Skip to main content
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" }
  }'

{
  "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

​
email
string
required
Email address for the user. Lowercased on input. Must match the email they will use when registering on DHMAD.
​
external_user_id
string
Your internal user or seller ID. Returned in webhooks so you can update your database.
​
redirect_url
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).
​
metadata
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.