Skip to navigation
Identity verification APIContact Verification

Send a one-time code

Sends a one-time code to an email address or phone number and returns the challenge, with what is known about the contact. Codes are valid for five minutes.

Sandbox. On sandbox and development keys nothing is sent. The code is all zeros at the length you asked for (000000 by default) and deliveryChannel is test.

Billing. Nothing is charged for sending. The check is charged when a code is accepted, in production only. In production the send is refused with 402 when your balance cannot cover that charge; the response then also carries required and balance as decimal strings.

Limits. Five codes per destination per hour, and an hourly ceiling per organisation across all destinations.

Error codes

errorStatusMeaning
invalid_request400The body failed validation. message says what.
invalid_destination400The phone number could not be parsed. Send country for national formats.
insufficient_credits402Your balance cannot cover the 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.
send_rate_limited429A send limit was reached.
pricing_not_configured500No price is configured for this check. Contact support.
send_failed502The message could not be handed to its delivery channel. Nothing was charged.

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.
channelenumRequired
What to verify.
Allowed values:
destinationstringRequired3-254 characters

The email address or phone number. A phone number in national format is resolved against country.

countrystringOptional=2 characters

ISO 3166-1 alpha-2. Resolves national phone formats and selects the price. It is stored and reused when the check is charged.

viaenumOptional

The preferred phone delivery. whatsapp is accepted and currently delivers by SMS.

Allowed values:
codeLengthintegerOptional1-20
Digits in the code. Values are brought into the range 4 to 8. Defaults to 6.
maxAttemptsintegerOptional1-20
Wrong codes allowed. Values are brought into the range 1 to 5. Defaults to 3.
externalUserIdstringOptional1-190 characters
Your own reference for the person. A verified contact is recorded against their existing record. No record is created.

Response

The code was sent.
contactVerificationobject

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error
502
Bad Gateway Error