Skip to navigation
Identity verification APIIdentity Checks

Run a one-off identity check

Verifies a person’s ID without the SDK capture flow. The check runs in the background: the response is 202 with a verificationId, and the result is ready shortly afterwards on the detail endpoint. No webhook is sent for a one-off check.

A requestId you have used before returns the existing check with 202 and runs nothing new.

Sandbox. A sandbox key accepts only the published test IDs (for example BVN 00000000001) and answers a real ID with 422 only_test_ids_allowed. A development key accepts test IDs and real IDs. Test checks return simulated results and are never charged.

Billing. Production checks are charged for the parts that run: the record lookup, the document read when a document is sent, and the facial comparison when a selfie is sent. A check that ends in error because of a fault on our side is refunded.

Error codes

errorStatusMeaning
invalid_input400The body failed validation, a slot was sent in both mediaIds and images, or neither an ID number nor a document front was sent.
invalid_image400An inline image is not an https URL, a data URI or base64, or is too short to be a photo.
unsupported_media_type400The bytes are not a JPEG, PNG or WebP photo. The format is read from the bytes.
image_too_large400The photo is larger than 25 MB.
image_url_not_allowed400The image URL is not http(s), or resolves to a non-public address.
image_fetch_failed400The image URL could not be fetched, returned nothing, or redirected too many times.
spot_checks_disabled403One-off checks are not enabled for your organisation.
spot_check_unavailable403This ID type is currently unavailable for one-off checks.
id_type_not_enabled403The ID type or a feature it needs is not enabled for your organisation. scope says which: id_type, document_verification or gov_db_check.
secret_key_required403A publishable key was used. This endpoint accepts secret keys only.
environment_mismatch403The key belongs to an environment this deployment does not serve.
ip_not_allowed403The key has an IP allowlist and the calling address is not on it.
organization_suspended403The organisation is suspended. The response carries reason and suspendedAt.
business_not_approved403A live key was used before the business was approved for production.
organization_not_found404The organisation behind the key no longer exists.
only_test_ids_allowed422A sandbox key sent an ID number that is not a published test ID.
rate_limited429The hourly verification limit for your organisation was reached.
pricing_not_configured500No price is configured for this check. Contact support.

A missing or unknown key answers 401, where error is a short sentence rather than a code.

Requires a secret (sk_) key. A publishable key receives 403 secret_key_required.

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.
countryenumRequired
The country that issued the ID.
Allowed values:
idTypestringRequired>=1 character

The ID type, for example bvn, nin or passport. It must be enabled for your organisation.

consenttrueRequired
Must be true. You attest that the person consented to the check.
idNumberstringOptional>=1 character

The ID number. Required for number-only IDs. A document ID may send the document front instead, and the number is read from it.

externalUserIdstringOptional1-255 characters
Your own reference for the subject. A verified check is recorded against that customer record.
createEntitybooleanOptionalDefaults to true
Whether to save the verified subject as a customer record. Defaults to true. Send false to run the check without creating or updating a record.
userDataobjectOptional
Details to compare against the record the check finds.
mediaIdsobjectOptional

Photos already uploaded through the upload endpoint. Send each slot here or in images, never both.

imagesobjectOptional
The same photos inline, each as an https URL, a data URI or base64.
requestIdstringOptional8-120 characters
Your idempotency key. A retry with the same value returns the same check and never runs or bills a second one.

Response

The check was accepted and is being processed.
verificationIdstring
The id of the check. Read the result from the matching detail endpoint.
statusenum

Always pending at submission. The check is processed in the background.

Allowed values:

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error