Your First Verification

This guide walks you through making your first eKYC verification call end-to-end — from getting your API key to interpreting the result. Total time: under 5 minutes.

This guide uses the sandbox environment. Sandbox calls return approved instantly and are completely free. No real identity data is processed.

Step 1 — Get your API key

If you don't have a sandbox API key yet, create one in under 60 seconds. No credit card required.

Get a free sandbox key →

Your sandbox key looks like: dme_sandbox_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Store it in an environment variable — never hardcode it in source code:

Terminal

export DME_API_KEY=dme_sandbox_your_key_here

Step 2 — Submit a verification

Call POST /v1/kyc/sandbox/verify with the identity details. In the sandbox, any syntactically valid request returns approved instantly.

curl -X POST https://api.d-id.me/v1/kyc/sandbox/verify \
  -H "Authorization: Bearer dme_sandbox_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "id_type": "national_id",
    "country": "SN",
    "id_number": "1234567890123",
    "first_name": "Amara",
    "last_name": "Diallo",
    "date_of_birth": "1990-05-15",
    "external_ref": "user_001",
    "score_requested": false
  }'

Request fields

Field	Type	Required	Description
`id_type`	string	Yes	`national_id`, `passport`, or `voter_id`
`country`	string	Yes	ISO 3166-1 alpha-2 (`SN`, `MA`)
`id_number`	string	Yes	The document number
`first_name`	string	Yes	As it appears on the document
`last_name`	string	Yes	As it appears on the document
`date_of_birth`	string	Yes	ISO 8601 (`YYYY-MM-DD`)
`external_ref`	string	No	Your internal user/session ID (returned in webhook)
`score_requested`	boolean	No	Request a Skorix credit score alongside the verification (default: `false`)

Step 3 — Read the response

A successful submission returns 202 Accepted in production (async job queued) or 200 OK in sandbox (instant result). The response body:

{
  "data": {
    "id": "ver_01hxyz1234567890",
    "status": "approved",
    "country": "SN",
    "id_type": "national_id",
    "external_ref": "user_001",
    "created_at": "2026-05-01T10:30:00Z",
    "completed_at": "2026-05-01T10:30:00Z",
    "score": null
  }
}

Status values

Status	Meaning
`pending`	Verification submitted, processing in progress (live only)
`approved`	Identity verified successfully
`declined`	Verification failed — identity could not be confirmed
`error`	Processing error, see `smile_result` for details

Step 4 — Poll for result or receive webhook

In the sandbox, the result is immediate — you can read it from the initial response. In live, verification takes 10–30 seconds. You have two options:

Option A: Poll the status endpoint

curl https://api.d-id.me/v1/kyc/verifications/ver_01hxyz1234567890 \
  -H "Authorization: Bearer dme_sandbox_xxxx"

Poll every 3 seconds, up to 5 times. If still pending after 15 seconds, the webhook will deliver the result when ready.

Option B: Receive a webhook

Webhook payload

{
  "event": "verification.completed",
  "data": {
    "id": "ver_01hxyz1234567890",
    "status": "approved",
    "external_ref": "user_001",
    "completed_at": "2026-05-01T10:30:00Z"
  },
  "timestamp": "2026-05-01T10:30:01Z"
}

See the Webhooks Guide to set up and verify webhook delivery.

Step 5 — Go live

Once your integration is tested in sandbox, activate live access. The only change needed in your code is the API key — swap dme_sandbox_ for dme_live_. Same endpoints, same request format, real results.

Going Live Checklist →