Skip to main content
PATCH
Save a person's communication profile
Saves a new revision of the person’s communication profile; reason is recorded on the revision and in the audit. Send the whole payload and the expectedCurrentRevisionId you read (omit it only for the first save); a stale value returns 409 (PERSON_PROFILE_REVISION_CONFLICT). payload.automationAuthorization.organizationId must be an org unit that is not a customer organization or under one; otherwise 404 Org unit not found. An inactive person returns 409 (PERSON_NOT_ACTIVE), and a payload outside the profile’s limits returns 400 with its PERSON_PROFILE_* code. The credential’s scopes must include workforce:read as well as workforce:manage, because the success returns the person’s record; otherwise 403 naming workforce:read, and nothing changes. Requires workforce:manage at the platform scope; a key or app whose grant covers only some org units receives 403. A person with any seat in a customer organization or an org unit under one returns 404, exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into. Send an Idempotency-Key to make a retry safe: a same-key retry within 24 hours returns the recorded result only while your scopes still include workforce:read, you still hold workforce:manage at the platform scope, and the person the result names is still in reach; otherwise 409 idempotency_result_unavailable, and the change is never made twice (see Idempotency). Without a key, a repeat returns 409 (PERSON_PROFILE_REVISION_CONFLICT) because the revision moved.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Path Parameters

personId
string
required

The person's ID (a merged-away ID resolves to the person it was merged into).

Minimum string length: 1

Body

application/json
payload
object
required
reason
string
required

Why the profile changes. Recorded in the audit.

expectedCurrentRevisionId
string

The current revision you are replacing; omit it only for the first save. A stale value is refused (PERSON_PROFILE_REVISION_CONFLICT).

Minimum string length: 1

Response

Success

data
object
required
meta
object
required