Skip to navigation
Quickstarts

Quickstart

Looking for transaction decisions, customer screening, continuous monitoring or Travel Rule? Use the Risk Intelligence quickstart.

This guide takes you through a full verification using curl. By the end you will have created an API key, discovered your enabled ID types, uploaded a selfie, submitted a verification, and read the result.

Building an app or website flow? You usually don’t need the raw API. Build a workflow in the dashboard and mount it with an SDK (workflowId="wf_…"), or share its hosted link with zero integration. This page walks the API underneath, for server-side integrations and for understanding what the SDKs do.

We use the sandbox environment (pk_test_… keys against https://api.toden.co/api/kyc) so you can test freely without affecting production. Sandbox and production share the same base URL, and your key prefix decides which environment you hit.

1. Create a test API key

In the dashboard, go to Settings → Organization → Developers → API Keys, switch the environment selector to Sandbox, and create a key. Copy the full key (pk_test_…); it is shown only once.

Store it in your shell:

export TODEN_KEY="pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export TODEN_BASE="https://api.toden.co/api/kyc"

2. Check your configuration

GET /config returns the ID types enabled for your organisation and which features each supports.

curl "$TODEN_BASE/config" \
  -H "Authorization: Bearer $TODEN_KEY"
{
  "environment": "SANDBOX",
  "idTypes": [
    {
      "country": "NG",
      "idType": "bvn",
      "features": { "documentVerification": false, "livenessCheck": true, "govDbCheck": true }
    }
  ]
}

3. Upload media (optional)

Number-only IDs (such as BVN) don’t need media. For document or selfie/liveness flows, upload each file and keep the returned mediaId.

curl "$TODEN_BASE/upload" \
  -H "Authorization: Bearer $TODEN_KEY" \
  -F "type=selfie" \
  -F "file=@./selfie.jpg"
{ "mediaId": "media_01j9..." }

4. Create the verification

Submit the ID details. The metadata.requestId is your idempotency key: reuse it to safely retry without creating duplicates.

curl "$TODEN_BASE/verify" \
  -H "Authorization: Bearer $TODEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "NG",
    "idType": "bvn",
    "idNumber": "12345678901",
    "metadata": { "requestId": "order_1001", "userId": "user_42" }
  }'

The API responds immediately with 202 Accepted:

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

5. Get the result

Verification runs asynchronously. The publishable key polls minimal status (no PII):

curl "$TODEN_BASE/status/ver_01j9..." \
  -H "Authorization: Bearer $TODEN_KEY"
{
  "verificationId": "ver_01j9...",
  "status": "approved",
  "checkStatus": "verified",
  "createdAt": "2026-04-27T12:00:00.000Z",
  "completedAt": "2026-04-27T12:00:05.000Z"
}

To read the full result (biodata, ID number, facial match), call the result endpoint from your backend with a secret (sk_) key, never from client code:

curl "$TODEN_BASE/verifications/ver_01j9..." \
  -H "Authorization: Bearer $TODEN_SECRET_KEY"
{
  "verificationId": "ver_01j9...",
  "status": "approved",
  "checkStatus": "verified",
  "country": "NG",
  "idType": "bvn",
  "result": {
    "firstName": "JOHN",
    "lastName": "DOE",
    "dateOfBirth": "1990-01-01",
    "idNumberMasked": "1234•••901",
    "facialMatch": null
  },
  "completedAt": "2026-04-27T12:00:05.000Z"
}

Better still, receive the result on your backend via a webhook.

Next steps