Skip to main content
POST
Create a person
Creates an active person with no sign-in and no role grant, and returns 201 with the person. With createSeat: true it also creates an active worker seat (only for EMPLOYEE or CONTRACTOR; otherwise 409 (PERSON_NOT_SEATABLE)). An email another person in reach already uses returns 409 (DUPLICATE_DECISION_REQUIRED) until you send duplicateDecision: LINK or MERGE answers that person, KEEP_SEPARATE creates a second person and records the decision, and the message names that person (conflicting person <id>). A person out of reach (any seat in a customer organization or under one) never matches: the create answers exactly as it would for an unused email, and the Console’s workforce integrity review reports the two people sharing the email. A duplicateDecision.personId out of reach returns 404. 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 with no email creates a second person.

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

The person's name.

Minimum string length: 1
userType
enum<string>
required
Available options:
EMPLOYEE,
CONTRACTOR,
OTHER,
EXTERNAL
createSeat
boolean
required

Also create an active worker seat (EMPLOYEE or CONTRACTOR only).

reason
string
required

Why the person is created (recorded in the audit).

Minimum string length: 1
email
string

Primary email, stored lowercased. An address another person in reach already uses needs duplicateDecision; a person out of reach never matches.

Minimum string length: 1
displayName
string
timezone
string

An IANA time zone, e.g. America/Denver.

duplicateDecision
object

Your decision when email matches an existing person: LINK or MERGE answers that person; KEEP_SEPARATE creates a second person and records the decision.

Response

Success

data
object
required
meta
object
required