Skip to navigation
Server API guides

Spot checks

For manual crypto investigations, open Spot Checks → Wallet in the dashboard. Enter a wallet address for an on-demand risk result and case actions. Backend integrations can use the On-Demand Wallet Screening API. Transaction Monitoring uses the same engine to screen crypto counterparties automatically.

POST /api/kyc/checks/individual
POST /api/kyc/checks/business
GET  /api/kyc/checks/individual
GET  /api/kyc/checks/business
GET  /api/kyc/checks/individual/:id
GET  /api/kyc/checks/business/:id

Run a one-off check without the SDK capture flow: verify a person’s ID number against the government database, or a business registration number against the registry. This is the server-to-server counterpart of the dashboard’s Spot Checks tabs — the same gates, pricing and sandbox behaviour, and the same history (API checks appear there labelled “API”).

Authentication: Authorization: Bearer sk_… (secret keys only, for the whole surface). Results carry PII, so this never belongs in client-side code. Production note: sk_live_ keys require an approved business. Sandbox and development checks are free and serve test data.

Checks run asynchronously: the submit returns 202 with a verificationId within milliseconds, and the result is ready seconds later on the detail endpoint.

Individual checks

POST /api/kyc/checks/individual
FieldRequiredDescription
countryyesNG, GH, KE, ZA or CI (the government-database markets).
idTypeyesThe ID type, e.g. bvn, nin, passport. See Countries & ID types.
idNumberno*The ID number. Required for number-based IDs; a document ID may instead send the document front for extraction.
userDatanoDetails to validate against the government record: firstName, lastName, dateOfBirth.
mediaIdsnoPre-uploaded photos from POST /upload: documentFront, documentBack, selfie. A selfie adds the facial comparison against the record photo.
imagesnoThe same three slots inline instead of pre-uploaded: each an https URL, a data URI, or base64 — the same forms the face match endpoint takes. Send each slot as mediaIds or images, never both.
consentyesMust be true: you attest the person consented to the check.
requestIdnoYour idempotency key. A retry with the same value returns the same check instead of running (and billing) a second one. Recommended.
externalUserIdnoYour own reference for the person. A verified check is saved on the customer record with that reference.
createEntitynoDefaults to true: a verified check is saved as a customer record. Without externalUserId, it is saved on the record that already holds this ID number, or as a new record. Send false to keep the result in spot-check history only. If you later send the same ID number with your own reference (a verification, a check or the entity API), the record created here is renamed to that reference rather than duplicated.
curl -X POST https://api.toden.co/api/kyc/checks/individual \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "NG",
    "idType": "bvn",
    "idNumber": "12345678901",
    "userData": { "firstName": "John", "lastName": "Doe" },
    "consent": true,
    "requestId": "check-user-42-2026-08-20"
  }'
# → 202 { "verificationId": "cmt…", "status": "pending" }

Then read the result:

GET /api/kyc/checks/individual/:id
{
  "check": {
    "id": "cmt…",
    "status": "verified",
    "country": "NG",
    "idType": "bvn",
    "idNumber": "12345678901",
    "result": {
      "firstName": "JOHN",
      "lastName": "DOE",
      "dateOfBirth": "1990-01-01",
      "dataMatch": true,
      "facialMatch": { "match": true, "confidence": 85 }
    },
    "govRecord": { "…": "customer-safe record extract" },
    "media": { "selfie": "https://api.toden.co/api/kyc/verifications/…/media/selfie" },
    "chargedAmount": "0.0500",
    "createdAt": "…",
    "completedAt": "…"
  }
}

status is pending until processing finishes, then verified, failed, not_found or error with reason and a stable reasonCode. result is present on verified only.

Business checks

POST /api/kyc/checks/business
FieldRequiredDescription
countryyesISO-2 country code (about 48 registry countries are supported).
registrationNumberyesThe registration number (e.g. RC123456).
registrationNamenoThe registered name, cross-checked against the registry when given.
subdivisionCodemaybeISO 3166-2 region (e.g. US-DE) — required for the countries whose registry is split by region (US, IN, CA, AE) and rejected elsewhere.
productnoThe check product; defaults to the standard business check. Nigeria adds tax-related products.
consentyesMust be true.
requestIdnoYour idempotency key, as above.
externalUserIdnoYour own reference for the business. A verified check is saved on the customer record with that reference.
createEntitynoDefaults to true: a verified check is saved as a customer record. Without externalUserId, it is saved on the record that already holds this registration number, or as a new record. Send false to keep the result in spot-check history only. If you later send the same ID number with your own reference (a verification, a check or the entity API), the record created here is renamed to that reference rather than duplicated.
sandboxOutcomenoverified or not_found — pins the canned result outside production. Silently ignored on live keys.

The detail (GET /api/kyc/checks/business/:id) returns the registry’s answer as businessRecord: company particulars, status, share capital and key personnel in a customer-safe extract, plus businessName, the product, and the region the registry was asked about.

History

GET /api/kyc/checks/individual
GET /api/kyc/checks/business

Paginated, newest first, scoped to your organisation and the key’s environment. Query parameters: status (pending / verified / failed / not_found / error), country, idType (individual) or product (business), from / to (ISO dates), page, pageSize (max 100). Rows are light — identifiers, status, cost, timestamps and initiatedVia (api or dashboard) — with the full result on the detail endpoints.

A check you no longer want in your history can be removed with DELETE /api/kyc/checks/individual/:id or DELETE /api/kyc/checks/business/:id. See Delete records: the delete is soft, and a check that is still running is refused with 409 check_in_progress.

Errors

StatusCodeMeaning
400invalid_inputThe body failed validation, or a slot was sent both as mediaIds and images.
400product_unsupportedThat product is not offered for the country.
400subdivision_required / subdivision_unsupported / subdivision_unknownThe registry-region rule above.
400invalid_image / unsupported_media_type / image_too_large / image_url_not_allowed / image_fetch_failedAn inline image problem — same rules as face match.
402insufficient_creditsYour balance cannot cover the check.
403spot_checks_disabled / business_checks_disabledThe module is not enabled for your organisation.
403id_type_not_enabledThe ID type is not granted to your organisation, or the required feature is disabled.
403spot_check_unavailableThe ID type is temporarily switched off for spot checks.
403secret_key_requiredA publishable key was used; this surface is secret-key only.
403business_not_approvedA live key before KYB approval.
422only_test_ids_allowedA sandbox key sent a real ID number; use the published test IDs.
429rate_limitedThe hourly verification cap was reached; retry later.