Candidates

The people you invite, one record per email.

You rarely need to create candidates directly: creating an invitation creates or updates the candidate for you. Use these endpoints to keep your own ids and tags in sync.

The candidate object

Field	Type
`id`	string	`cand_…`
`object`	`"candidate"`
`email`	string	Unique within your organisation
`name`	string
`phone`	string or null
`external_id`	string or null	Your id, for example from your ATS
`tags`	string[]	Up to 20
`metadata`	object	Your own key-value data
`livemode`	boolean
`created_at`, `updated_at`	timestamp

List candidates

GET /candidates needs candidates:read. Filters: email, external_id, created_gte, created_lt, plus pagination.

Create a candidate

POST /candidates needs candidates:write.

Field
`email`	required
`name`	required	Up to 200 characters
`phone`	optional	Up to 40 characters
`external_id`	optional	Up to 200 characters
`tags`	optional	Up to 20 strings
`metadata`	optional	Object

An email that already exists in the other mode returns 409 candidate_exists_in_other_mode.

Retrieve a candidate

GET /candidates/{id} needs candidates:read.

Update a candidate

PATCH /candidates/{id} needs candidates:write. Send any of name, phone, external_id, tags, metadata. The email cannot change.

Delete a candidate

DELETE /candidates/{id} needs candidates:write. Only a candidate who was never invited can be deleted; otherwise you get 409 candidate_has_sessions.