Create a verification

POST /api/kyc/verify

Submits an identity for verification. The request returns immediately with 202 Accepted and a verificationId; the actual verification runs asynchronously. Receive the outcome via webhooks or by polling GET /status/:id.

This call is also what fires verification.started. That is the submission event: it fires here, before any check has run, and is how your backend learns that somebody finished the flow.

Authentication: Authorization: Bearer pk_… (required). Content type: application/json. Production note: pk_live_ keys require an approved business.

Request body

* Whether idNumber and which mediaIds are needed depends on the ID type. Check its features from GET /config.

Optional header

Request

curl "https://api.toden.co/api/kyc/verify" \
  -H "Authorization: Bearer $TODEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "NG",
    "idType": "drivers-license",
    "idNumber": "ABC12345",
    "userData": { "firstName": "John", "lastName": "Doe", "dateOfBirth": "1990-01-01" },
    "mediaIds": { "documentFront": "media_01j9abc...", "selfie": "media_01j9def..." },
    "externalUserId": "user_42",
    "metadata": { "requestId": "order_1001", "loanId": "loan_20191" }
  }'

Response 202 Accepted

{
  "verificationId": "ver_01j9...",
  "status": "processing",
  "externalUserId": "user_42",
  "metadata": { "loanId": "loan_20191" }
}

externalUserId and metadata come back exactly as stored, so a retry of the same requestId returns the same values.

The verification is now queued. Track it via its verificationId.

processing is the same word Get verification status returns for this id a moment later. There is one status vocabulary across the whole API, so nothing changes meaning between the response that accepts a submission and the one that reports on it.

Calling from your backend

When you call this endpoint from your server with a secret key, the request reaches us from your server, not your user. We don’t treat your server as your user’s device: its address and user agent are kept for the record only, and no Device Intelligence signals are raised from them.

To have your user’s device and network analysed (country, network type, VPN and Tor checks, blocklists), pass their connection as you received it:

"metadata": {
  "requestId": "order_1001",
  "endUser": {
    "ipAddress": "102.89.34.10",
    "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) ...",
    "acceptLanguage": "en-NG,en;q=0.9"
  }
}

• Send the address your own server saw for your user, not your server’s address.
• A value we can’t read (for example an IP address that isn’t valid) is ignored. It never makes the request fail.
• endUser is ignored on a publishable key. Those calls come from your user’s own device, so we already see their connection.
• Without endUser or a device fingerprint, Device Intelligence has nothing to analyse, and it is not charged.

Idempotency

metadata.requestId is your idempotency key. If you submit a request with a requestId that already exists for your organisation, the API returns the existing verification instead of creating a new one:

{ "verificationId": "ver_01j9...", "status": "approved" }

Always send a stable requestId per logical verification so retries (timeouts, network errors) never create duplicates or double-charge you. Reusing another organisation’s requestId is not possible: a collision across orgs returns 403.

Errors