Skip to main content
POST
Add an email claim to a person
Claims a secondary email address for the person (verification admin_assigned, provider api), or returns the person’s existing claim on it with created: false. The first verified sign-in with a claimed address binds an unbound person, so each new claim is recorded on the person’s history with its claim ID, never the address. An address that is another person’s primary email or active claim returns 409; the message names that person only when they are in reach. A new claim returns 201. 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 200 with created: false.

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
email
string<email>
required

A secondary email address for the person.

Response

Success

data
object
required
meta
object
required