RErecruitwithatlas
People

Update a person

Changed on

Use this endpoint to update an existing person in your Atlas account.

This endpoint changes only the parts of a person that are applied immediately — fields on the person record (name, gender, headline, location, source), their contact details (identities), and their custom attribute values. Work experience, education and compensation are not handled here — set them on POST /api/v1/people, where they are created via background jobs.

Every field is optional — send only what you want to change. An omitted field is left untouched; sending null on a nullable field clears it. At least one updatable field must be present.

Identities are additive. Any identities you send are added to the person — existing ones are never removed. An identity already on this person is ignored; an identity that belongs to a different person fails with 409 Conflict (conflictType: "identity") and returns that person's personId. Updating identities requires addedByEmail (the acting user).

source.externalId uniqueness. A (source.system, source.externalId) pair is unique within your agency. Setting source to a pair that already belongs to a different person fails with 409 Conflict (conflictType: "externalId") and returns that person's personId — even when no identities are supplied. Re-sending the pair already stored on the person being updated is fine.

Custom attributes are replaced per attribute. For every customAttributeId you send, the person's existing values for that attribute are removed and the supplied ones written. Attributes you don't mention are left as-is. (Clearing an attribute by sending it empty is not supported here.)

Company contact. Send isContact: true to link the person to their headline company when they are not a contact yet — the link is created synchronously and is present on an immediate GET /api/v1/people/{id}. The company comes from headline.company / headline.companyId in this same request, or from the headline company already stored on the person; with neither the request fails with 422. A person who is already a contact is left untouched (no-op). isContact: false is rejected with 422 — unlinking a contact is not supported here, and the request is refused rather than silently ignored. The response field companyContactCreated is 1 when this request created the link and 0 otherwise.

Attribution. addedByEmail is optional and records which Atlas user made the change; if omitted the update is unattributed (but is required when changing identities).

patch/api/v1/people/{id}

Request

Path parameters

idstring uuid required

Atlas person ID

Example:123e4567-e89b-12d3-a456-426614174000

Request body

firstNamestring nullable

First name

lastNamestring nullable

Last name

gender'male' | 'female'

Gender

candidateStatus'omitted' | 'applied' | 'sourced' | 'regular'

Candidate status classification: omitted (outbound-only, unresponsive), applied (created from an application), sourced (created via sourcing, still in a sourcing stage), regular (everyone else).

overviewstring nullable

Free-text overview/summary of the person. null clears it.

addedByEmailstring email

Email of the Atlas user the update is attributed to. Optional — required only when updating identities. If omitted, the update is unattributed.

isContactboolean

If true, creates the company-contact link when the person has none. Requires a headline company — headline.company / headline.companyId in this request, or one already stored on the person and still existing; otherwise the request fails with 422. Already-a-contact is a no-op. false is rejected with 422: unlinking a contact is not supported here.

Example request

{
  "firstName": "Michael",
  "lastName": "Scott",
  "gender": "male",
  "candidateStatus": "regular",
  "overview": "Senior backend engineer, 10 years in fintech, open to contract roles.",
  "addedByEmail": "jordan@recruitwithatlas.com",
  "source": {
    "system": "api",
    "externalId": "124456"
  },
  "identities": [
    {
      "type": "email",
      "value": "mscott@gmail.com",
      "isPersonal": true,
      "isPrimary": true
    }
  ],
  "headline": {
    "role": "Regional Manager",
    "company": "Dunder Mifflin",
    "companyId": "550e8400-e29b-41d4-a716-446655440000",
    "roleStartedAt": "2023-04-01"
  },
  "location": {
    "name": "London, UK",
    "locality": "London",
    "region": "England",
    "metro": "new york, new york",
    "country": "United Kingdom",
    "streetAddress": "123 Baker Street",
    "addressLine2": "Suite 200",
    "postalCode": "NW1 6XE",
    "raw": "123 Baker Street, London NW1 6XE, United Kingdom",
    "latitude": 51.523767,
    "longitude": -0.158519
  },
  "isContact": true,
  "customAttributes": [
    {
      "customAttributeId": "550e8400-e29b-41d4-a716-446655440000",
      "value": "Some text value"
    },
    {
      "customAttributeId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "optionId": "9b2e4d6a-1c3f-4a8b-9e7d-2f1a6c5b4d3e"
    }
  ]
}

Response

Person updated. All changes are applied synchronously.

status'ok' required

Changes

  • cd4bc8bbd95eRevision changes
    • info

      added the optional property to the response with the status

  • bfc1118eeb5dRevision changes
    • info

      added the new optional request property

    • info

      added the required property / to the response with the status