Skip to main content
POST
Link an identity to a person
Links a Slack, email, GitHub, Google Workspace, Okta, Rippling, Microsoft Entra or Freshservice identity to an active person; reason is recorded in the audit. WorkOS sign-in bindings are managed in the Console and return 400. A Freshservice link names the technician (technicianId), the synchronized Freshservice Knowledge source they belong to (freshserviceSourceId) and the org unit that source is homed at (orgUnitId), instead of externalId and duplicateDecision; the identity is derived from the source’s account (<account>.freshservice.com:<technician>), so a repeat finds the same identity. As in the Console, it needs knowledge:read at that org unit: the credential’s scopes must include knowledge:read (else 403 naming it before anything runs), and the grant must cover the org unit (else 403 naming knowledge:read, and nothing is read or written). An org unit out of reach returns 404 “Org unit not found”; a source that is not that unit’s active, synchronized Freshservice source returns 404 “Freshservice Knowledge source not found”. Mixing the two shapes returns 400. An identity another person holds returns 409 (EXTERNAL_IDENTITY_ALREADY_LINKED). An email that matches another person returns 409 (DUPLICATE_DECISION_REQUIRED) until you send duplicateDecision: LINK links the identity to that person, KEEP_SEPARATE links it here and records the decision, and MERGE returns 409 (PERSON_MERGE_PREVIEW_REQUIRED). A conflict names the other person (conflicting person <id>) only when that person is in reach, and a duplicateDecision.personId out of reach returns 404. A new link 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 outcome: ALREADY_LINKED.

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
provider
enum<string>
required

The identity provider.

Available options:
slack,
email,
github,
google_workspace,
okta,
rippling,
microsoft_entra
externalId
string
required

Every provider but freshservice: the provider's ID for the person; a Slack ID is workspace-qualified (T…:U…), an email identity is the address.

Minimum string length: 1
reason
string
required

Why the identity is linked. Recorded in the audit.

duplicateDecision
object

Every provider but freshservice: your decision when the identity's email matches another person: LINK links it to that person, KEEP_SEPARATE links it here and records the decision, MERGE is refused until you preview and merge the two people.

Response

Success

data
object
required
meta
object
required