The user types their national ID number. Didit checks it against the government database that issued it in 36 countries, and matches their selfie to the registry photo where the registry returns one.
Trusted by 2,000+ organizations worldwide.
Availability and rates come from the production methods catalog, not from this page. A country lights up here the moment it can be switched on inside your workflow; a rate is USD per answered attempt.
Live today
From Argentina to South Africa, every country in the catalog is live with its per-country rate next to it. Argentina, Nigeria, Panama and South Africa return a registry photo, so those four also run a selfie, passive liveness and a face match inside the same lookup.
Turn the lookup on for the countries that support it. Choose what happens on a partial match, on no match, and when the registry stays silent. Set how many tries the user gets. No code required.
Straight from the methods catalog
Live registries
Return a photo
Document photos needed
Every country listed is live in production. A dashed entry, if one ever appears here, is in the catalog but not switched on yet.
Department of Home Affairs
The format check runs before anything leaves the device. A mistyped number never reaches the registry and is never billed.
Where the registry returns a photo
One switch per outcome
On the session
Assurance labels are for your reviewers. The end user never sees them, the source name, or the price.
South Africa, USD per answered attempt
$2.20Every rate is public retail USD and includes the selfie, liveness and face match where the registry returns a photo. Document capture is billed only when the user falls back.
$ curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "wf_id_lookup",
"vendor_data": "user_42"
}'{ "url": "https://verify.didit.me/..." }const crypto = require("crypto");
// X-Signature-V2 signs canonical JSON: keys sorted as strings, compact,
// Unicode preserved. Emit the sorted entries directly - rebuilding an object
// would reorder integer-like keys ("10", "2"). Never hash req.rawBody.
const canonical = (v) =>
Array.isArray(v) ? "[" + v.map(canonical).join(",") + "]"
: v && typeof v === "object"
? "{" + Object.keys(v).sort()
.map((k) => JSON.stringify(k) + ":" + canonical(v[k])).join(",") + "}"
: JSON.stringify(v);
app.post("/webhooks/didit", express.json(), (req, res) => {
// Freshness: the signed body timestamp (refreshed on retry) must be recent
// and X-Timestamp must agree - the header alone is unsigned and replayable.
const ts = Number(req.body?.timestamp);
if (!ts || String(ts) !== req.headers["x-timestamp"] ||
Math.abs(Date.now() / 1000 - ts) > 300) return res.sendStatus(401);
const expected = crypto.createHmac("sha256", SECRET)
.update(canonical(req.body), "utf8").digest("hex");
const sig = String(req.headers["x-signature-v2"] ?? "");
const valid = sig.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
if (!valid) return res.sendStatus(401);
const { status, decision } = req.body;
// One entry per ID Verification node; pick yours by node_id when you run several.
const [idv] = decision?.id_verifications ?? [];
// idv.verification_method: "document" | "id_lookup" | "wallet"
res.sendStatus(200);
});{ "verification_method": "id_lookup", "assurance": "data_match" }# Didit non-document verification — integrate in 5 minutes
You are adding non-document identity verification to my_stack. The user types a
national ID number plus a few personal details, and Didit checks them against
the government database that issued the number. Every URL, header, and enum
value below is canonical — do not paraphrase or "improve" them.
## 1. Provision an account
- Sign up: https://business.didit.me (no credit card required).
- Grab the API key for your application from the console.
## 2. Read the methods catalog first
Availability is server-driven per country. Never hard-code a country list.
The catalog is not a public REST endpoint. Read it one of two ways:
- Business Console (signed in): your application -> ID Verification ->
Countries tab. https://docs.didit.me/console/id-verification-methods
- Didit MCP server tool didit_workflow_get_id_verification_methods_catalog,
authenticated with the same x-api-key; pass country (ISO 3166-1 alpha-3)
to narrow it to one country. https://docs.didit.me/integration/mcp/tools
- Public mirror of the coverage table (no auth, read-only):
https://docs.didit.me/core-technology/id-verification/verification-methods#coverage
The catalog tells you, per ISO 3166-1 alpha-3 country code:
- whether id_lookup is available
- the source label and the public USD rate per answered attempt (36 countries
are live at the time of this prompt, from Argentina to South Africa)
- the exact request fields to ask the user for, with their format rules
- the response fields that come back, and which of them are optional
## 3. Create a workflow with the ID Verification (OCR) feature
POST https://verification.didit.me/v3/workflows/
-H "x-api-key: <your-api-key>"
-H "Content-Type: application/json"
The ID Verification feature's enum value is OCR (UPPERCASE — strict enum;
there is no ID_VERIFICATION alias and the API rejects it). Non-document
lookup is its id_lookup method, configured per country under config.methods
on that same feature entry, in the same request. Keys are ISO 3166-1 alpha-3.
An omitted country, or an omitted methods key, means document only.
{
"workflow_label": "Non-document onboarding",
"features": [
{
"feature": "OCR",
"config": {
"methods": {
"ZAF": {
"document": { "enabled": true },
"id_lookup": {
"enabled": true,
"max_attempts": 1,
"skip_liveness_and_face_match": false,
"on_partial_match": "fallback_to_document",
"on_no_match": "fallback_to_document",
"on_provider_error": "fallback_to_document",
"response_fields": ["gender", "citizenship", "registry_portrait"]
}
}
}
}
}
]
}
Response: the workflow uuid — use it as workflow_id in step 4.
Rules that the API enforces:
- every fallback value is either fallback_to_document or decline
- max_attempts is an integer from 1 to 5, default 1
- skip_liveness_and_face_match is only accepted where the source returns a
portrait; elsewhere it is rejected
- response_fields lists the OPTIONAL fields you want stored. Required fields
are always stored and cannot be removed
- a country whose id_lookup the catalog does not mark available is rejected
- a country with no method enabled is rejected at publish time
## 4. Create a session
POST https://verification.didit.me/v3/session/
-H "x-api-key: <your-api-key>"
-H "Content-Type: application/json"
-d '{ "workflow_id": "<id from step 3>", "vendor_data": "<your user id>" }'
Response: 201 with url (the hosted verification link), session_token and
session_id. Redirect the user to url, or open it in the SDK. The field is
named url — there is no session_url and no verification_url.
Didit asks the user for the request fields in plain language, runs the
client-side format check, then queries the registry.
Where the registry returns a portrait (Argentina, Nigeria, Panama, South
Africa), Didit also takes a selfie, runs passive liveness on it, and
face-matches it to that portrait. All of it is inside the lookup price.
## 5. Webhooks
Register a destination (console -> API & Webhooks, or
POST https://verification.didit.me/v3/webhook/destinations/ with
webhook_version "v3" and subscribed_events ["status.updated"]) and store the
secret_shared_key it returns. Verify every delivery:
Header: X-Signature-V2 (NOT X-Signature, NOT X-Signature-Simple)
Algorithm: HMAC-SHA256, hex digest, over the CANONICAL JSON of the payload:
parse the body, sort keys recursively, serialise compact with
Unicode preserved and whole-valued floats as integers. Do NOT
hash the raw request bytes — that is the v1 X-Signature
algorithm and fails for V2 whenever whitespace or key order
differs from the canonical form.
Freshness: the signed body field timestamp is the dispatch time (Unix
seconds, refreshed on every retry). Reject when
abs(now - timestamp) > 300 seconds, and reject when the
X-Timestamp header does not equal it. The header is not
covered by the signature, so it must never be the only replay
check: a captured delivery replays with just that header
refreshed.
Compare: constant-time (crypto.timingSafeEqual)
Reference handler (Express) — use it as written:
const crypto = require("crypto");
// X-Signature-V2 signs canonical JSON: keys sorted as strings, compact,
// Unicode preserved. Emit the sorted entries directly - rebuilding an object
// would reorder integer-like keys ("10", "2"). Never hash req.rawBody.
const canonical = (v) =>
Array.isArray(v) ? "[" + v.map(canonical).join(",") + "]"
: v && typeof v === "object"
? "{" + Object.keys(v).sort()
.map((k) => JSON.stringify(k) + ":" + canonical(v[k])).join(",") + "}"
: JSON.stringify(v);
app.post("/webhooks/didit", express.json(), (req, res) => {
// Freshness: the signed body timestamp (refreshed on retry) must be recent
// and X-Timestamp must agree - the header alone is unsigned and replayable.
const ts = Number(req.body?.timestamp);
if (!ts || String(ts) !== req.headers["x-timestamp"] ||
Math.abs(Date.now() / 1000 - ts) > 300) return res.sendStatus(401);
const expected = crypto.createHmac("sha256", SECRET)
.update(canonical(req.body), "utf8").digest("hex");
const sig = String(req.headers["x-signature-v2"] ?? "");
const valid = sig.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
if (!valid) return res.sendStatus(401);
const { status, decision } = req.body;
// One entry per ID Verification node; pick yours by node_id when you run several.
const [idv] = decision?.id_verifications ?? [];
// idv.verification_method: "document" | "id_lookup" | "wallet"
res.sendStatus(200);
});
Body fields you will use: session_id, status, webhook_type, workflow_id,
vendor_data, decision.
Status values: Approved, Declined, In Review, In Progress, Not Started,
Abandoned.
## 6. Reading the result
The decision is the V3 shape: every feature result is a plural array with one
entry per workflow node. ID Verification results live in
decision.id_verifications[] — there is no singular decision.kyc (that is the
V2 shape) and no decision.id_verification. Select your entry by node_id (the
id of your ID Verification node in the workflow graph); with a single ID step,
take index 0. Each entry carries, next to the document fields:
verification_method "document" | "id_lookup" | "wallet"
assurance "documentary" | "data_match" | "cryptographic"
id_lookup source label, checked_at, attempts, outcome, one
comparison row per field with match / partial /
no_match, and the registry portrait reference when
there is one; null on document entries
fallback_from { method, reason, action } when the session fell
back to document capture or was declined; else null
A non-document entry that succeeds is assurance data_match, never
documentary. The fallbacks only govern unsuccessful lookups (partial match,
no match, provider error): a lookup that matches is accepted as the ID result
and never reaches them, so switching them to decline does not add documentary
evidence. If your risk policy needs documentary assurance for a segment, do
not enable id_lookup for that segment's country: configure
"document": { "enabled": true } alone (omit the id_lookup key, or set its
enabled to false) and route that segment to a workflow of its own when other
users may keep the lookup. As a final guard, treat any id_verifications[]
entry whose assurance is not documentary as failing that policy.
Field-by-field reference: https://docs.didit.me/reference/data-models#id-verification
## 7. Billing — what actually bills
- a registry that answered bills the lookup. Match, partial match and no
match all count as answered
- document capture bills on top when the user falls back
- a source that never answered is not billed
- a number that fails the client-side format check never reaches the registry
and is neither counted nor billed
## 8. Hard rules — do not change
- base URL for v3 endpoints: verification.didit.me
- auth header: x-api-key (lowercase, hyphenated)
- webhook headers: X-Signature-V2 plus X-Timestamp; canonical JSON, never
raw bytes; freshness from the signed body timestamp
- feature enum: OCR (uppercase) — the ID Verification feature; per-country
methods go under its config.methods
- method keys: document, id_lookup, wallet (lowercase, snake_case)
- country keys: ISO 3166-1 alpha-3, uppercase
- result path: decision.id_verifications[] (array), never decision.kyc
## 9. Verify your integration
- run one session per configured country in sandbox
- assert the id_verifications[] entry for your node has verification_method
id_lookup on the happy path
- force a no-match and assert the fallback you configured actually fires
- for a segment that needs documentary assurance, run a lookup that matches
against that segment's workflow and assert its entry has
verification_method document and assurance documentary
- assert your webhook accepts a correctly signed payload with reordered
keys, whitespace and integer-like metadata keys ("10" before "2"), and
rejects a wrong X-Signature-V2, a payload whose signed timestamp is older
than 300 seconds, and that same stale payload with only the X-Timestamp
header refreshed
Docs: https://docs.didit.me/integration/integration-prompt
For building, testing, and your first users.
25+ modules, publicly priced. Automatic volume discounts.
For large volumes and regulated programs.
Volume discounts apply automatically as usage grows — no negotiation, no sales call.
Didit is infrastructure for identity and fraud, the platform we wished existed when we were building products ourselves: open, flexible, and developer-friendly, so it works as a real part of your stack instead of a black box you integrate around.
One API covers verifying people (KYC, know your customer), verifying businesses (KYB, know your business), screening crypto wallets (KYT, know your transaction), and monitoring transactions in real time, on a stack built to be:
The footprint underneath: 14,000+ document types in 48+ languages, 1,000+ data sources, and 200+ fraud signals on every session. The Didit infrastructure dynamically learns from every session and gets better every day.
The user types their national ID number plus a few personal details, and Didit checks them against the government database that issued that number — no photo of a document anywhere in the flow.
Where the registry hands back a photo of the person, Didit also takes a selfie, runs passive liveness on it, and matches it to that photo. That is included in the lookup price, not billed on top.
It is not a separate product. It is one method inside ID_VERIFICATION, switched on per country next to document capture and digital ID wallets.
Thirty-six countries answer today, each through the government body that issued the number — among them Argentina (RENAPER), Brazil (Receita Federal), Colombia (Registraduría), India (UIDAI), Kenya (IPRS), Mexico (RENAPO), Nigeria (NIMC / NIBSS), Peru (RENIEC), South Africa (Department of Home Affairs) and the United Kingdom and United States through credit-bureau and financial-services records.
Argentina, Nigeria, Panama and South Africa return a registry photo, so those four also include a selfie, passive liveness and a face match.
Availability is served by the methods catalog, so your workflow sees a country the day it is ready. The full list with rates is on /pricing. Document capture still covers 220+ countries — see /supported-documents.
The full flow normally takes under 30 seconds end-to-end — that is the fastest in the market. Legacy providers usually take more than 90 seconds for the same flow.
Typing an ID number is faster than photographing a document, so a non-document lookup is usually the quickest path a user can take. On the back end Didit returns the result in under two seconds at p99.
A number on its own is never enough.
Where the registry returns a photo of the person, Didit takes a selfie, runs passive liveness on it to prove a real human is present, and face-matches it to the registry photo. A stolen number with the wrong face does not pass.
Where the registry returns no photo, the lookup confirms the data matches the record but not that the person is present. For those countries, keep a fallback to document capture on, or pair the lookup with liveness in the same workflow.
You decide, per country, with three separate switches: partial match, no match, and no response from the provider. Each one either falls back to document capture or declines the session.
You also set how many tries the user gets before the fallback fires — 1 to 5, default 1.
The result records what happened: the method that ran, the method it fell back from, and the reason. Nothing is silently swallowed.
A lookup is priced per country, because each registry charges differently — from $0.05 in the Dominican Republic to $4.30 in Singapore, with most Latin American registries at $0.20. Every rate is public on /pricing. A registry that answered bills the lookup — match, partial match and no match all count as answered.
Where the registry returns a photo, the selfie, passive liveness and face match are inside that rate, not on top of it. Document capture bills $0.15 on top only when the user falls back, and the first 500 document verifications every month are free, forever.
A registry that never answered is not billed. A number that fails the format check never reaches the registry and is neither counted nor billed.
Encrypted in transit and at rest, in the region you choose, under SOC 2 Type 1 and Type 2, ISO 27001 and GDPR.
Each lookup runs under the local privacy framework — POPIA in South Africa, NDPR in Nigeria, LGPD in Brazil, UK GDPR in the United Kingdom, GLBA permissible purpose in the United States — and Didit asks the user for consent before querying a registry that requires it.
Optional response fields can be unticked so they are never stored at all. Required fields are always stored. Full detail on /security-compliance.
Didit is in production with 2,000+ companies across regulated industries — fintech, banking, iGaming, crypto, marketplaces, healthcare and government.
A non-document lookup returns data match assurance rather than documentary assurance. Where your regulator requires a document, keep document capture as the fallback, or set the country to decline instead. The assurance level is on every session, so an auditor can see exactly which evidence backed each decision.
Memos on /security-compliance.
Minutes, three ways.
Start at business.didit.me, or read docs.didit.me/integration/integration-prompt.
One API for KYC, KYB, Transaction Monitoring, and Wallet Screening. Integrate in 5 minutes.