Create a verification

Submits an identity for verification and returns at once. The checks run asynchronously: receive the outcome by webhook, or poll the status endpoint.

A 202 means a new verification was created. A 200 with the same body shape means metadata.requestId matched an earlier submission and that verification is returned instead; nothing new is created or charged.

An accepted submission can still end declined or in error later (an ID not found, a face mismatch, insufficient credit). Those outcomes arrive on the status endpoint and webhooks with a reason and reasonCode, never as an HTTP error here.

Send the business block for a business verification, or idChecks for a workflow that verifies several IDs. Both require a published workflow. A hosted verification session token is also accepted in place of an API key.

Error codes

`error`	Status	Meaning
`Invalid request body`	400	The body failed validation. `details` lists each problem.
`invalid_sandbox_outcome`	400	`metadata.sandboxOutcome` is not a known test outcome.
`invalid_media`	400	An uploaded file is unknown, expired or already used. `mediaKey` names it when known.
`country_mismatch`	400	The country is not offered by the business or scoped workflow.
`country_not_supported`	400	The country is not accepted by the address workflow.
`product_unsupported`	400	The business product is not offered by the workflow for that country.
`Forbidden`	403	The `requestId` belongs to another organisation or environment.
`mobile_device_required`	403	The workflow only runs on a mobile device.
`business_verifications_disabled`	403	Business verification is switched off for the organisation.
`workflow_not_found`	404	A business or scoped submission named no published workflow of the right kind.
`request_id_conflict`	409	The `requestId` was already used for a different verification.
`session_cancelled`	409	The session named in `sessionId` has been cancelled.
`session_unavailable`	409	The session has closed and its workflow refuses late submissions.
`applicant_session_required`	409	An applicant identity submission must resume its business application.
`verification_in_progress`	409	A resubmission for this verification is still being checked.
`resubmission_superseded`	409	The verification has already been resubmitted.
`resubmission_withdrawn`	409	The resubmission link is no longer in use.
`handoff_session_used`	409	The hosted session has already been submitted.
`only_test_ids_allowed`	422	A sandbox key was used with a number that is not a published test ID.
`workflow_subject_mismatch`	422	The submission kind does not match the workflow.
`questionnaire_invalid`	422	Questionnaire answers failed validation. `issues` lists them.
`contact_verification_required`	422	A required email or phone proof is missing. `missing` lists which.
`missing_supporting_documents`	422	A required supporting document is missing. `missing` lists which.
`address_collection_required`	422	The workflow requires an address pin.
`proof_of_address_required`	422	The address workflow requires a proof-of-address document.
`missing_address_fields`	422	Required address fields are missing. `missing` lists which.
`invalid_id_checks`	422	`idChecks` does not fit the workflow multiple-ID plan.
`multi_id_required`	422	The workflow verifies several IDs and `idChecks` was not sent.
`registration_name_required`	422	The business workflow requires the registered name.
`missing_documents`	422	A required company document is missing.
`missing_company_info`	422	Required company details are missing.
`key_people_required`	422	Too few key people were declared.
`key_person_email_required`	422	A key person who must be invited has no email address.
`user_reference_required`	422	A biometric submission did not name its subject.
`selfie_required`	422	A biometric submission carried no selfie.
`questionnaire_required`	422	A questionnaire submission carried no answers.
`not_enrolled`	422	The subject has no biometric enrolment to authenticate against.
`rate_limited`	429	The hourly verification limit for the organisation was reached.
`pricing_not_configured`	500	No price is configured for this check. Contact support.
`Missing or invalid Authorization header`	401	No bearer credential was sent.
`Invalid API key`	401	The key is unknown or revoked.
`environment_mismatch`	403	The key belongs to an environment this host does not serve.
`origin_not_allowed`	403	The request origin is not on the publishable key allowlist.
`ip_not_allowed`	403	The caller address is not on the secret key allowlist.
`organization_suspended`	403	The organisation is suspended.
`business_not_approved`	403	A production key was used before the business was approved.

Accepts a publishable (pk_) or secret (sk_) key.

Authentication

AuthorizationBearer

Send the API key as a Bearer token. Each operation states whether a publishable key is enough or a secret key is required.

Request

This endpoint expects an object.

countrystringRequired=2 characters

ISO 3166 alpha-2 country code of the ID.

idTypestringRequired>=1 character

The ID type, for example bvn or passport. For a business submission, send the lookup product here.

metadataobjectRequired

Request metadata. Any key other than those listed is stored as your own customer metadata and echoed on responses and webhooks.

idNumberstringOptional

The ID number. Required for number-based ID types and omitted for document-only flows.

userDataobjectOptional

Applicant details to compare with the record.

mediaIdsobjectOptional

References to files uploaded with the upload endpoint.

idCheckslist of objectsOptional

Two or three ID checks for a workflow that verifies several IDs in one run. The first entry is the primary.

businessobjectOptional

Present for a business verification. Requires a published business workflow.

workflowIdstringOptional<=64 characters

The published workflow that configured this submission. Ignored when unknown, except for business and scoped submissions, which require it.

sessionIdstringOptional<=64 characters

The session this submission belongs to. The verification takes the same identifier.

externalUserIdstringOptional1-190 characters

Your own stable reference for the person or business being verified.

livenessModeenumOptional

The liveness method the client ran. A workflow setting takes precedence.

Allowed values:

proofOfAddressTypeenumOptional

What kind of document mediaIds.proofOfAddress is.

Allowed values:

nfcobjectOptional

Data read from the chip of an electronic passport or identity card. Dropped without error when the document has no verifiable chip or the workflow does not run the chip step.

addressobjectOptional

The applicant address pin collected on the address step. Dropped without error when the workflow does not collect an address.

supportingDocumentslist of objectsOptional

Supporting documents the workflow asks the applicant to provide. Documents the workflow did not ask for are dropped.

contactobjectOptional

Proofs that the applicant confirmed their contact details.

questionnairemap from strings to strings or doubles or booleans or lists of stringsOptional

Answers to the workflow questionnaire, keyed by question key.

userIdstringOptional1-190 charactersDeprecated

Legacy alias of externalUserId.

Response

An earlier submission with the same requestId was returned.

verificationIdstring

The verification identifier.

statusstring

processing for a new submission. On a repeated requestId this is the existing verification check result: pending, verified, failed, not_found or error.

externalUserIdstring or null

Your reference for the subject, as stored.

metadatamap from strings to any or null

Your customer metadata, as stored. Bounded: at most 16 KiB, four levels deep and 100 keys.

applicantKeyPersonIdstring or nullOptional

Business submissions only. The reference to send as userId on the applicant identity submission that follows, or null when the workflow does not verify the applicant.

keyPeopleInviteslist of objectsOptional

Business submissions only. Verification links for the key people the applicant listed.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error