Skip to main content
POST
Create ID Check

Authorizations

x-api-key
string
header
required

Each key carries scopes chosen when it is created: candidates:read, candidates:write, assessments:read, assessments:write, problems:read, problems:write, results:read, id_checks:read, id_checks:write. Keys created before scopes existed have full access. A request with a key that lacks an operation's scope returns 403 naming the missing scope.

Headers

Idempotency-Key
string

Optional key for safely retrying the same request

Maximum string length: 255

Body

application/json
candidateId
string

The candidate to verify. Send this or email, not both.

Required string length: 1 - 255
email
string<email>

The candidate's email. Resolves to your most recently created candidate with that email.

Maximum string length: 320
expirationDays
integer

Days until the check expires (default 30).

Required range: 1 <= x <= 30
maxRetries
integer

Guided retries after a recoverable decline (default 3, so 4 attempts).

Required range: 0 <= x <= 3
startScoutIfNone
boolean

Start a first Scout run on completion when the candidate has none. Defaults to the organization's setting.

inviteEmailLocale
enum<string>

Language of the invite and reminder emails (default en).

Available options:
en,
fr
metadata
object

Your own key-value pairs, returned as sent. At most 20 keys; values up to 500 chars.

Response

Idempotent replay of an earlier request

id
string
required

The ID check identifier.

candidateId
string
required
status
enum<string>
required

sent: emailed, not started. in_progress: the candidate is verifying or retrying. processing: awaiting the decision. verified, failed, expired and canceled are final.

Available options:
sent,
in_progress,
processing,
verified,
failed,
expired,
canceled
failure
object | null
required

Why the check or attempt failed. Null unless it failed.

attemptCount
integer
required

Decided verification sessions. Each one is billed.

maxRetries
integer
required
attempts
object[]
required

Verification sessions, oldest first.

continuity
object | null
required

Face continuity across the candidate's screens, from their latest Scout run. Null until Scout has run.

metadata
object
required
createdAt
string<date-time>
required
expiresAt
string<date-time>
required
completedAt
string<date-time> | null
required