Skip to main content
The Identity Verifications API lets you start Didit KYC for a user by email before they register on dhmad.tn. DHMAD sends the verification link by email, stores the result, and links it when the user later creates an account with the same email.
For a full integration walkthrough, see KYC for marketplaces.

​
What you get

Pre-account verification

Verify sellers or buyers during your onboarding, even without a DHMAD account

Email-based flow

DHMAD emails the Didit link — the session URL is never returned to your API

Automatic linking

Approved KYC attaches when the user registers with the same email

Webhooks

identity.verification.updated and identity.verification.linked events

​
Endpoints

MethodPathDescription
POST/api/v1/identity-verificationsCreate session and send invite email
GET/api/v1/identity-verifications/:idGet status
GET/api/v1/identity-verifications?email=List by email
All endpoints require API key authentication. They do not require associating your developer account with a user account.

​
Typical flow

  1. Create — POST with email, optional external_user_id, optional redirect_url
  2. User completes Didit — from the DHMAD verification email (production only)
  3. Webhook — identity.verification.updated when status becomes approved or rejected
  4. User registers on DHMAD — same email, email OTP verified
  5. Webhook — identity.verification.linked with linked_user_id

​
Important constraints

verification_url is never returned. You cannot embed or redirect to Didit from your app using the API response. The user must complete KYC from the DHMAD email.
If you pass redirect_url, it must match an allowed redirect URL in Developer Dashboard settings. Same validation as checkout sessions.
On sandbox, verifications are auto-approved immediately with no Didit or invite email. Production behavior is different — see Sandbox behavior.

​
Response fields (common)

FieldDescription
idVerification record ID
emailUser email (lowercased)
external_user_idYour reference, if provided
kyc_statuspending, approved, or rejected
claim_statuspending until linked to a DHMAD user
linked_user_idDHMAD user ID after registration, or null
verification_email_sentWhether the invite email was sent
verification_email_sent_atISO timestamp of last invite email
expires_atRecord expiry hint (default 90 days)

​
Error codes

StatusMeaning
409DHMAD user with this email already has approved KYC (user_exists: true)
400Invalid email, invalid ID, or redirect_url not in allowed list
403Blocked email domain
404Verification not found (or not owned by your developer account)

​
Sandbox behavior

When using https://sandbox.dhmad.tn/api/v1 with a sk_sandbox_* key:
  • New verifications are auto-approved immediately
  • No Didit flow and no verification email
  • Webhook identity.verification.updated fires with status_source: "sandbox"
Use sandbox to test webhook handling and your onboarding logic. Validate the production email + Didit flow before launch.

​
Monitoring in the dashboard

View sessions started by your API keys in Developer Dashboard → Identity verifications. Document images and full Didit payloads are not shown — use webhooks or the GET endpoints from your backend.