Didit MCP Server
Connect AI agents to Didit for KYC, KYB, AML screening, and fraud operations. Create hosted verification sessions and review their status using a Didit workspace.
Hosted MCP Server
npx add-mcp 'https://mcp.didit.me/mcp'Installs into Claude Code, Codex, Cursor and more
Documentation
Didit MCP Server
The official Model Context Protocol server for Didit — bring KYC, KYB, AML screening, transaction monitoring, biometrics, and full workspace operations to Claude, Cursor, VS Code, Windsurf, Zed, and any MCP client.
- 160+ tools across sessions, workflows, vendor users/businesses, transactions, the standalone verification APIs, lists, cases, reports, webhooks, and billing.
- Load only what you need. Add
?toolsets=corefor a short catalog of about 30 tools, about a tenth of the tokens the full list costs; the rest stays one step away throughdidit_tool_search. See Toolsets. - Read-only mode for connections that must never change anything: add
?read_only=true. - Two ways to connect. "Log in with Didit" (OAuth 2.1 + PKCE): the MCP acts as the signed-in user with their role's permissions. Or an application API key, for agents that run with no person present (CI, scheduled jobs, backend agents): the connection is that one application. See Authentication.
- Tools call Didit REST endpoints. Session PDF generation returns a temporary download URL for the original PDF.
Full documentation: https://docs.didit.me/integration/mcp/overview
Session PDF downloads
didit_session_generate_pdf returns download_url, expires_at (UTC), and
expires_in (300 seconds). Fetch the URL without an Authorization header to save
the original Didit PDF. The server checks PDF access before issuing the link and
fetches the original report again at download time using the same user and organization.
It does not reconstruct the report from session data. If the session changes between
issuance and download, the download reflects the current report. Revoked or expired
user access can invalidate a link before its five-minute expiry.
Deployments must set MCP_PDF_DOWNLOAD_KEY to 32 cryptographically random bytes
encoded as 64 hexadecimal characters, shared across all replicas, and set
MCP_RESOURCE_URI to the public HTTPS MCP endpoint. Route
/downloads/session-report.pdf to this HTTP server. The authenticated-encryption
key protects the credentials embedded in the session-scoped link; rotating it
invalidates outstanding links. Treat links as secrets and redact the token query
parameter in proxy/access logs. Responses use Cache-Control: no-store.
E-signature files
didit_session_get_signature_evidence, didit_session_get_signed_document and
didit_session_get_signature_field_image return the same kind of link (plus content_type)
for a signer's evidence PDF, the signed PDF of one document and the PNG of a signature field.
They use the same MCP_PDF_DOWNLOAD_KEY and MCP_RESOURCE_URI; route
/downloads/session-signature to this HTTP server as well. The file is checked against its
recorded SHA-256 at issuance and again at download. didit_session_validate_signatures
re-validates the signed documents and returns the result as JSON.
Stdio deployments need a reachable HTTP deployment with the same key, API base URL,
and MCP_RESOURCE_URI; stdio alone cannot serve download links. Missing key
configuration produces an actionable tool error instead of inline PDF data.
Quick start
Hosted (recommended)
No install, no API key — point your client at the hosted URL and sign in via the browser:
https://mcp.didit.me/mcp
| Client | Install |
|---|---|
| Claude (web, Desktop) | Add Didit to Claude |
| Claude Code | claude mcp add --transport http didit https://mcp.didit.me/mcp |
| Cursor | Add Didit to Cursor |
| VS Code (GitHub Copilot) | Add Didit to VS Code |
| OpenAI Codex | codex mcp add didit --url https://mcp.didit.me/mcp |
Cursor (~/.cursor/mcp.json), by hand
{ "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp" } } }
Windsurf / Zed (via the mcp-remote bridge)
{ "mcpServers": { "didit": { "command": "npx", "args": ["-y", "mcp-remote@latest", "https://mcp.didit.me/mcp"] } } }
See per-client setup for every client, with screenshots and troubleshooting.
Once connected, ask for "my Didit context" (the model calls didit_context_get), or start from one of the server's prompts: integrate_didit, review_queue, explain_session, build_workflow, verification_report.
Sign in without a browser (device code)
For the local (stdio) server on a remote machine, in a container or in CI, where no browser can open, sign in with an OAuth device code. It also works for accounts that use a passkey or SSO and have no password.
npx -y @didit-protocol/mcp-server login
The terminal prints a short code and a link:
To connect this machine to your Didit account, open https://business.didit.me/device and enter the code WDJB-MJHT
Or open: https://business.didit.me/device?user_code=WDJB-MJHT
Approve only if the code on the page matches this one.
Open the link on any device with a browser, sign in to Didit, check that the code matches and approve. The command then saves your credentials and prints the scopes that were granted (never the token). Approve only a code you started yourself.
- Credentials live in
~/.config/didit/mcp-credentials.json(override withDIDIT_MCP_CREDENTIALS_FILE), readable by you only, one entry per Didit environment. - The local server uses them automatically when
DIDIT_ACCESS_TOKENis not set, and refreshes them before they expire. npx -y @didit-protocol/mcp-server logoutrevokes the grant and deletes the stored credentials.- Set
DIDIT_DEVICE_NAMEto change the name shown on the approval page (default: the machine's hostname). - In CI, run
loginonce on a trusted machine and mount the credentials file as a secret, or setDIDIT_ACCESS_TOKENas before. Do not share one credentials file between jobs that run at the same time, because refresh tokens rotate. - No shell? Ask the agent to call
didit_account_device_login_start, show you the link and code, thendidit_account_device_login_pollonce you approve. Both tools exist only on the local server.
Sign in with the account tools
On the local server an agent can also sign in by itself, with an email address and a password: didit_account_login for an existing account (then didit_account_verify_2fa when the account has an authenticator app), or didit_account_register and didit_account_verify_email for a new one.
The local server keeps that sign-in, so the tools that follow are authenticated with nothing passed between them.
- It is kept in the same credentials file as a device-code sign-in (
~/.config/didit/mcp-credentials.json, readable by you only) and refreshed before it expires. A server started later picks it up. - The answer of these tools carries no refresh token: the server holds it, because a refresh token works once.
- When the file cannot be written (a read-only home directory in a container), the sign-in is kept in memory until the server stops.
- If you signed in both ways, the server uses the more recent sign-in.
DIDIT_ACCESS_TOKEN, when set, still takes precedence over both. npx -y @didit-protocol/mcp-server logoutremoves it from the machine.- An account that signs in with a passkey or SSO has no password: use the device code above.
These tools exist only on the local server. The hosted server never takes a password.
Connect with an API key (headless agents and CI)
An agent that runs with no person present has no browser to sign in with.
It connects to the hosted server with the application API key it already sends to the Didit API, in the x-api-key header:
Claude Code
claude mcp add --transport http didit https://mcp.didit.me/mcp --header "x-api-key: $DIDIT_API_KEY"
Cursor (~/.cursor/mcp.json)
{ "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp", "headers": { "x-api-key": "${env:DIDIT_API_KEY}" } } } }
Any other client or your own agent: send x-api-key: <key> on every request to https://mcp.didit.me/mcp.
Authorization: Bearer <key> works too, for clients that only let you set a bearer token.
What an API key connection is:
- One application.
The connection acts on the application the key belongs to, so there are no ids to pass.
didit_context_getnames it, says whether it isliveorsandbox, and reportsconnection.type: "api_key". A call that names another organization or application is refused. - The key's own access. The key is forwarded to the Didit API exactly as on a direct API call, and the API decides what it may do. A full-access key reaches everything of its application; a restricted key only the resources it was given. Give an agent a restricted key with an expiry, created in the Didit console under the application's API keys.
- Sandbox first. Connect with the sandbox application's key to build and test: every check is simulated and nothing is billed.
- Combines with toolsets and read-only:
https://mcp.didit.me/mcp?toolsets=core&read_only=true(see Toolsets). - Revoked like any key. Revoke or rotate the key in the console and the connection stops within a minute. Every tool call is logged with the key's id, never the key.
What needs a person, and is therefore neither listed nor run on an API key connection:
- members, roles and API key management;
- the organization's plan, cards, receipts and billing details;
- the audit log, and
didit_workflow_build_graph(usedidit_workflow_create, or the graph toolsdidit_workflow_create_draft,didit_workflow_validate_graphanddidit_workflow_set_graph); - download links for session PDFs and e-signature files (request the file from the Didit API with the same key).
A person does those in the Didit console, or through a connection that signs in with OAuth.
Two limits to know:
- A key limited to specific IP addresses is refused, because the Didit API would see this server's address and not yours.
/mcpand/mcp/paymentstake a key. From nothing to a first verification, with no browser. The account tools of the local server create the account:didit_account_register, thendidit_account_verify_emailwith the code sent to the email address. The answer carries the new organization with its live and its sandbox application, each with its API key. The local server is signed in from that moment (see Sign in with the account tools), so the same conversation goes on to create a workflow (didit_workflow_create) and a session (didit_session_create) in the sandbox application. For an agent that runs elsewhere, store the keys in your secret store and connect it to the hosted server with the sandbox key; switch to the live key to go live.didit_org_get_balancereads the credit balance; when credit is needed, see Agent payments.
GET /healthz lists api_key under features on a server that accepts keys.
Authentication
The MCP is an OAuth 2.1 resource server; the Didit console (business.didit.me) is the authorization server. On first connect your client opens a browser, you Log in with Didit and approve the scopes, and the MCP then acts as you — across every organization you belong to, with your role's permissions. Tokens are short-lived and refreshed automatically.
Scopes: didit:management (workspace operations), didit:verification (running checks) and didit:staff (Didit staff accounts only; the authorization server never issues it to anyone else). Your console role is enforced server-side on every call.
The hosted server also takes an application API key in place of a sign-in, for agents that run with no person present. Such a connection is one application with the key's own access, not a user with a role: see Connect with an API key.
The phone code pair,
didit_verify_phone_sendanddidit_verify_phone_check, always calls the public phone API with the application's API key, because the console has no route for them. On a sign-in the MCP reads that key with your sign-in (a role withcreate:sessionsand thedidit:managementscope, or an organization owner or admin for a localdidit_account_logintoken); on an API key connection it uses the connection's own key. The key is never returned, stored or logged.
See Authentication.
Toolsets
By default a connection lists every tool your role may use, as it always has. Tool definitions are sent to the model with every request, so the whole catalog costs tens of thousands of tokens each time: roughly 50,000 to 115,000, depending on the model's tokenizer. Some clients also cap how many tools they accept. The short catalog trades that cost for one more step, a search for the tool: measured on a set of everyday requests, the strongest models reached the right tool a little more often with the full list, at about ten times the tokens. When the cost matters (a coding agent with a context budget, a client that caps the number of tools), name the toolsets you want on the server URL:
https://mcp.didit.me/mcp?toolsets=core
https://mcp.didit.me/mcp?toolsets=core,workflows
https://mcp.didit.me/mcp?toolsets=core,transactions,cases&read_only=true
core is the short catalog: about 30 tools and about a tenth of the tokens.
It covers your organizations and applications, sessions (create, find, decide, explain, simulate in the sandbox, webhook deliveries), finding workflows, analytics and balance, the application's API key and webhooks, finding cases, users, businesses and transactions, and the documentation search.
| Toolset | What it holds |
|---|---|
core | The short list above. |
account | Organizations, applications, API keys, members and roles. |
billing | Plan, credit balance, payment methods, receipts and billing details. |
sessions | Verification sessions: create, find, decide, review, share, import, PDFs and webhook deliveries. |
workflows | Verification workflows and questionnaires: build, edit, validate and publish. |
lists | Custom lists, the blocklist and the allowlist. |
vendors | The people and companies you verify: vendor users and vendor businesses. |
transactions | Transaction monitoring: transactions, wallet screening and rules with backtesting. |
cases | Case management: create, assign, escalate and resolve cases. |
investigator | The AI Investigator: its review queue, reports, decisions, policy questions and performance. |
webhooks | Webhook destinations and alerts. |
reports | Analytics, exports and the audit log. |
branding | White-label branding of the verification flow. |
verification | Standalone verification APIs: ID document, face, AML, proof of address, phone, email, database and business checks. |
docs | Search the Didit documentation. |
all | Every tool your role may use. The default. |
How it behaves:
- Toolsets are opt-in. A URL with no
toolsetslists everything, so an existing connection sees no difference. - Naming toolsets lists exactly those.
?toolsets=caseslists the case tools (anddidit_context_get); addcoreto get the short list too. - A toolset decides what is listed, not what you may run. A tool outside the selection still runs when called by name, with the same permission checks as always. Nothing is lost by loading less.
- The rest stays one step away. When a connection lists only part of the catalog it also gets four discovery tools:
didit_tool_search(find a tool by what you want to do, or list a toolset),didit_tool_describe(its full schema),didit_tool_call_readanddidit_tool_call_write(run it). A call through them is checked exactly like a direct call. read_only=trueis a safety boundary. Only tools that read are listed or discoverable, and every call that would change data is refused, whatever the client lists or remembers. It works with or withouttoolsets.- An unknown toolset is ignored, never an error, and the server's instructions name it back with the valid ids.
- Clients that cannot edit the URL send the
X-MCP-ToolsetsandX-MCP-Readonlyheaders instead. - The local (stdio) server takes
--toolsets=core,workflowsand--read-only, or theDIDIT_TOOLSETSandDIDIT_READ_ONLYenvironment variables. - A self-hosted server can change what a connection gets when it names nothing with
MCP_DEFAULT_TOOLSETS(for examplecore). GET /healthzlists what the server supports ("features": ["toolsets", "read_only", ...]), for a client that wants to check before it relies on one.
The server also sends instructions on connect (where to start, how organization and application ids resolve, what this connection loaded) and offers prompts (integrate_didit, review_queue, explain_session, build_workflow, verification_report).
didit_docs_search searches the live documentation at docs.didit.me, so questions about how Didit works are answered from the current pages; set DIDIT_DOCS_MCP_URL to an empty string to switch it off.
Tools
160+ tools, grouped by toolset. The full catalogue with read/write/destructive markers is in docs/TOOLS.md and at docs.didit.me. Highlights:
- Discovery & cross-app:
didit_context_get,didit_session_search,didit_transaction_search,didit_vendor_user_search,didit_analytics— aggregate across every org/app in one call. - Sessions: create, list, get decision, update status, reviews, bulk import, webhook delivery log + resend (
didit_session_webhookswaits for a sandbox session's webhook so an integration can be verified end to end), Precise Location evidence (didit_session_get_location_evidence: every attempt and the same person's earlier checks behind a Location verdict). - Verification APIs:
didit_verify_id,didit_verify_aml,didit_verify_face_match,didit_verify_kyb_search, … - Workflows (incl. branching graphs):
didit_workflow_search,didit_workflow_get_graph,didit_workflow_edit_graph— build conditional/branching workflows (fuzzy-match conditions, Document-AI steps) by sending small ops; large feature configs are kept server-side, never resent.didit_workflow_get_id_verification_methods_cataloganddidit_workflow_get_kyb_registry_cataloganswer the server-driven questions a config write depends on (which countries offer non-doc lookup / wallets, which KYB data tiers and monitoring a country's registries sell). - Investigator (AI case reviewer):
didit_investigator_queue_list,didit_investigator_report_get(recommendation, basis, evidence, precedents),didit_investigator_record_get(the review of one verification or transaction, open or decided),didit_investigator_add_note(a fact the user adds, as a team note the next review reads), questions, the free backtest (didit_investigator_backtest_start), performance, dashboard and Activity. Its decisions (didit_investigator_accept,_override,_batch_accept), policy answers (_question_answer,_question_dismiss) and the re-review that replaces the open report (_rereview, optionally with a note) are annotated destructive and refused withoutconfirm: true, which a client sends only after the user approves that exact action. Every Investigator call sendsX-Didit-Actor-Via: mcp(orcopilotwhen the console assistant marks its request so), so the Investigator Activity shows where the user acted from. - Compliance: transaction monitoring, custom and preset rule management with backtesting, lists/blocklist/allowlist, cases, reports, audit logs, alerts.
- Workspace: questionnaires, webhooks, members, billing, branding.
- API key for your integration:
didit_org_create_api_keycreates ONE key per connected app and application, scoped to what the signed-in person can do (never full access or key management), rate-limited and audit-logged. The secret is returned once; the person sees the key with the connected app in the console and can revoke it there. - Billing:
didit_org_get_balance,didit_billing_get_plan,didit_billing_quote_plan,didit_billing_list_payment_methods,didit_billing_list_receipts,didit_billing_get_detailsanddidit_billing_update_details. No tool charges a card: when credit or a plan change is needed, the tools return console links (next_steps.top_up_urlopens the top-up dialog with the amount filled in) and the person pays there. The local stdio server and the unlisted/mcp/paymentsendpoint (below) also offerdidit_org_top_up.
Agent payments (/mcp/payments, stdio)
The directory-listed connectors (/mcp and /mcp/chatgpt) never move money: didit_org_top_up is not in their catalog and a call to it is refused with the console link.
https://mcp.didit.me/mcp/payments is a separate, unlisted endpoint for coding agents that may top up the organization's saved card once a person turned that on.
It uses the same OAuth sign-in and tokens as /mcp (its own protected-resource metadata is at /.well-known/oauth-protected-resource/mcp/payments), serves the full catalog plus didit_org_top_up, and is never submitted to a directory.
An API key connection gets the same tool there, under the same switch.
The local stdio server offers the same tool.
didit_org_top_up parameters:
| Parameter | Description |
|---|---|
amount_in_dollars | USD, $50 to $20,000 per top-up. |
confirm | Required, true, only after the person approved this exact action. |
payment_method | checkout (default) creates a Stripe Checkout page for the person to pay. saved_card charges the organization's saved primary card off-session, now. |
idempotency_key | Required for saved_card (1 to 255 characters). Choose one unique key per intended top-up and reuse it on any retry of that same top-up: the same key and amount returns the same top-up and never charges twice, another amount is idempotency_key_conflict. The server never retries a charge by itself. |
saved_card works only when a person turned on "Connected AI agents can top up with your saved card" in the Didit console (Billing > Payment methods; off by default).
While it is on, the saved primary card is charged off session at the normal self-serve amounts ($50 to $20,000).
didit_org_get_balance shows the switch as agent_top_up: {enabled} on /mcp/payments and stdio (and nowhere else).
A successful call returns the backend body (outcome, top_up).
A refusal comes back as Error [<code>]: <detail> followed by Next step: {"action", "url", "description"}, unchanged from the backend, so the agent can hand the person next_step.url: a Top up dialog link that says which agent asked and has the amount filled in.
| Code | Meaning | The person |
|---|---|---|
agent_top_up_not_enabled | The switch is off (the default). | Tops up in the console, or turns the switch on. |
authentication_required | The card's bank asks the cardholder to approve; nothing was charged. | Approves it in the console. |
payment_method_required | No saved card. | Adds a card. |
card_declined | The card was declined. | Tops up in the console. |
billing_address_required, top_up_in_progress, payment_provider_error | See detail. | Follows next_step (retry with the same key where it says so). |
On the directory-listed endpoints a refused didit_org_top_up call includes a signed request link for the requested amount when one can be made (POST /organization/{org}/billing/top-up-requests/; it charges nothing).
didit_org_top_up with checkout returns the same signed link as next_steps.console_top_up_url.
Every request the MCP server sends to the Didit API carries X-Didit-Agent: mcp; the backend refuses settings changes (including the agent top-up switch) that carry it, so an agent can never turn it on itself.
File inputs
Tools that consume files (face upload, ID/PoA/liveness/face/age verification, branding) accept the file in one of two forms:
*_path— an absolute path on the machine running the MCP server. Only works for local/stdio runs (e.g. Claude Code with a local server), where your files and the server share a filesystem.*_base64— the file content inline, as raw base64 or adata:URL. Use this against the hosted endpoint; it is how the Didit Console Copilot passes chat attachments (its agent resolves attachment references likeatt_1into base64 before the call reaches the MCP).
Both forms enforce the same 15MB cap and magic-bytes allow-list (png/jpg/jpeg/webp/gif/bmp/ico/pdf). The hosted transport's JSON body limit is 25MB (MCP_JSON_BODY_LIMIT).
Run it yourself
The hosted server above is the easy path - no install. To self-host, clone this repo and run it with Docker or Node. It authenticates the same way: OAuth or an application API key on the hosted endpoint, or a user Bearer token (DIDIT_ACCESS_TOKEN) for a local headless run.
API keys need the default token verification mode (MCP_TOKEN_VERIFY_MODE=introspection).
git clone https://github.com/didit-protocol/mcp.git && cd mcp
# Docker (recommended) — serves /mcp and /healthz on port 3000
docker build -t didit-mcp . && docker run -p 3000:3000 --env-file .env didit-mcp
# …or with Node
npm install && npm run build
node dist/http.js # hosted HTTP/OAuth
DIDIT_ACCESS_TOKEN=<user-access-token> node dist/index.js # stdio (headless)
All Didit base URLs and OAuth endpoints are environment variables with public defaults (verification.didit.me, apx.didit.me, business.didit.me) — override them for a private deployment. See ARCHITECTURE.md and .env.example for the full reference.
Workflow feature configuration
Every workflow feature node takes a config object. The tables below are the complete
contract - what didit_workflow_create, didit_workflow_update, didit_workflow_validate_graph,
didit_workflow_set_graph and didit_workflow_edit_graph accept, and what the API stores.
A key that is not listed here is not part of the contract and is dropped silently on save.
didit_workflow_get_feature_config_schema returns the same data as JSON at runtime.
Generated from schema/feature-config-schema.json (contract sha256:76c4acb7cff69ae13d13d71e61bb7fa0d6b29f04d834a58558d458cd2806bb02, schema version 1), which is a copy of the artifact service-didit-verification generates from its feature-config serializers. Do not edit by hand — run npm run schema:readme.
AGE_ESTIMATION
Configuration for Age Estimation feature.
| Key | Type | Accepts | Meaning |
|---|---|---|---|
borderline_maximum_age_threshold | integer | null | integer >=1 <=100 | |
borderline_minimum_age_threshold | integer | null | integer >=1 <=100 | |
enable_id_verification_fallback | boolean | null | boolean | |
external_capture_device_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when an external capture device is detected. |
face_audio_recording_enabled | boolean | null | boolean | Record the microphone during the selfie capture, so a reviewer can hear the session. Off by default. |
face_liveness_attack_face_match_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the liveness face matches (above the duplicate-face similarity bar) a face from an earlier session of this application whose own capture the liveness engine judged an attack (risk FACE_MATCHES_LIVENESS_ATTACK), another user's session only and only a confident attack verdict. Review or no action only - a decline set here is downgraded to review, because a genuine user can be rejected once by mistake and then pass. Defaults to NO_ACTION (evidence is recorded, the verdict is unchanged). |
face_liveness_duplicated_face_document_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when a duplicate face is found on a user verified with a different date of birth. Another document of the same person (a passport after an identity card, a renewal, a document of a second country) is not flagged. |
face_liveness_duplicated_face_name_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when a duplicate face is found under a different name. |
face_liveness_flash_mode | string | null | string | |
face_liveness_max_attempts | integer | null | integer >=1 <=3 | |
face_liveness_method | string | null | 'ACTIVE_3D'|'FLASHING'|'PASSIVE' | |
face_liveness_multiple_faces_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when more than one face is present in the capture. |
face_liveness_possible_duplicated_face_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when this face matches a previously seen user. |
face_liveness_score_decline_threshold | number | null | number | |
face_liveness_score_review_threshold | number | null | number | |
face_liveness_uncertain_retry_enabled | boolean | null | boolean | Native SDK active liveness only. On, a capture whose liveness score falls strictly between face_liveness_score_decline_threshold and face_liveness_score_review_threshold is never decided, whichever verdict the engine attached to it: the person is told the result was unclear and asked to capture again, every time, outside the face_liveness_max_attempts budget (which still applies to captures the engine could not score). Off by default; the web flow ignores it. |
face_liveness_video_anomaly_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the stored liveness recording contains a repeated moving sequence consistent with a looped video feed, measured server-side from the video itself, independently of the liveness score. It deliberately does NOT flag a frozen or near-motionless capture: frame statistics cannot separate an injected still from a genuine one (a subject holding still, or a flash that clips the exposure), so acting on that would decline real users. A frozen or pre-recorded injected feed is instead defeated by strict flash liveness (set face_liveness_flash_mode to "1" for strict), which binds the capture to a per-session colour-sequence challenge a recording cannot reproduce. Defaults to NO_ACTION (evidence is recorded, the verdict is unchanged). |
face_luminance_max_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the selfie is brighter than face_luminance_max_threshold. |
face_luminance_max_threshold | integer | null | integer >=0 <=100 | |
face_luminance_min_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the selfie is darker than face_luminance_min_threshold. |
face_luminance_min_threshold | integer | null | integer >=0 <=100 | |
face_privacy_mode_enabled | boolean | null | boolean | |
face_quality_decline_threshold | integer | null | integer >=0 <=100 | |
face_quality_review_threshold | integer | null | integer >=0 <=100 | |
face_search_enabled | boolean | null | boolean | Run the 1:N Face Search on the selfie: match it against previously verified users, the face blocklist and allowlist, and store its biometric template for later matching. On by default. Off skips the search, keeps no face template, and leaves the duplicate-face actions with nothing to act on. |
frame_injection_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when injected video frames are detected. |
minimum_age_threshold | integer | null | integer >=1 <=100 | |
screen_capture_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the selfie is a photo of a screen. |
status_rules | array | array | |
virtual_camera_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when a virtual camera feed is detected. |
AML
Configuration for AML feature (used for both KYC AML and KYB Company AML).
| Key | Type | Accepts | Meaning |
|---|---|---|---|
aml_country_weight | integer | null | integer >=0 <=100 | |
aml_dob_weight | integer | null | integer >=0 <=100 | |
aml_entity_type | string | null | 'company'|'person' | Whether this node screens a person or a company. Defaults to person on a person (KYC) workflow and to company on a business (KYB) workflow. Set it to company to screen the business named in an uploaded document (via aml_field_sources) without a KYB Registry step - the provider searches company records instead of people, and the match score is scored as a company. |
aml_field_sources | json | null | {"full_name"|"date_of_birth"|"nationality"|"document_number": {"source": "document_ai"|"questionnaire"|"expected_data", "key": "||expected_details.<expected_details field>|metadata."}} | Where this node reads the entity it screens, when the workflow has no ID Verification or KYB Registry step to supply it - a Document AI workflow over non-standardised documents (a tax certificate, an acta constitutiva). Same contract as database_validation_field_sources: source names the producer and key names the value inside it - a Document AI field key for document_ai, a questionnaire node id for questionnaire, and expected_details.<field> or metadata.<key> for expected_data. The map's KEY is one of the four AML screening inputs: full_name, date_of_birth, nationality, document_number - read for a company as legal name, incorporation date, country and registration number. A Document AI field already keyed as one of those four maps automatically and is deliberately not persisted, so renaming it never freezes a stale mapping. An explicit mapping wins over both the auto-map and the ID document, and a mapping that resolves to nothing at runtime leaves that input empty rather than falling back. The screened name is the exception on a person node: when the ID Verification step already named the person, that name stands in rather than leaving the node with no search to run. With no ID Verification and no KYB Registry upstream, full_name must be fillable or the graph is rejected on save: there is no search without a name. |
aml_incomplete_data_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the screening ran on less than a full identity (name, date of birth and country). REVIEW is the default and the historical behaviour; NO_ACTION proceeds on reduced data for a workflow that knowingly holds only a name. The screening still runs either way, and the partial-data log is still recorded - this only decides what it does to the status. |
aml_match_score_threshold | integer | null | integer >=0 <=100 | |
aml_name_weight | integer | null | integer >=0 <=100 | |
aml_score_approve_threshold | integer | null | integer >=0 <=100 | |
aml_score_review_threshold | integer | null | integer >=0 <=100 | |
case_blueprint | uuid | null | uuid | Which case blueprint the automatically-created case is built from. Only meaningful with create_cases_on_hit; the account default is used when unset. |
create_cases_on_hit | boolean | null | boolean | Open a case automatically when the screening returns a hit, instead of leaving the hit to be triaged from the session. Off by default. |
fallback_to_native | boolean | null | boolean | |
is_aml_ongoing_monitoring_enabled | boolean | null | boolean | Keep screening the PERSON after the session is approved, raising a new hit when they later appear on a watchlist. Off by default. |
kyb_company_aml_country_weight | integer | null | integer >=0 <=100 | |
kyb_company_aml_dob_weight | integer | null | integer >=0 <=100 | |
kyb_company_aml_match_score_threshold | integer | null | integer >=0 <=100 | |
kyb_company_aml_name_weight | integer | null | integer >=0 <=100 | |
kyb_enable_ongoing_monitoring | boolean | null | boolean | The same, for the COMPANY on a KYB workflow. The two switches are independent. |
kyb_score_approve_threshold | integer | null | integer >=0 <=100 | |
kyb_score_review_threshold | integer | null | integer >=0 <=100 | |
provider_key | string | null | string | |
status_rules | array | array |
BANK_VERIFICATION
Configuration for Bank Verification feature.
Bank Verification confirms who owns a bank account against an identity ANOTHER step established - it is not identity proof on its own. Put ID Verification, Database Validation or a questionnaire before it; first in a graph it has nothing to compare against and can only return
unknown. The node is opt-in and runs nothing whilebank_countriesis empty.
| Key | Type | Accepts | Meaning |
|---|---|---|---|
bank_abandoned_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the step ends without a match after the person left at their bank and never came back (an attempt timed out). |
bank_account_age_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the account is newer than bank_account_age_days, a common mule pattern. |
bank_account_age_days | integer | null | integer >=1 <=365 | An account whose history starts later than this many days ago counts as new, 1 to 365, defaulting to 30. Read from the transaction history, so only with the transactions scope. |
bank_account_check_accept_close_match | boolean | null | boolean | Account check only. On (the default), a name the bank scores between bank_partial_match_floor and bank_name_match_threshold is a close match: the person confirms the name the bank holds when bank_suggest_holder_name is on, and bank_partial_match_action decides. Off, that close match is a no match (OWNER_NAME_MISMATCH, decided by bank_no_match_action) and spends the attempt. Bank sign-in keeps its close matches either way. |
bank_account_check_max_attempts | integer | null | integer >=1 <=5 | How many account checks the user gets, 1 to 5 (3 when unset): how many times the person can type the account details for a check the bank answers. A separate count from bank_max_attempts. A check refused as typed (an invalid IBAN) or one the provider could not answer spends none. |
bank_account_lookup_enabled | boolean | null | boolean | Retired: use bank_method_order and bank_countries.<ISO3>.methods. Read for one release from a save that sends no bank_method_order (with bank_open_banking_enabled, it sets the order: the account check after bank sign-in when on; off when unset), and written back on every save as whether any country offers the account check. |
bank_account_selection | string | null | 'auto'|'user' | Whether the user picks which of the connected accounts is verified (user) or the first eligible one is taken (auto). |
bank_account_type_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the verified account is a savings account. |
bank_address_match_threshold | integer | null | integer >=50 <=100 | At or above this score the holder's address matches, 50 to 100, defaulting to 70. Only read with bank_require_address_match. |
bank_address_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the holder's address differs, which turns a match into a close match. Only with bank_require_address_match. |
bank_allow_skip | boolean | null | boolean | Retired by bank_continue_without_bank: still accepted, and written back from it on every save. A save that sends only this key gets from_start for true and when_needed otherwise. The person can always continue without a bank now. |
bank_attempts_exhausted_action | string | null | 'REVIEW'|'DECLINE' | Verdict when the user spent the attempts of every method the country offers (bank_max_attempts, and bank_account_check_max_attempts where it offers the account check) without a successful connection, also when they then continue without a bank. |
bank_auto_add_countries | boolean | null | boolean | Offer every country a route of this node can serve, also the ones added after the node was saved, apart from countries bank_countries turns off. Off when the key is absent, so an existing node never widens on its own. |
bank_business_account_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the institution types the holder as a business rather than a person. |
bank_cash_flow_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when money comes in and straight back out, or many small transfers come in (pass-through cash flow). Needs the transactions scope. |
bank_connection_timeout_minutes | integer | null | integer >=5 <=60 | How long a started connection stays open before the attempt is abandoned, 5 to 60 minutes. |
bank_consent_expired_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the bank consent lapses after the step was already decided. Only meaningful with bank_refresh_enabled. |
bank_continue_without_bank | string | null | 'from_start'|'when_needed' | When the bank step shows "Continue without your bank". when_needed (the default) shows it once no method works for the person's country or bank (also when their bank cannot be reached and no other bank sign-in or account check could verify them), or when they say they have no online banking. from_start also shows it on the first screen. It cannot be turned off: the person can always continue, and the session then follows bank_unsupported_action when nothing could verify their country or bank, bank_attempts_exhausted_action when every attempt is spent, and bank_skipped_action otherwise. A failed attempt that spends the last one does not wait for the person: the step ends on its own with bank_attempts_exhausted_action. Every save writes it. |
bank_countries | json | null | {"": {"enabled": true|false, "institutions": ["<institution_id>", ...] | "all", "popular_institutions"?: ["<institution_id>", ...], "hidden_institutions"?: ["<institution_id>", ...], "methods"?: ["open_banking"|"account_lookup", ...]}} | Which countries a user may connect a bank in - a WHITELIST, so an empty map means the node offers nothing and runs nothing (unless bank_auto_add_countries is on), and a map whose countries are all off is refused. institutions narrows the picker to specific provider institution ids; "all" offers every identity-capable bank in the country. hidden_institutions leaves banks out of the suggestions and the search; with bank_popular_mode: manual, popular_institutions are the banks shown as popular, in order. A bank is never both hidden and popular. Coverage belongs to the route the node selected in provider_key: the native route (a registered native route with an approved price) or the connected marketplace provider. A country no route of the node can establish account ownership in is KEPT on save, because the step is never a dead end: it offers no bank sign-in or account check there, only its fallbacks (a statement upload where the node offers one, micro-deposits where a route sends them) and Continue without a bank (bank_continue_without_bank). A code that names no country Didit verifies is refused on save. A statement-only country is refused when the organization's contract does not price the statement upload. methods sets which of bank sign-in (open_banking) and the account check (account_lookup) the country offers and in what order, over the step's bank_method_order: the person starts on the first one and is offered the second as its backup. A country a route serves whose methods leave it nothing, and any country whose methods name a method no route of the node serves there, are refused on save. |
bank_country_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the institution's country differs from the expected/document country. |
bank_currency_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the account currency is not in bank_expected_currencies. |
bank_dob_match_enabled | boolean | null | boolean | Compare the holder's date of birth, where the bank shares one, with the verified one. A mismatch never changes the ownership result: it fires bank_dob_mismatch_action. On by default. |
bank_dob_match_threshold | integer | null | integer >=50 <=100 | At or above this score the date of birth matches, 50 to 100, defaulting to 70. A date is the same day or not, so it scores 100 or 0. |
bank_dob_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the holder's date of birth differs. Only with bank_dob_match_enabled. |
bank_eligible_account_types | array | null | array | Which account types the user may pick. Credit cards, loans and investment accounts are never eligible - they do not establish ownership of a payment account. Defaults to current/checking. |
bank_email_match_enabled | boolean | null | boolean | Compare the email on file at the bank with the session's verified email. A mismatch fires bank_email_mismatch_action. Off by default. |
bank_email_match_threshold | integer | null | integer >=50 <=100 | At or above this score the email matches, 50 to 100, defaulting to 70. |
bank_email_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the holder's email differs. Only with bank_email_match_enabled. |
bank_evidence_retention_days | integer | null | integer >=30 <=1825 | Delete the bank evidence this many days after the verdict: 30, 90, 365 or 1825. Null keeps it with the session. Deleted: the holder details, the identity they were compared against, the account identifiers, the financial data and an uploaded statement; a connection still live is revoked. The verdict, scores and reason codes stay. Deleting the session deletes everything, whichever comes first. |
bank_expected_currencies | array | null | array | ISO 4217 currencies the account is expected to be in. Empty means any; a mismatch is reported through bank_currency_mismatch_action. |
bank_fallback_used_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the account was verified with micro-deposits or a statement upload. |
bank_field_sources | json | null | {"full_name"|"first_name"|"last_name"|"address"|"date_of_birth"|"phone"|"email": {"source": "document_ai"|"questionnaire"|"expected_data", "key": "||expected_details.<expected_details field>|metadata."}} | Where to read a reference-identity field when no earlier step in the graph can fill it. The map's KEY is one of full_name, first_name, last_name, address, date_of_birth, phone, email; source names the producer and key names the value inside it - a Document AI field key for document_ai, a questionnaire node id for questionnaire, and expected_details.<field> or metadata.<key> for expected_data. An expected_details.<field> VALUE may only name a field the session-create payload actually carries - address, country, date_of_birth, first_name, gender, id_country, identification_number, ip_address, last_name, nationality or poa_country. A malformed entry is refused on save, not dropped. |
bank_joint_account_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the account has more than one holder. |
bank_low_balance_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the available balance is below bank_min_balance. Needs the balances scope. |
bank_match_any_holder | boolean | null | boolean | A joint or co-owned account matches when ANY listed holder matches the person. Off: only the first holder the bank lists can. On by default. |
bank_max_attempts | integer | null | integer >=1 <=5 | How many bank sign-in attempts the user gets, 1 to 5; a micro-deposit or statement fallback spends one too. The account check has its own bank_account_check_max_attempts. The step ends once every method the country offers has spent its attempts, which without a successful connection is bank_attempts_exhausted_action. |
bank_method_order | array | null | ["open_banking"|"account_lookup", ...] | Which of the two methods the step offers and in what order, for every country that sets no methods of its own in bank_countries: open_banking is bank sign-in (the person signs in at their bank and shares the account holder, plus balances, transactions and income when the step asks for them), account_lookup is the account check (no sign-in: the person types the account details, an IBAN, a sort code and account number, a CLABE..., and the bank confirms the name on it; ownership only). In each country the person starts on the first method a route serves there, and is offered the other one as its backup under "Other ways to verify"; where a country offers both, the account check also stands in for a bank whose sign-in is degraded or down. A method no route serves in a country is left out there. At least one method; a save that names none gets ["open_banking", "account_lookup"], unless it sends bank_open_banking_enabled or bank_account_lookup_enabled, which then set it. The account check is billed once per check the provider answers (a match, a close match, a no match, an account it could not verify or did not find); an account refused before the check bills nothing. |
bank_microdeposits_enabled | boolean | null | boolean | Offer micro-deposits as a fallback: two small deposits reach the account and the person enters the amounts. Offered only in a country whose route can send them, after a charged bank verification attempt in the same session. Included at no extra charge; the customer pays the route price once. Sandbox sessions can test it without billing. The holder is the name the session verified, which the person declares the account is under, so a verified account records a holder_declared warning. On by default. |
bank_min_balance | number | null | number >=0 | Minimum available balance, in the account's own currency. Below it bank_low_balance_action fires. Needs the balances scope and the save is refused without it. 0 is a real cutoff - it triggers the action for an overdrawn account - but the action defaults to NO_ACTION, so the verdict is unchanged unless another action is configured. This is not the same as leaving the key out. |
bank_mule_score_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the mule score is at or above bank_mule_score_threshold. |
bank_mule_score_threshold | integer | null | integer >=0 <=100 | At or above this mule score, 0 to 100, bank_mule_score_action fires; defaults to 70. The score combines a new account, pass-through cash flow, a drained balance and many small transfers in, read from the transaction history (the transactions scope). |
bank_name_match_threshold | integer | null | integer >=50 <=100 | At or above this score the holder name is a match. 50 to 100, defaults to 85. |
bank_no_match_action | string | null | 'REVIEW'|'DECLINE' | Verdict when the account holder is demonstrably not the verified person (best name score below bank_partial_match_floor). |
bank_not_verifiable_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the institution connected but returned no holder identity to compare. |
bank_open_banking_enabled | boolean | null | boolean | Retired: use bank_method_order and bank_countries.<ISO3>.methods. Read for one release from a save that sends no bank_method_order (with bank_account_lookup_enabled, it sets the order: bank sign-in when on, which is the default), and written back on every save as whether any country offers bank sign-in. |
bank_partial_match_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the holder name lands between bank_partial_match_floor and bank_name_match_threshold. Never approves by default. |
bank_partial_match_floor | integer | null | integer >=0 <=99 | The close-match value: below this score the holder name is a no-match. 0 to 99, defaults to 70. The band between the floor and the threshold is the partial match, so the floor must be strictly below bank_name_match_threshold or the save is refused. An explicit null means "use the default" here too, which is why a threshold of 50 with no floor is refused: it is checked against the default floor of 70. |
bank_phone_match_enabled | boolean | null | boolean | Compare the phone on file at the bank with the session's verified phone. A mismatch fires bank_phone_mismatch_action. Off by default. |
bank_phone_match_threshold | integer | null | integer >=50 <=100 | At or above this score the phone matches, 50 to 100, defaulting to 70. |
bank_phone_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the holder's phone differs. Only with bank_phone_match_enabled. |
bank_popular_mode | string | null | 'auto'|'manual' | auto (the default) orders the popular banks by what people in the country connect most; manual shows each country's popular_institutions from bank_countries instead, in their order. |
bank_reference_identity | string | null | 'auto'|'database_validation'|'expected_details'|'kyc'|'questionnaire' | Which earlier step supplies the identity the account holder is compared against: kyc (ID Verification), database_validation, expected_details (the session-create payload), questionnaire, or auto to use whichever one the workflow produced. The step that actually supplied the compared name is recorded on the result as reference_identity_source: a name mapped in bank_field_sources records where it was mapped from (document_ai among them), and a business session records kyb. |
bank_reference_identity_missing_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when no earlier step produced an identity to compare the holder against, so ownership can only be unknown. |
bank_refresh_enabled | boolean | null | boolean | Re-fetch the account's financial data after the step has already been decided, for as long as the bank consent lasts. Needs at least one of the balances, transactions or income scopes and the save is refused without one. A consent that lapses afterwards is bank_consent_expired_action. |
bank_require_address_match | boolean | null | boolean | Also require the holder's address to match. A name that reached the threshold but whose address scores below bank_address_match_threshold drops to a close match decided by bank_address_mismatch_action. An institution that returns no address waives the requirement; a session with no address of its own to compare against does not, and lands on a close match decided by bank_partial_match_action. Off by default. |
bank_require_oauth_only | boolean | null | boolean | Offer only institutions reachable over OAuth / app-to-app, never a provider's legacy credential-capture surface. Where open banking already makes OAuth the only route, this changes nothing. |
bank_scopes | json | null | {"ownership": true, "identifiers": true|false, "balances": true|false, "transactions": true|false, "income": true|false} | What the user is asked to consent to sharing. ownership is what the product verifies and cannot be turned off. identifiers unmasks the IBAN / account number; balances, transactions and income read real financial data, are each billed separately, and are refused on save unless the application carries the bank_financial_data entitlement. On a node that can run on Didit's own routes, each of them is also refused when a country the node offers has no route that reads it with bank sign-in: only bank sign-in reads data, so the data must come from the person's bank (the console offers only the scopes every country reads). A country that offers only the account check is not refused: a person who verifies by account check passes without the data, which the result lists in financial_data.not_collected. A scope that is off is never requested from the provider, so the bank never shows it on its consent screen. |
bank_show_match_result_to_user | boolean | null | boolean | Show the ownership result to the user inside the verification flow. Off means it is recorded on the session but never shown to them. |
bank_skipped_action | string | null | 'REVIEW'|'DECLINE' | Verdict when the person chose "Continue without your bank" while a way to verify was there. Defaults to REVIEW. The bank result then has continued_without_bank true and SKIPPED in its reason codes. |
bank_statement_document_checks_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when an uploaded statement carries editing or tampering evidence. Defaults to REVIEW. |
bank_statement_enabled | boolean | null | boolean | Offer a bank statement upload as a fallback: a statement from the last 3 months, checked for tampering, whose holder name is matched like a bank's. Included at no extra charge after a charged bank verification attempt in the same session. With bank_statement_standalone_enabled it is also offered with no bank attempt before it, in any country. Sandbox sessions can test it without billing. Off by default. |
bank_statement_standalone_enabled | boolean | null | boolean | With bank_statement_enabled, also offer the statement upload when no bank attempt happened, in any country, including one no bank sign-in or account check route serves. Charged on its own as bank_statement_upload, USD 0.20 per evaluated statement at list price, with the organization's contract rate or special price applying as for any add-on; not offered where the contract does not price it. Sandbox sessions can test it without billing. On by default. |
bank_store_full_identifiers | boolean | null | boolean | Store the account identifiers unmasked rather than masked. Needs the identifiers scope and the save is refused without it. Even then the unmasked form is only served to a caller holding the bank-verification read permission. |
bank_store_raw_owner_data | boolean | null | boolean | Keep the holder details the institution returned next to the ownership evidence. Off means only the comparison itself is retained: scores, match method and reason codes. |
bank_suggest_holder_name | boolean | null | boolean | On a close match, show the person the name the bank holds the account under and ask them to confirm it is theirs or to connect another account. Their answer is recorded as holder_confirmation; confirming ends the step on bank_partial_match_action. On by default. |
bank_transactions_history_days | integer | null | integer >=30 <=365 | How far back transaction history is read, 30 to 365 days, defaulting to 90. Needs the transactions scope and the save is refused without it. A node that may run on Didit's native route (no provider_key, or fallback_to_native) reads 30 or 90 days only: anything else is refused, because the native transactions add-on is priced for those two windows. |
bank_unknown_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the evidence could not be fetched after retries - a transient failure. |
bank_unsupported_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the person continues without a bank because no method could verify their country or bank: no bank sign-in or account check route serves the country, or the bank they picked cannot be used on this step. Defaults to REVIEW. The bank result then has continued_without_bank true and NOT_COVERED in its reason codes. |
bank_use_provider_score | boolean | null | boolean | Also read the institution's own holder-name score, and let it decide when it is higher than Didit's or when Didit had no holder name to score at all. A result decided that way reports provider_only as its match method, and a connection that returned no such score records a provider_score_unavailable warning. On by default. |
fallback_to_native | boolean | null | boolean | Whether a marketplace connection that cannot be established falls back to Didit's native route. Off by default: a silent fallback would spend your Didit balance on a session you expected to run on your own provider contract. A fallback connection is recorded as credential_source = native and billed at the native price. |
provider_key | string | null | string | Which route runs the step. Empty (the default) is Didit's native Bank Verification, a provider-independent product Didit routes to the regional open-banking vendor that serves the user's country and institution, on Didit's contracts and billing. A value names a MARKETPLACE provider whose own credentials this application has connected - the session then runs, is billed and is revoked on your provider account, and Didit charges only the marketplace platform fee. A provider that is not connected is refused on save. |
status_rules | array | array |
DATABASE_VALIDATION
Configuration for Database Validation feature.
The node is opt-in and does nothing while
database_validation_countriesis empty - the editor blocks publishing in that state and the compliance check reports it as a gap. Place it after the step that produces its inputs (usually OCR), and usedatabase_validation_field_sourcesonly for inputs no upstream step can fill.
| Key | Type | Accepts | Meaning |
|---|---|---|---|
database_validation_countries | json | null | {"": {"services": ["<service_id>", ...]}} | The databases to check, per country - this node runs NOTHING until at least one country carries at least one service id. Service ids come from the country's live catalog (e.g. bra_cpf for BRA). An unknown id, an id that belongs to another country, and a service no workflow can run (not live yet, or offered only through the standalone POST /v3/database-validation/) are rejected with a 400 that names the service; a service the saved workflow already carries but can no longer run is removed on save. The legacy {"<ISO3>": "one_by_one"|"two_by_two"|"not_enabled"} shape is still accepted and auto-expanded to that country's live services. |
database_validation_field_sources | json | null | {"<db_validation_input_field>": {"source": "document_ai"|"questionnaire"|"expected_data", "key": "||expected_details.<expected_details field>|metadata."}} | Where to read a database input that no earlier step in the graph can fill. source names the producer and key names the value inside it: a Document AI field key for document_ai, a questionnaire node id for questionnaire, and expected_details.<field> or metadata.<key> for expected_data. The two halves speak different vocabularies: the map's KEY is a Database Validation input field (tax_id, document_number, ...), while an expected_details.<field> VALUE may only name a field the session-create payload actually carries - address, country, date_of_birth, first_name, gender, id_country, identification_number, ip_address, last_name, nationality or poa_country. Anything else under expected_details. is rejected on save; metadata.<key> takes any non-empty whitespace-free customer key. Exact-key matches against an upstream step resolve automatically and are deliberately not persisted, so renaming a Document AI field never freezes a stale mapping into the config. A malformed entry is rejected with a 400 that names its input field. |
database_validation_no_match_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the database returns no match at all. |
database_validation_not_applicable_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when no selected database covers the holder's country or document. |
database_validation_partial_match_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the database matches some, but not all, of the submitted fields. |
status_rules | array | array |
DOCUMENT_AI
Configuration for the Document AI feature.
At most 3 documents per node, field keys unique within a document, and at most one field per document may set
is_full_name(it is optional - a document may mark none).
| Key | Type | Accepts | Meaning |
|---|---|---|---|
document_ai_document_tampering_action | string | null | 'REVIEW'|'DECLINE' | Verdict when the document looks tampered with. |
document_ai_documents | array | array | |
document_ai_max_attempts_exceeded_action | string | null | 'REVIEW'|'DECLINE' | Verdict when the user runs out of document_ai_max_retry_attempts. |
document_ai_max_retry_attempts | integer | null | integer >=2 <=5 | |
document_ai_missing_required_fields_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when a field marked required could not be extracted. |
document_ai_name_match_score_threshold | integer | null | integer >=0 <=100 | |
document_ai_name_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the field flagged is_full_name disagrees with the verified identity's full name, scored against document_ai_name_match_score_threshold. |
document_ai_unreadable_document_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the uploaded document cannot be read at all. |
document_ai_unsupported_file_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the uploaded file type is not supported. |
status_rules | array | array |
EMAIL_VERIFICATION
Configuration for Email Verification feature.
| Key | Type | Accepts | Meaning |
|---|---|---|---|
breached_email_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the address appears in a known credential breach. |
cross_org_fraud_email_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when this address was flagged as fraudulent by another organization in the network. |
disposable_email_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the address belongs to a disposable-mail provider. |
duplicated_email_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the address was already verified for this application. |
email_alphanumeric_code | boolean | null | boolean | |
email_code_size | integer | null | integer >=4 <=8 | |
email_enrichment_enabled | boolean | null | boolean | |
email_intelligence_score_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the enrichment score is worse than email_intelligence_score_threshold. |
email_intelligence_score_threshold | integer | null | integer >=0 <=100 | |
email_max_check_attempts | integer | null | integer >=1 <=5 | |
email_max_retries | integer | null | integer >=1 <=5 | |
email_no_social_presence_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the social footprint check (email_social_enabled) finds the address registered on none of the platforms it covers. |
email_social_enabled | boolean | null | boolean | |
frequent_email_breach_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the address appears in many breaches. |
only_corporate_emails_allowed | boolean | null | boolean | |
recent_email_breach_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the address appears in a recent breach. |
status_rules | array | array |
FACE_MATCH
Configuration for Face Match feature.
| Key | Type | Accepts | Meaning |
|---|---|---|---|
face_match_eyes_covered_action | string | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when calibrated evidence says the eyes region is covered in the selfie. NO_ACTION records evidence without changing Face Match; REVIEW sends Face Match to review; DECLINE declines it. The signal remains shadow-only until the region reports calibrated=true. |
face_match_face_covered_action | string | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when calibrated evidence says the face region is covered in the selfie. NO_ACTION records evidence without changing Face Match; REVIEW sends Face Match to review; DECLINE declines it. The signal remains shadow-only until the region reports calibrated=true. |
face_match_max_attempts | integer | null | integer >=1 <=3 | |
face_match_mouth_covered_action | string | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when calibrated evidence says the mouth region is covered in the selfie. NO_ACTION records evidence without changing Face Match; REVIEW sends Face Match to review; DECLINE declines it. The signal remains shadow-only until the region reports calibrated=true. |
face_match_not_computed_action | string | null | 'REVIEW'|'DECLINE' | Verdict when no face-match score could be produced (missing portrait or selfie). |
face_match_score_decline_threshold | integer | null | integer >=0 <=100 | |
face_match_score_review_threshold | integer | null | integer >=0 <=100 | |
status_rules | array | array |
GEOLOCATION
Configuration for the Precise Location (GEOLOCATION) feature. Every threshold is bounded here rather than in the client: the browser and the native SDKs are told what to collect by the step data this config produces, and a value the server would refuse must never reach a user as a request their device cannot satisfy. The action keys all default to Review rather than Decline. A denied permission, a wide radius or a stale fix is not evidence of fraud, and a default that declined them would make the step a conversion trap.
| Key | Type | Accepts | Meaning |
|---|---|---|---|
geolocation_accuracy_mode | string | null | 'approximate_allowed'|'precise' | What the device is asked for. precise asks the operating system for a precise position, and a person who grants only an approximate one is asked again while attempts remain and then judged by geolocation_approximate_action; approximate_allowed accepts an approximate grant without that verdict. geolocation_max_accuracy_radius_m applies either way. precise when unset. |
geolocation_allow_qr_handoff | boolean | null | boolean | Offer to continue on a phone with a QR code while the step is still open (allow_qr_handoff in the step data, can_handoff on each submit answer). Native SDKs already run on the phone and never show the code. On by default. |
geolocation_allow_skip | boolean | null | boolean | Let the person go on without a location at any time, from the intro or a retry screen (skipped: true). The skip ends the step and is judged by geolocation_unavailable_action, except a skip that answers a refusal on a continue_without_location geolocation_refusal_path, which is recorded as that refusal. Off by default. |
geolocation_approximate_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the user granted an approximate location while geolocation_accuracy_mode asks for a precise one. |
geolocation_areas | json | null | [{"id": "<1-64 of A-Z a-z 0-9 _ ->", "label"?: "", "type": "allowed"|"blocked", "kind": "country", "country": ""} | {..., "kind": "region", "country": "", "regions": ["<ISO 3166-2>", ...]} | {..., "kind": "circle", "center": {"latitude": , "longitude": }, "radius_km": <1-500>} | {..., "kind": "polygon", "points": [{"latitude": , "longitude": }, ...]}] | Allowed and blocked areas, applied while is_geolocation_geofencing_enabled is true. Only a position inside an allowed area passes, and a blocked area always wins over an allowed one. A position counts by its whole accuracy circle: a circle that crosses an edge that decides the answer is undetermined, never outside. A country or region ends where other land begins, never at its coastline, and a position the outlines place on no land (a seafront or pier the simplified coastline cut away) is undetermined for every country or region within its radius plus 12 nautical miles. id is what branch rules and geolocation.inside_areas / geolocation.blocked_areas name; kind picks the shape: a whole country (ISO 3166-1 alpha-3 with a published outline: a territory the outlines draw as another country's region is that region, such as Reunion as France's FR-RE or Bonaire, Sint Eustatius and Saba as NL-BQ1 to NL-BQ3), region (ISO 3166-2 codes of one country with published boundaries), circle (1 to 500 km) or polygon (3 to 200 points, a ring whose edges never cross or touch each other). At most 50 areas, ids unique, and at least one allowed area while geofencing is on. Cannot be combined with geolocation_geofencing_by_country. |
geolocation_blocked_area_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the position, and its whole accuracy circle, falls inside a blocked area of geolocation_areas. Defaults to Decline. |
geolocation_consecutive_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when geolocation_consecutive_mismatch_count mismatches in a row are reached. Defaults to Review. |
geolocation_consecutive_mismatch_count | integer | null | integer | Raise LOCATION_CONSECUTIVE_MISMATCHES when this check and the same person's previous checks (same vendor_data) were outside the allowed areas, in a blocked area or too far from the address this many times in a row. A check that compared nothing neither extends nor breaks the streak, and neither does a position the device did not measure (a mocked or simulated fix, an emulator, a failed attestation). From 2 to 10; null (the default) is off. |
geolocation_deep_link_enabled | boolean | null | boolean | Forwarded to the client as deep_link_enabled in the step data: offer to open the customer's own app instead. The server applies no rule to it. Off by default. |
geolocation_document_distance_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the device position is further from the document address than geolocation_document_distance_km. The address is geocoded coarsely, so this is a weak signal. |
geolocation_document_distance_basis | string | null | 'declared'|'document'|'proof_of_address' | Which address geolocation_document_distance_km is measured from: document (the default: the identity document's address, then the proof of address), proof_of_address only, or declared (the expected_details.address given at session creation, geocoded). |
geolocation_document_distance_km | integer | null | integer >=0 | How far, in kilometres, the position (the IP location on an ip_only node) may be from the address geolocation_document_distance_basis names before geolocation_document_distance_action applies. Unset or null (the default) is off. |
geolocation_document_distance_unit | string | null | 'imperial'|'metric' | The unit the console shows geolocation_document_distance_km in. Display only: the stored value is always kilometres and no rule depends on it. |
geolocation_emulator_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the app that shared the location reported running on an emulator. Browsers cannot report it. Unless it is No action, it ends the step on that attempt: checking again cannot change the device. No action unless set or a preset says otherwise. |
geolocation_geofence_undetermined_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the position cannot be placed inside or outside the fence because its accuracy circle reaches the boundary. Uncertainty is never reported as being outside. |
geolocation_geofencing_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the device position, and its whole uncertainty circle, falls outside geolocation_geofencing_by_country. |
geolocation_geofencing_by_country | json | null | {"": {"allowed": true|false, "states"?: {"<ISO 3166-2 code>": {"allowed": true|false}} | null}} | Country and region allow/deny rules for the device's own position, applied only while is_geolocation_geofencing_enabled is true. Same shape as IP Analysis's ip_geofencing_by_country, except that states keys are ISO 3166-2 codes (US-NJ), not state names, because the position is resolved to a subdivision rather than to a provider's city label. A country that is not listed is allowed. Saving a region rule for a country with no published ISO 3166-2 boundaries is rejected rather than silently ignored. |
geolocation_integrity_missing_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when a native client submitted a position with no device-attestation token. Defaults to No action; web clients are recorded as unsupported rather than missing, because no browser can attest. |
geolocation_ip_distance_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the device position and the session's IP location are further apart than geolocation_ip_distance_km, after both uncertainty radii are subtracted. |
geolocation_ip_distance_km | integer | null | integer >=0 | How far apart, in kilometres, the device position and the IP location may be, after both uncertainty radii are subtracted, before geolocation_ip_distance_action applies. 200 when the key is omitted; null switches the comparison off. Only a node whose geolocation_position_source is device_and_ip or unset compares; that key says which IP location it compares with. |
geolocation_ip_distance_unit | string | null | 'imperial'|'metric' | The unit the console shows geolocation_ip_distance_km in. Display only: the stored value is always kilometres and no rule depends on it. |
geolocation_low_accuracy_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when no attempt established the required precision: the best position has an uncertainty radius wider than geolocation_max_accuracy_radius_m, or it reported no radius at all. A position without a radius is never counted as meeting the limit. |
geolocation_low_accuracy_behavior | string | null | 'ask_again'|'fail' | What a position wider than geolocation_max_accuracy_radius_m, or with no radius, does: ask_again (the default) asks the person to try again while attempts remain; fail ends the step on the first one. |
geolocation_max_accuracy_radius_m | integer | null | integer | The widest uncertainty radius, in metres, a device position may have and still count. From 10 to 50000 metres; 250 when unset. A wider position, or one that reports no radius, does what geolocation_low_accuracy_behavior says and is judged by geolocation_low_accuracy_action. An ip_only node has no device radius and never applies it. |
geolocation_max_accuracy_radius_unit | string | null | 'imperial'|'metric' | The unit the console shows geolocation_max_accuracy_radius_m in. Display only: the stored value is always metres, no rule depends on it, and the step data only forwards it so a client can show the same unit. |
geolocation_max_age_seconds | integer | null | integer | How old, in seconds, a device position may be when the server receives it. From 5 to 3600 seconds; 120 when unset. An older one is asked again while attempts remain and then judged by geolocation_stale_fix_action. |
geolocation_max_attempts | integer | null | integer | How many attempts the person gets on this node. From 1 to 5 attempts; 3 when unset. An attempt the person can still change (a refusal, a wide, stale or approximate position, or an area or anonymizer finding the node acts on) asks again while attempts remain, and the last one decides the step. A mocked position, or an emulator the node acts on, ends the step on the attempt that reported it. |
geolocation_mock_location_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the operating system reported the position as simulated rather than measured (Android mock provider, iOS simulated-by-software). |
geolocation_permission_denied_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the user declined or dismissed the location prompt on every allowed attempt. Defaults to Review: a refusal is a choice, not a fraud signal. |
geolocation_position_source | string | null | 'device_and_ip'|'device_only'|'ip_only' | Where the position comes from. device_and_ip asks for the device position and compares it with the IP location of the connection it is submitted from (an IP-intelligence lookup when that IP is not cached yet). Unset (the default) asks for the device position too and, as before this key existed, compares it with the IP location the session's Device & IP Analysis step observed, so there is no distance without that step and the connection is never looked up. The exception is a node that acts on a VPN, proxy or Tor finding (its own action or its preset): it looks the connection up for that finding and compares the device with it, exactly as device_and_ip does. device_only never compares with the IP location and looks the connection up only for those findings; ip_only never asks the person and judges the connection's IP location instead, city level with a 50 km radius, with no accuracy, freshness or approximate-grant rule; with geolocation_areas a coastal city is judged inside its country unless another country is within that radius. On a node that asks the device, an attempt with no device position is judged as the refusal or failure it is: the IP location never stands in for it. |
geolocation_preset | string | null | 'fraud_screening'|'licensing' | The defaults every unset action of this node takes. licensing: outside an area, in a blocked area, a VPN, Tor or an emulator declines, a proxy and the other findings are reviewed, and a missing device attestation stays No action. fraud_screening: the same, except that what Licensing declines goes to review. Null keeps the long-standing defaults. An action set explicitly always wins. |
geolocation_proxy_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the connection that shared the location goes through an open, anonymous or private-relay proxy. No action unless set or a preset says otherwise. |
geolocation_refusal_path | string | null | 'continue_without_location'|'end_session'|'retry_then_handoff' | The way forward offered when location access is refused. retry_then_handoff (the default) asks again while attempts remain and offers a phone hand-off; continue_without_location lets the person go on, recording the refusal; end_session ends the step and the session on the first refusal, and needs geolocation_permission_denied_action to be Review or Decline and a workflow with a Declined, In Review or Final decision ending. The session is decided from the steps that ran and never Approved: on a workflow that cannot end on that decision it takes the other non-approving ending (Declined for In Review, In Review for Declined). |
geolocation_stale_fix_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the position was measured more than geolocation_max_age_seconds before the server received it. |
geolocation_timeout_seconds | integer | null | integer | How long, in seconds, the client lets the device look for a position on each attempt; the server forwards it in the step data and enforces nothing itself. From 5 to 120 seconds; 20 when unset. An attempt that finds no position in time is submitted as timeout, asked again while attempts remain and then judged by geolocation_unavailable_action. |
geolocation_tor_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the connection that shared the location is a Tor exit node. No action unless set or a preset says otherwise. |
geolocation_travel_max_days | integer | null | integer | How long after being seen in the usual area a distant position is still travel. From 1 to 90 days; 14 when unset. |
geolocation_travel_tolerance_enabled | boolean | null | boolean | Excuse the distance from the address when the same person (same vendor_data) was seen within geolocation_travel_usual_area_km of it in the last geolocation_travel_max_days days. Never excuses a VPN, a spoofed position, a blocked area or being outside the allowed areas. Only a position the device measured counts as being seen there: a mocked or simulated fix, an emulator or a failed attestation never does. |
geolocation_travel_usual_area_km | integer | null | integer | Radius around the address that counts as the person's usual area. From 10 to 500 km; 100 when unset. |
geolocation_unavailable_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when no position could be obtained - location services off or restricted, the positioning system returned nothing, the attempt timed out, the user skipped the step, or the client is too old to support it. |
geolocation_vpn_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the connection that shared the location is a commercial VPN. Unless it is No action, the person is asked to turn it off and check again while attempts remain. No action unless set or a preset says otherwise. |
is_geolocation_geofencing_enabled | boolean | null | boolean | Turns the area rules on: geolocation_areas, or the older geolocation_geofencing_by_country, only apply while this is true, and only then does the step data list available_areas. Off by default. With it on, a geolocation_areas list needs at least one allowed area. |
status_rules | array | array |
IP_ANALYSIS
Configuration for Device & IP Analysis feature.
| Key | Type | Accepts | Meaning |
|---|---|---|---|
automation_detected_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the session looks driven by automation rather than a person. |
cross_org_fraud_device_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when this device was flagged as fraudulent by another organization in the network. |
cross_org_fraud_ip_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when this IP was flagged as fraudulent by another organization in the network. |
device_app_tampered_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the host application binary looks tampered with. |
device_blocklist_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the device is on the organization's block list. |
device_debugger_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when a debugger is attached to the host application. |
device_emulator_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the device is an emulator rather than real hardware. |
device_hooking_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when runtime hooking or instrumentation is detected. |
device_integrity_missing_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when no platform device-integrity attestation was returned. |
device_liveness_attack_history_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the same device (matched on its persistent device id) was used in an earlier session of another user whose liveness capture the liveness engine judged an attack (risk DEVICE_LINKED_TO_LIVENESS_ATTACK). Defaults to NO_ACTION (evidence is recorded, the verdict is unchanged). |
device_model_inconsistency_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the same device (matched on its persistent device id) was reported as a different device model in an earlier session (risk DEVICE_MODEL_INCONSISTENT), which points at a spoofed device model or a copied device identifier. Generic model strings (for example iPhone or the reduced user agent K) are never compared. Defaults to NO_ACTION (evidence is recorded, the verdict is unchanged). |
device_rooted_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the device is rooted or jailbroken. |
duplicated_device_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when this device was already used by another verified user. |
duplicated_ip_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when this IP was already used by another verified user. |
expected_ip_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the IP disagrees with the expected IP sent on the session. |
ip_geofencing_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the connecting IP's country is not allowed by ip_geofencing_by_country. |
ip_geofencing_by_country | json | null | {"": {"allowed": true|false, "states"?: {"<state_code>": {"allowed": true|false}} | null}} | Country allow/deny rules for the connecting IP address, applied only while is_ip_geofencing_enabled is true. allowed is required and must be a real boolean; states is optional and null when the country needs no per-state rule. Countries that are not valid ISO3 are dropped on save. |
ip_location_not_determined_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when no IP address identifying the end user was recorded, so the session has no IP location at all: country, city, ISP, coordinates and time zone are unavailable, and ip_geofencing_by_country, the document-country comparison and the VPN/data-centre checks cannot run. Defaults to No Action, which keeps the IP_LOCATION_NOT_DETERMINED warning visible on the session without changing its verdict; set Review or Decline if an unlocated session must not pass. |
ip_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the IP country disagrees with the document's issuing country. |
is_ip_geofencing_enabled | boolean | null | boolean | |
multiple_devices_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the session was driven from more than one device. |
recovered_device_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the device reports a recovered or restored state. |
status_rules | array | array | |
vpn_detection_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the connection comes through a VPN, proxy or Tor exit. |
KYB_DOCUMENTS
| Key | Type | Accepts | Meaning |
|---|---|---|---|
kyb_document_age_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when a document is older than its configured freshness window. |
kyb_document_critical_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when a document contradicts the registry on a critical company detail. |
kyb_document_max_attempts_exceeded_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the user runs out of kyb_document_max_retry_attempts. |
kyb_document_max_retry_attempts | integer | null | integer >=1 <=5 | |
kyb_document_non_critical_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when a document contradicts the registry on a minor detail. |
kyb_document_subtype_config | json | null | {"<KYB_DOCUMENT_GROUP|KYB_DOCUMENT_SUBTYPE>": {"enabled": true|false, "max_age_days": <0-3650>|-1|null}} | Per-group or per-subtype switch and freshness window. Keys must be a known KYB document group or subtype code. max_age_days is null for the default window, -1 for unlimited, or an integer 0-3650; anything else is rejected. |
kyb_document_tampering_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when a company document looks tampered with. |
kyb_document_unproven_text_replacement_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when a text field of a company document was blanked and re-typed in another font and the file holds no proof of whether its content changed (KYB_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT). Other editing evidence on the same document stays under kyb_document_tampering_action; when both apply, the stricter action decides. |
kyb_required_document_groups | json | null | ["<KYB_DOCUMENT_GROUP>", ...] | The company paperwork to collect, as a list of document-GROUP codes - each group is satisfied by any one of the document types it covers. The KYB Documents feature refuses to save with an empty list: a node that requires nothing is the same as not having the node. |
status_rules | array | array |
KYB_KEY_PEOPLE
The workflow ids here point at separate KYC workflows: a KYB graph verifies the company, and the people behind it are verified by the linked person workflows.
| Key | Type | Accepts | Meaning |
|---|---|---|---|
kyb_corporate_ubo_verification_workflow | uuid | null | uuid | |
kyb_key_people_company_fields | json | null | [{"key": "", "label": "", "type": "text"|"number"|"date"|"phone"|"email", "required": true|false, "custom": true|false}] | Which company details are collected for a CORPORATE key person. Same list-of-descriptors shape and same rules as kyb_key_people_person_fields. |
kyb_key_people_document_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when a key person's document disagrees with the details declared for them. |
kyb_key_people_ownership_required | boolean | null | boolean | |
kyb_key_people_person_fields | json | null | [{"key": "", "label": "", "type": "text"|"number"|"date"|"phone"|"email", "required": true|false, "custom": true|false}] | Which personal details are collected for an individual key person, as an ORDERED LIST of field descriptors (not a map). key is required and non-empty; type must be one of text, number, date, phone or email; custom marks a field the customer added rather than one of the built-ins. |
kyb_key_people_prefill_from_registry | boolean | null | boolean | Pre-fill the key-people list from the company registry result, so the customer confirms and corrects rather than typing every officer and shareholder in. |
kyb_notify_parties_by_email | boolean | null | boolean | |
kyb_officer_verification_workflow | uuid | null | uuid | |
kyb_reject_if_ubo_rejected | boolean | null | boolean | |
kyb_require_corporate_ubo_kyb | boolean | null | boolean | |
kyb_require_officer_kyc | boolean | null | boolean | |
kyb_require_ubo_kyc | boolean | null | boolean | |
kyb_reuse_verified_individuals | boolean | null | boolean | |
kyb_role_config | json | null | {"<role_key>": {"enabled"?: true|false, "require_kyc"?: true|false, "verification_workflow"?: ""|null, "allow_skip"?: true|false}} | Per-role rules for the people behind the company. Role keys come from the existing config - never invent one. A role with require_kyc: true MUST also carry a verification_workflow (the uuid of a separate KYC workflow) or the save is rejected. A list of {"role": ..., ...} entries is accepted as an alternative to the map. |
kyb_shareholder_ownership_threshold | integer | null | integer >=0 <=100 | |
kyb_shareholder_verification_workflow | uuid | null | uuid | |
kyb_ubo_ownership_threshold | integer | null | integer >=0 <=100 | |
kyb_ubo_verification_workflow | uuid | null | uuid | |
kyb_wait_for_all_ubos | boolean | null | boolean | |
status_rules | array | array |
KYB_REGISTRY
| Key | Type | Accepts | Meaning |
|---|---|---|---|
kyb_accepted_countries | json | null | ["", ...] | Which company-registry countries the business may be incorporated in, as a list of ISO-2 codes (note: ISO-2 here, unlike the ISO-3 used by the OCR and IP allow-lists). An empty list or null accepts every supported registry. |
kyb_manual_company_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the company could not be found in a registry and was entered by hand. |
kyb_registry_countries_config | json | null | {"": {"enabled": true|false, "tier": "basic"|"shareholders"|"ubo"}} | Per-country registry routing configuration. Each enabled country selects the data tier charged when a company is selected. Only tiers marked available by the pricing endpoint can be enabled. At least one country must be enabled: a registry check that searches nowhere is rejected. Manual company entry does not use this configuration and is billed at its own flat fee of USD 0.75 per company. |
kyb_registry_fields_config | json | null | {"<registry_field>": {"enabled"?: true|false, "required"?: true|false}} | Per-registry-field overrides controlling which company details are collected and which of them are mandatory. Field keys come from the backend's configurable-field catalog (registration_number, incorporation_date, legal_address, vat_number, alternative_names, tax_number, company_type, legal_entity_identifier, location_of_registration, nature_of_business, registered_capital_amount, registered_capital_currency, website, email, phone, ...); an unknown key, or any sub-key other than enabled / required, is rejected. |
kyb_registry_monitoring_enabled | boolean | null | boolean | Keep the COMPANY's registry record under continuous monitoring after a Shareholders or UBO result: changes of status, officers, ownership or address move the session back to review and fire a webhook. Only where the registry provider offers monitoring; USD 2.00 per company per year, cancellable at any time. Off by default. |
kyb_vat_invalid_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the VAT number is rejected by the tax authority. |
kyb_vat_unverified_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the VAT number could not be checked at all. |
status_rules | array | array |
LIVENESS
Configuration for Liveness feature.
| Key | Type | Accepts | Meaning |
|---|---|---|---|
cross_org_fraud_face_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Deprecated and no longer applied. It treated a face as if it carried a fraud verdict. Use cross_org_identity_claim_pattern_action. |
cross_org_identity_claim_pattern_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when other organizations in the network recorded identity-claim events for this same person in which the claimed identity did not match. Review or no action only - a decline set here is downgraded to review. |
external_capture_device_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when an external capture device is detected. |
face_audio_recording_enabled | boolean | null | boolean | Record the microphone during the selfie capture, so a reviewer can hear the session. Off by default. |
face_liveness_attack_face_match_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the liveness face matches (above the duplicate-face similarity bar) a face from an earlier session of this application whose own capture the liveness engine judged an attack (risk FACE_MATCHES_LIVENESS_ATTACK), another user's session only and only a confident attack verdict. Review or no action only - a decline set here is downgraded to review, because a genuine user can be rejected once by mistake and then pass. Defaults to NO_ACTION (evidence is recorded, the verdict is unchanged). |
face_liveness_duplicated_face_document_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when a duplicate face is found on a user verified with a different date of birth. Another document of the same person (a passport after an identity card, a renewal, a document of a second country) is not flagged. |
face_liveness_duplicated_face_name_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when a duplicate face is found under a different name. |
face_liveness_flash_mode | string | null | string | |
face_liveness_max_attempts | integer | null | integer >=1 <=3 | |
face_liveness_method | string | null | 'ACTIVE_3D'|'FLASHING'|'PASSIVE' | |
face_liveness_mode | string | null | string | |
face_liveness_multiple_faces_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when more than one face is present in the capture. |
face_liveness_possible_duplicated_face_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when this face matches a previously seen user. |
face_liveness_score_decline_threshold | integer | null | integer >=0 <=100 | |
face_liveness_score_review_threshold | integer | null | integer >=0 <=100 | |
face_liveness_uncertain_retry_enabled | boolean | null | boolean | Native SDK active liveness only. On, a capture whose liveness score falls strictly between face_liveness_score_decline_threshold and face_liveness_score_review_threshold is never decided, whichever verdict the engine attached to it: the person is told the result was unclear and asked to capture again, every time, outside the face_liveness_max_attempts budget (which still applies to captures the engine could not score). Off by default; the web flow ignores it. |
face_liveness_video_anomaly_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the stored liveness recording contains a repeated moving sequence consistent with a looped video feed, measured server-side from the video itself, independently of the liveness score. It deliberately does NOT flag a frozen or near-motionless capture: frame statistics cannot separate an injected still from a genuine one (a subject holding still, or a flash that clips the exposure), so acting on that would decline real users. A frozen or pre-recorded injected feed is instead defeated by strict flash liveness (set face_liveness_flash_mode to "1" for strict), which binds the capture to a per-session colour-sequence challenge a recording cannot reproduce. Defaults to NO_ACTION (evidence is recorded, the verdict is unchanged). |
face_luminance_max_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the selfie is brighter than face_luminance_max_threshold. |
face_luminance_max_threshold | integer | null | integer >=0 <=100 | |
face_luminance_min_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the selfie is darker than face_luminance_min_threshold. |
face_luminance_min_threshold | integer | null | integer >=0 <=100 | |
face_privacy_mode_enabled | boolean | null | boolean | |
face_quality_decline_threshold | integer | null | integer >=0 <=100 | |
face_quality_review_threshold | integer | null | integer >=0 <=100 | |
face_search_enabled | boolean | null | boolean | Run the 1:N Face Search on the selfie: match it against previously verified users, the face blocklist and allowlist, and store its biometric template for later matching. On by default. Off skips the search, keeps no face template, and leaves the duplicate-face actions with nothing to act on. |
frame_injection_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when injected video frames are detected. |
race_map_similarity_thresholds | json | {"": {"possible": 0-100, "high": 0-100}} | Per-demographic overrides of the face-similarity bands used against the allow-list and duplicate-face sets, so match rates stay even across groups. possible is the lower band (defaults to 62) and high the upper (68); a group with no entry uses those defaults. |
screen_capture_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the selfie is a photo of a screen. |
status_rules | array | array | |
virtual_camera_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when a virtual camera feed is detected. |
NFC
Configuration for NFC/ePassport feature.
| Key | Type | Accepts | Meaning |
|---|---|---|---|
allow_nfc_skip | boolean | null | boolean | |
jpki_certificate_invalid_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when a My Number Card certificate does not chain to the JPKI certification authority, is outside its validity period or is not a card certificate of the requested type. Default DECLINE. |
jpki_certificate_revoked_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the revocation check reports a My Number Card certificate revoked. Default DECLINE. |
jpki_inconsistent_data_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the name, date of birth, sex or address in the My Number Card's signature certificate differs from the OCR data of the same card. Default REVIEW. |
jpki_request_attributes | boolean | null | boolean | Japan My Number Card (JPKI, native SDKs only): also read the signature certificate, which needs the card's signature PIN and carries the holder's name, date of birth, sex and address, compared with the OCR data. Default true; false reads only the user authentication certificate (4-digit PIN), which proves the card and PIN but carries no attributes. |
jpki_revocation_unchecked_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the My Number Card was verified but its revocation status could not be checked. Default REVIEW. |
jpki_signature_invalid_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the My Number Card's signature over the one-time challenge does not verify, so possession of the card and knowledge of its PIN are not proven. Default DECLINE. |
skip_nfc_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the user skips the NFC chip read (only reachable with allow_nfc_skip). |
status_rules | array | array | |
trust_anchor_missing_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when chip data-group hashes are intact but the certificate chain cannot be verified because the issuing country's CSCA trust anchor is not loaded. |
unverified_chip_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the chip is read but its signature cannot be verified. |
OCR
Configuration for OCR/ID Verification feature.
Omitting
documents_allowedstores the full country/document catalog, so the node accepts everything. Put OCR before any feature that reads identity data from the document (FACE_MATCH, NFC, DATABASE_VALIDATION).
| Key | Type | Accepts | Meaning |
|---|---|---|---|
address_not_verified_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when Address Validation could not confirm the address to the building (ADDRESS_NOT_VERIFIED: partially_verified or not_verified). Applies only while address_validation_enabled is on; an unavailable validation never raises it. Defaults to NO_ACTION, which only records the warning. |
address_validation_enabled | boolean | null | boolean | Validate the address this node reads (the one printed on the identity document, or the one on the proof of address) against postal reference data: it confirms the address exists and normalises it, and never links it to a person. The result is the address_validation object of the node's decision entry. A paid add-on, charged per address validated (a validation that could not run is free); off by default. |
age_restrictions_by_country | json | null | {"": {"minimum_age": 1-120, "maximum_age": 1-120|null, "states"?: {"<STATE_CODE>": {"minimum_age": 1-120, "maximum_age": 1-120|null}}}} | Per-country (and optionally per-state) age gate. minimum_age is required for every country listed; maximum_age may be null. |
critical_field_occlusion_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when a critical printed field - an identity number, a name, the date of birth or the expiry date - was physically covered on the captured document. Defaults to REVIEW. |
cross_org_fraud_document_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when this document was flagged as fraudulent by another organization in the network. |
document_audio_recording_enabled | boolean | null | boolean | Record the microphone during document capture, so a reviewer can hear the session. Off by default. |
document_blur_fields_by_country | json | null | {"": ["<blur_field_name>", ...]} | Fields to blur out of the stored document image, per country. Only fields the country's document layout supports are accepted. |
document_liveness_portrait_replace_decline_threshold | integer | null | integer >=0 <=100 | |
document_liveness_portrait_replace_review_threshold | integer | null | integer >=0 <=100 | |
document_liveness_printed_copy_decline_threshold | integer | null | integer >=0 <=100 | |
document_liveness_printed_copy_review_threshold | integer | null | integer >=0 <=100 | |
document_liveness_screen_replay_decline_threshold | integer | null | integer >=0 <=100 | |
document_liveness_screen_replay_review_threshold | integer | null | integer >=0 <=100 | |
document_or_personal_number_format_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the document or personal number does not match the country's expected format. |
document_selfie_duplicated_face_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the document-capture selfie matches, or possibly matches, the face of a user already verified in this application. |
document_selfie_duplicated_face_document_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the document-capture selfie matches a user already verified with a different date of birth. Another document of the same person (a passport after an identity card, a renewal, a document of a second country) is not flagged. Can only escalate document_selfie_duplicated_face_action. |
document_selfie_duplicated_face_name_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the document-capture selfie matches a user already verified under a different name. Can only escalate document_selfie_duplicated_face_action. |
document_selfie_face_search_enabled | boolean | null | boolean | Run the 1:N Face Search on the selfie taken during document capture (needs is_document_selfie_portrait_match_enabled): match it against the face blocklist and previously verified users. The selfie is a probe only, its template is never stored. On by default. Off skips the search and leaves the document-selfie duplicate-face actions with nothing to act on; face_search_enabled off on the LIVENESS step skips it too, since that opt-out covers every selfie of the session. |
document_selfie_portrait_match_decline_threshold | integer | null | integer >=0 <=100 | |
document_selfie_portrait_match_review_threshold | integer | null | integer >=0 <=100 | |
document_without_portrait_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the scanned document family carries no portrait on any side. Node-config only - there is no account-level setting; the runtime default is REVIEW. |
documents_allowed | json | null | {"": {"<DOC_CODE>": {"enabled": 0|1, "sides"?: 1|2, "subtypes"?: ["<SUBTYPE_CODE>", ...]}}} | Which identity documents are accepted, per issuing country. Omit the key entirely to accept the full catalog; an empty object means the same thing. At least one document must end up enabled or the save is rejected. |
duplicated_user_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the identity was already verified for this application. |
expected_details_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the extracted identity contradicts the expected_details sent with the session. |
expiration_date_not_detected_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when no expiry date could be read from the document. |
id_document_quality_threshold | integer | null | integer >=0 <=100 | |
id_verification_injection_attack_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the document (or the ID-lookup selfie) was injected rather than captured by the device's own camera (INJECTION_ATTACK_DETECTED): a software virtual camera, a camera feed generated by the page or by browser automation, a hooked camera, or an instrumentation tool attached to the app. Defaults to DECLINE: each of these proves the frames did not come from the device's own camera. Heuristic capture signals (FRAME_INJECTION_SUSPECTED and the others) are not covered and stay information. |
id_verification_max_retry_attempts | integer | null | integer >=2 <=5 | |
id_verification_name_match_score_threshold | integer | null | integer >=0 <=100 | |
image_capture_methods_allowed | array | null | ["CAMERA_SCAN" | "UPLOAD", ...] | Capture methods the end user may use for the document photo. Declared as a list of free strings, so the vocabulary is not in the field itself: CAMERA_SCAN (live capture) and UPLOAD (pick an existing file). An empty list falls back to the account default. |
image_quality_too_low_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when overall document image quality is below the bar. |
image_too_blurry_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the captured document image is too blurry to trust. |
image_too_bright_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the captured document image is overexposed. |
image_too_dark_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the captured document image is underexposed. |
inconsistent_data_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the document's own fields contradict each other. |
invalid_code_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when a document check digit or barcode fails validation. |
invalid_mrz_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the machine-readable zone is missing or inconsistent. |
invalid_validation_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when a document authenticity validation fails. |
is_age_restrictions_enabled | boolean | null | boolean | |
is_document_selfie_portrait_match_enabled | boolean | null | boolean | |
is_image_capture_review_screen_enabled | boolean | null | boolean | Show the user a review screen after each document capture, letting them retake the photo before it is submitted. Off by default. |
is_ocr_id_verification_data_review_enabled | boolean | null | boolean | Let the user review and correct the extracted identity data before the step completes. Off by default. A correction is scored against ocr_id_verification_data_review_critical_fields, and a disagreement takes the critical or the minor action accordingly. The review still runs when the workflow includes NFC - a later chip read simply supersedes it. |
maximum_age | integer | null | integer >=1 <=120 | |
maximum_age_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the holder is older than maximum_age. |
methods | json | null | {"": {"document": {"enabled": bool, "fallback_only"?: bool}, "id_lookup": {"enabled": bool, "source"?: "<source_id>"|null, "max_attempts": 1-5, "skip_liveness_and_face_match": bool, "on_partial_match": "fallback_to_document"|"decline", "on_no_match": "fallback_to_document"|"decline", "on_provider_error": "fallback_to_document"|"decline", "response_fields"?: ["<field_key>", ...]}, "wallet": {"enabled": bool, "providers": ["<wallet_id>", ...], "on_failure": "fallback_to_document"|"decline"|"retry"}}} | Which ID verification methods each country may use: document capture (today's behaviour), non-doc lookup against a government or other authoritative source, and digital identity wallets. Omit the key, or a country, or a method, and that country is document only. Every method must be available for the country in the capability catalog (GET workflow-graph/id-verification-methods-catalog/); wallets are an accept-list with no ordering. Each lookup fallback is fallback_to_document or decline; wallet.on_failure also accepts retry (see below); max_attempts (1-5, default 1) counts only lookups the registry answered. Where the catalog lists several lookup sources for a country, source picks exactly one by id; omitted means the country's default (the first listed). document.fallback_only: true keeps document capture out of the first screen: users start with the wallet or lookup and only those it fails reach document capture. It needs document capture enabled and a wallet or lookup in the country that falls back to it. wallet.on_failure: retry keeps a user whose sign-in failed on the wallet step to try again: the session is never declined for it and no document is offered. |
minimum_age | integer | null | integer >=1 <=120 | |
minimum_age_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the holder is younger than minimum_age. |
ocr_id_verification_data_review_critical_fields | array | null | ["first_name" | "last_name" | "date_of_birth" | ...] | Which extracted identity fields count as critical when the user edits the OCR result, so a mismatch takes the critical action rather than the minor one. |
ocr_id_verification_data_review_critical_mismatch_action | string | null | 'REVIEW'|'DECLINE' | Verdict when the user's edit disagrees with OCR on a critical field. |
ocr_id_verification_data_review_minor_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the user's edit disagrees with OCR on a non-critical field. |
status_rules | array | array | |
unparsed_address_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the document address could not be parsed into components. |
PHONE_VERIFICATION
Configuration for Phone Verification feature.
| Key | Type | Accepts | Meaning |
|---|---|---|---|
code_size | integer | null | integer >=4 <=8 | |
cross_org_fraud_phone_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when this number was flagged as fraudulent by another organization in the network. |
disposable_number_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the number belongs to a disposable-number provider. |
duplicated_phone_number_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the number was already verified for this application. |
fallback_to_native | boolean | null | boolean | |
high_risk_phone_action | string | null | 'REVIEW'|'DECLINE' | Verdict when the number carries a high risk signal. |
low_phone_trust_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the trust index is below phone_trust_index_threshold. |
phone_enrichment_enabled | boolean | null | boolean | |
phone_intelligence_score_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the enrichment score is worse than phone_intelligence_score_threshold. |
phone_intelligence_score_threshold | integer | null | integer >=0 <=100 | |
phone_max_check_attempts | integer | null | integer >=1 <=5 | |
phone_max_retries | integer | null | integer >=1 <=5 | |
phone_no_social_presence_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the social footprint check (phone_social_enabled) finds the number registered on none of the platforms it covers. |
phone_shared_device_mode | boolean | null | boolean | |
phone_social_enabled | boolean | null | boolean | |
phone_trust_index_threshold | integer | null | integer >=0 <=100 | |
phone_type_risk_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the line type itself is considered risky. |
phone_verification_countries | json | null | {"": {"<channel: sms|whatsapp|telegram|rcs|viber|zalo>": {"enabled": true|false, "max_retries": } | true|false}} | Which countries and delivery channels the one-time code may be sent through. It is a WHITELIST: a country absent from the map is not offered at all, and a channel absent from a listed country is skipped. max_retries overrides the node-level retry cap for that one channel. A bare boolean is the legacy form and still means enabled/disabled with the node-level cap. |
provider_key | string | null | string | |
recent_port_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the number was ported to a new carrier recently. |
status_rules | array | array | |
voip_number_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the number is VoIP rather than a real subscriber line. |
PROOF_OF_ADDRESS
Configuration for Proof of Address feature.
| Key | Type | Accepts | Meaning |
|---|---|---|---|
address_not_verified_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when Address Validation could not confirm the address to the building (ADDRESS_NOT_VERIFIED: partially_verified or not_verified). Applies only while address_validation_enabled is on; an unavailable validation never raises it. Defaults to NO_ACTION, which only records the warning. |
address_validation_enabled | boolean | null | boolean | Validate the address this node reads (the one printed on the identity document, or the one on the proof of address) against postal reference data: it confirms the address exists and normalises it, and never links it to a person. The result is the address_validation object of the node's decision entry. A paid add-on, charged per address validated (a validation that could not run is free); off by default. |
poa_document_authenticity_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the document fails authenticity checks. |
poa_document_issues_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the document is damaged, cropped or otherwise unusable. |
poa_document_unproven_text_replacement_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when a text field was blanked and re-typed in another font and the file holds no proof of whether its content changed (POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT). Other editing evidence on the same document stays under poa_document_authenticity_action; when both apply, the stricter action decides. |
poa_documents_allowed | json | null | {"": {"<DOC_CODE>": {"enabled": 0|1, "sides"?: 1|2, "subtypes"?: ["<SUBTYPE_CODE>", ...]}}} | Which proof-of-address documents are accepted, per issuing country. Same shape as OCR's documents_allowed; omit to accept the full catalog. |
poa_issue_date_not_detected_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when no issue date could be read from the document. |
poa_issuer_not_identified_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the issuing company or authority cannot be identified. |
poa_languages_allowed | json | null | {"<language_code>": 0|1} | Languages the proof-of-address document may be written in, as a flag per language code. Omit to accept every supported language. |
poa_max_attempts_exceeded_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the user runs out of poa_max_retry_attempts. |
poa_max_retry_attempts | integer | null | integer >=2 <=5 | |
poa_name_match_score_threshold | integer | null | integer >=0 <=100 | |
poa_name_or_address_mismatch_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the name or address on the document disagrees with the verified identity. |
poa_unparsable_or_invalid_address_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the address on the document cannot be parsed or is not a real address. |
poa_unsupported_document_type_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the uploaded document is not one of poa_documents_allowed. |
poa_unsupported_language_action | string | null | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the document language is not one of poa_languages_allowed. |
status_rules | array | array |
QUESTIONNAIRE
Configuration for Questionnaire feature.
| Key | Type | Accepts | Meaning |
|---|---|---|---|
questionnaire_uuid | uuid | null | uuid | |
review_questionnaire_manually | boolean | null | boolean | |
status_rules | array | array |
SIGNATURE
| Key | Type | Accepts | Meaning |
|---|---|---|---|
signature_consent_per_document | boolean | boolean | |
signature_declined_action | string | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the signer declines; nothing is charged. |
signature_document_changed_action | string | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when an original no longer matches its captured SHA-256. |
signature_documents | json | [{"uuid":"UUID", "title":"string", "file_name":"string", "pages":1, "size_bytes":1}] | Ordered documents previously uploaded to this workflow (a Word file is stored as its converted PDF); metadata is read from stored files. Fields placed on a document are managed on its signature-documents/{document}/fields/ route, not in this list. |
signature_documents_source | string | 'both'|'session'|'workflow' | |
signature_email_signed_copy | boolean | boolean | |
signature_evidence_page | boolean | boolean | |
signature_format | string | 'cades'|'pades'|'xades' | |
signature_identity_not_verified_action | string | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the signer lacks approved identity evidence. |
signature_level | string | 'aes'|'qes'|'simple' | simple (default) needs no ID verification, email or phone: the signer types their name (or uses a verified one the session already has) and signs on the session link, with no code. aes needs an approved ID verification and a verified email or phone, and confirms with a one-time code. qes (an add-on) needs an approved ID verification with a passport or national ID card and a verified phone (signature_otp_channel: sms), documents of at most 5 MB, and is refused while the workflow's signature_availability.qes is false; a qualified trust service provider texts the code and issues the signer a qualified certificate. simple is only valid for signature_signer: verified_person. Simple suits low-risk agreements; regulated or high-value contracts should use aes or qes. |
signature_link_validity_days | integer | integer >=1 <=30 | |
signature_name_mismatch_action | string | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict when the verified name does not match the requested signer. |
signature_otp_channel | string | 'email'|'sms' | |
signature_otp_failed_action | string | 'NO_ACTION'|'REVIEW'|'DECLINE' | Verdict after three invalid one-time codes. |
signature_require_read_to_end | boolean | boolean | |
signature_signer | string | 'key_people'|'legal_representative'|'verified_person' | |
status_rules | array | array |
Contributing
The feature-config contract above is generated - never hand-write a config key into a tool description. See CONTRIBUTING.md for the regeneration workflow and the checks that enforce it.
Issues and PRs welcome — see CONTRIBUTING.md. Run the hosted server at mcp.didit.me/mcp, or self-host from this repo (Docker / Node) — see Run it yourself.
License
MIT © Didit Protocol