Skip to main content
POST
Merge two people
Moves the loser’s seats, identity claims, role grants and person-keyed rows to the winner and leaves the loser as an inactive redirect; reason (1–500 characters) is recorded in the audit. This cannot be undone: there is no unmerge, and a role grant both people hold is kept once and the loser’s copy is deleted. Call Preview person merge first; the merge plans again and does not consume the preview. A pod ownership both people hold returns 409 (POD_OWNER_MERGE_CONFLICT). Both people must be in reach: 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 self-merge returns 400; an already merged loser, or a winner merged into someone else, returns 409. The credential’s scopes must include workforce:read as well as workforce:manage, because the success returns the person; 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. 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 every 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 because the loser is already merged.

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

Body

application/json
winnerId
string
required

The person who remains.

Minimum string length: 1
loserId
string
required

The person merged into the winner; it becomes an inactive redirect.

Minimum string length: 1
reason
string
required

Why the two people are one. 1–500 characters (trimmed); recorded in the audit.

Response

Success

data
object
required
meta
object
required