Create Identity Verification

curl -X POST https://sandbox.dhmad.tn/api/v1/identity-verifications \
  -H "Authorization: Bearer sk_sandbox_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "seller@example.com",
    "external_user_id": "seller_42",
    "redirect_url": "https://yourapp.com/onboarding/kyc-done",
    "metadata": { "source": "onboarding" }
  }'

const response = await fetch('https://sandbox.dhmad.tn/api/v1/identity-verifications', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_sandbox_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'seller@example.com',
    external_user_id: 'seller_42',
    redirect_url: 'https://yourapp.com/onboarding/kyc-done',
    metadata: { source: 'onboarding' }
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://sandbox.dhmad.tn/api/v1/identity-verifications',
    headers={
        'Authorization': 'Bearer sk_sandbox_your_api_key_here',
        'Content-Type': 'application/json'
    },
    json={
        'email': 'seller@example.com',
        'external_user_id': 'seller_42',
        'redirect_url': 'https://yourapp.com/onboarding/kyc-done',
        'metadata': {'source': 'onboarding'}
    }
)

data = response.json()

{
  "id": "6655abc1234567890abcdef12",
  "email": "seller@example.com",
  "external_user_id": "seller_42",
  "kyc_status": "pending",
  "didit_session_status": "in_progress",
  "needs_admin_review": false,
  "claim_status": "pending",
  "linked_user_id": null,
  "linked_at": null,
  "created_at": "2026-06-06T12:00:00.000Z",
  "updated_at": "2026-06-06T12:00:00.000Z",
  "expires_at": "2026-09-04T12:00:00.000Z",
  "verification_email_sent": true,
  "verification_email_sent_at": "2026-06-06T12:00:00.000Z",
  "message": "A verification email has been sent to the user."
}

Start Didit identity verification for a user who does not yet have a DHMAD account. DHMAD sends a verification email with the Didit link. The Didit session URL is not included in the API response.

Configure allowed redirect URLs in your Developer Dashboard before passing redirect_url. Unlisted URLs return 400.

On sandbox, verifications are auto-approved immediately — no email is sent. See Identity Verifications overview.

curl -X POST https://sandbox.dhmad.tn/api/v1/identity-verifications \
  -H "Authorization: Bearer sk_sandbox_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "seller@example.com",
    "external_user_id": "seller_42",
    "redirect_url": "https://yourapp.com/onboarding/kyc-done",
    "metadata": { "source": "onboarding" }
  }'

const response = await fetch('https://sandbox.dhmad.tn/api/v1/identity-verifications', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_sandbox_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'seller@example.com',
    external_user_id: 'seller_42',
    redirect_url: 'https://yourapp.com/onboarding/kyc-done',
    metadata: { source: 'onboarding' }
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://sandbox.dhmad.tn/api/v1/identity-verifications',
    headers={
        'Authorization': 'Bearer sk_sandbox_your_api_key_here',
        'Content-Type': 'application/json'
    },
    json={
        'email': 'seller@example.com',
        'external_user_id': 'seller_42',
        'redirect_url': 'https://yourapp.com/onboarding/kyc-done',
        'metadata': {'source': 'onboarding'}
    }
)

data = response.json()

{
  "id": "6655abc1234567890abcdef12",
  "email": "seller@example.com",
  "external_user_id": "seller_42",
  "kyc_status": "pending",
  "didit_session_status": "in_progress",
  "needs_admin_review": false,
  "claim_status": "pending",
  "linked_user_id": null,
  "linked_at": null,
  "created_at": "2026-06-06T12:00:00.000Z",
  "updated_at": "2026-06-06T12:00:00.000Z",
  "expires_at": "2026-09-04T12:00:00.000Z",
  "verification_email_sent": true,
  "verification_email_sent_at": "2026-06-06T12:00:00.000Z",
  "message": "A verification email has been sent to the user."
}

Request Body

string

required

Email address for the user. Lowercased on input. Must match the email they will use when registering on DHMAD.

string

Your internal user or seller ID. Returned in webhooks so you can update your database.

string

URL to redirect the user after they complete Didit. Must match one of your allowed redirect URLs in developer settings. Must use HTTPS in production (http://localhost allowed for development).

object

Optional key-value pairs (string values, max 500 characters each). Not returned in webhooks; stored on the verification record.

Response Fields

There is no verification_url field. The Didit link is only delivered by email to the end user.

Duplicate pending sessions

If you POST again with the same developer account and email while a pending session exists, the API returns 200 with the existing record and may resend the invite email (5-minute cooldown between resends).

Error Responses

User already has approved KYC on DHMAD:

{
  "error": "Conflict",
  "message": "User already has approved KYC on DHMAD.",
  "kyc_status": "approved",
  "user_exists": true
}

Redirect URL not allowed:

{
  "error": "Bad Request",
  "message": "Redirect URL does not match any allowed redirect URLs configured in developer settings."
}

Blocked email domain:

{
  "error": "Forbidden",
  "message": "Verification is not allowed for this email domain."
}

After creation, subscribe to identity.verification.updated and identity.verification.linked webhooks. See the Webhooks guide.

Get Started

API Reference

Guides

Developer Portal

Request Body

Response Fields

Duplicate pending sessions

Error Responses

​Request Body

​Response Fields

​Duplicate pending sessions

​Error Responses

Request Body

Response Fields

Duplicate pending sessions

Error Responses