@didit-protocol/mcp-server 5.1.36 → 5.1.51
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +201 -29
- package/dist/app-api-key.d.ts +5 -0
- package/dist/app-api-key.d.ts.map +1 -0
- package/dist/app-api-key.js +108 -0
- package/dist/app-api-key.js.map +1 -0
- package/dist/auth/cached-verifier.d.ts +38 -0
- package/dist/auth/cached-verifier.d.ts.map +1 -0
- package/dist/auth/cached-verifier.js +82 -0
- package/dist/auth/cached-verifier.js.map +1 -0
- package/dist/auth/introspection-verifier.d.ts +12 -0
- package/dist/auth/introspection-verifier.d.ts.map +1 -1
- package/dist/auth/introspection-verifier.js +40 -14
- package/dist/auth/introspection-verifier.js.map +1 -1
- package/dist/chatgpt-app.d.ts +1 -0
- package/dist/chatgpt-app.d.ts.map +1 -1
- package/dist/chatgpt-app.js +2 -0
- package/dist/chatgpt-app.js.map +1 -1
- package/dist/config.d.ts +12 -3
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +55 -8
- package/dist/config.js.map +1 -1
- package/dist/device-login.d.ts +98 -0
- package/dist/device-login.d.ts.map +1 -0
- package/dist/device-login.js +455 -0
- package/dist/device-login.js.map +1 -0
- package/dist/http.d.ts.map +1 -1
- package/dist/http.js +61 -5
- package/dist/http.js.map +1 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +595 -47
- package/dist/index.js.map +1 -1
- package/dist/investigator-agent.d.ts +4 -0
- package/dist/investigator-agent.d.ts.map +1 -0
- package/dist/investigator-agent.js +10 -0
- package/dist/investigator-agent.js.map +1 -0
- package/dist/login-cli.d.ts +6 -0
- package/dist/login-cli.d.ts.map +1 -0
- package/dist/login-cli.js +47 -0
- package/dist/login-cli.js.map +1 -0
- package/dist/mcp-modern.d.ts +1 -0
- package/dist/mcp-modern.d.ts.map +1 -1
- package/dist/mcp-modern.js +1 -1
- package/dist/mcp-modern.js.map +1 -1
- package/dist/permissions.d.ts.map +1 -1
- package/dist/permissions.js +29 -4
- package/dist/permissions.js.map +1 -1
- package/dist/privileged-tools.d.ts +1 -0
- package/dist/privileged-tools.d.ts.map +1 -1
- package/dist/privileged-tools.js +2 -1
- package/dist/privileged-tools.js.map +1 -1
- package/dist/schema/feature-config-schema.json +941 -28
- package/dist/security.d.ts +9 -8
- package/dist/security.d.ts.map +1 -1
- package/dist/security.js +11 -3
- package/dist/security.js.map +1 -1
- package/dist/signature-download.d.ts +31 -0
- package/dist/signature-download.d.ts.map +1 -0
- package/dist/signature-download.js +122 -0
- package/dist/signature-download.js.map +1 -0
- package/dist/tools/auth.d.ts +2 -0
- package/dist/tools/auth.d.ts.map +1 -1
- package/dist/tools/auth.js +114 -14
- package/dist/tools/auth.js.map +1 -1
- package/dist/tools/billing.d.ts +33 -2
- package/dist/tools/billing.d.ts.map +1 -1
- package/dist/tools/billing.js +252 -12
- package/dist/tools/billing.js.map +1 -1
- package/dist/tools/compliance.d.ts.map +1 -1
- package/dist/tools/compliance.js +37 -0
- package/dist/tools/compliance.js.map +1 -1
- package/dist/tools/investigator.d.ts +19 -0
- package/dist/tools/investigator.d.ts.map +1 -0
- package/dist/tools/investigator.js +449 -0
- package/dist/tools/investigator.js.map +1 -0
- package/dist/tools/members.d.ts +8 -0
- package/dist/tools/members.d.ts.map +1 -1
- package/dist/tools/members.js +73 -4
- package/dist/tools/members.js.map +1 -1
- package/dist/tools/observability.d.ts +6 -0
- package/dist/tools/observability.d.ts.map +1 -1
- package/dist/tools/observability.js +11 -3
- package/dist/tools/observability.js.map +1 -1
- package/dist/tools/search.d.ts.map +1 -1
- package/dist/tools/search.js +89 -5
- package/dist/tools/search.js.map +1 -1
- package/dist/tools/session-explain-levers.d.ts +6 -0
- package/dist/tools/session-explain-levers.d.ts.map +1 -1
- package/dist/tools/session-explain-levers.js +40 -7
- package/dist/tools/session-explain-levers.js.map +1 -1
- package/dist/tools/sessions.d.ts +24 -0
- package/dist/tools/sessions.d.ts.map +1 -1
- package/dist/tools/sessions.js +196 -2
- package/dist/tools/sessions.js.map +1 -1
- package/dist/tools/settings.d.ts.map +1 -1
- package/dist/tools/settings.js +3 -1
- package/dist/tools/settings.js.map +1 -1
- package/dist/tools/standalone.d.ts +5 -0
- package/dist/tools/standalone.d.ts.map +1 -1
- package/dist/tools/standalone.js +18 -2
- package/dist/tools/standalone.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -26,6 +26,16 @@ key protects the credentials embedded in the session-scoped link; rotating it
|
|
|
26
26
|
invalidates outstanding links. Treat links as secrets and redact the `token` query
|
|
27
27
|
parameter in proxy/access logs. Responses use `Cache-Control: no-store`.
|
|
28
28
|
|
|
29
|
+
### E-signature files
|
|
30
|
+
|
|
31
|
+
`didit_session_get_signature_evidence`, `didit_session_get_signed_document` and
|
|
32
|
+
`didit_session_get_signature_field_image` return the same kind of link (plus `content_type`)
|
|
33
|
+
for a signer's evidence PDF, the signed PDF of one document and the PNG of a signature field.
|
|
34
|
+
They use the same `MCP_PDF_DOWNLOAD_KEY` and `MCP_RESOURCE_URI`; route
|
|
35
|
+
`/downloads/session-signature` to this HTTP server as well. The file is checked against its
|
|
36
|
+
recorded SHA-256 at issuance and again at download. `didit_session_validate_signatures`
|
|
37
|
+
re-validates the signed documents and returns the result as JSON.
|
|
38
|
+
|
|
29
39
|
Stdio deployments need a reachable HTTP deployment with the same key, API base URL,
|
|
30
40
|
and `MCP_RESOURCE_URI`; stdio alone cannot serve download links. Missing key
|
|
31
41
|
configuration produces an actionable tool error instead of inline PDF data.
|
|
@@ -60,6 +70,36 @@ claude mcp add --transport http didit https://mcp.didit.me/mcp
|
|
|
60
70
|
|
|
61
71
|
See [per-client setup](https://docs.didit.me/integration/mcp/installation) for Claude Desktop and VS Code.
|
|
62
72
|
|
|
73
|
+
### Sign in without a browser (device code)
|
|
74
|
+
|
|
75
|
+
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](https://www.rfc-editor.org/rfc/rfc8628).
|
|
76
|
+
It also works for accounts that use a passkey or SSO and have no password.
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
npx -y @didit-protocol/mcp-server login
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
The terminal prints a short code and a link:
|
|
83
|
+
|
|
84
|
+
```
|
|
85
|
+
To connect this machine to your Didit account, open https://business.didit.me/device and enter the code WDJB-MJHT
|
|
86
|
+
Or open: https://business.didit.me/device?user_code=WDJB-MJHT
|
|
87
|
+
Approve only if the code on the page matches this one.
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Open the link on any device with a browser, sign in to Didit, check that the code matches and approve.
|
|
91
|
+
The command then saves your credentials and prints the scopes that were granted (never the token).
|
|
92
|
+
Approve only a code you started yourself.
|
|
93
|
+
|
|
94
|
+
- Credentials live in `~/.config/didit/mcp-credentials.json` (override with `DIDIT_MCP_CREDENTIALS_FILE`), readable by you only, one entry per Didit environment.
|
|
95
|
+
- The local server uses them automatically when `DIDIT_ACCESS_TOKEN` is not set, and refreshes them before they expire.
|
|
96
|
+
- `npx -y @didit-protocol/mcp-server logout` revokes the grant and deletes the stored credentials.
|
|
97
|
+
- Set `DIDIT_DEVICE_NAME` to change the name shown on the approval page (default: the machine's hostname).
|
|
98
|
+
- In CI, run `login` once on a trusted machine and mount the credentials file as a secret, or set `DIDIT_ACCESS_TOKEN` as before.
|
|
99
|
+
Do not share one credentials file between jobs that run at the same time, because refresh tokens rotate.
|
|
100
|
+
- No shell? Ask the agent to call `didit_account_device_login_start`, show you the link and code, then `didit_account_device_login_poll` once you approve.
|
|
101
|
+
Both tools exist only on the local server.
|
|
102
|
+
|
|
63
103
|
## Authentication
|
|
64
104
|
|
|
65
105
|
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.
|
|
@@ -67,6 +107,8 @@ The MCP is an OAuth 2.1 **resource server**; the Didit console (`business.didit.
|
|
|
67
107
|
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.
|
|
68
108
|
|
|
69
109
|
> **There is no API-key mode.** Every tool targets the user-scoped console endpoints (`/organization/{org}/application/{app}/…`), which authorize a Bearer token with per-role privileges and reject `x-api-key`. (For raw REST access with an application API key — e.g. creating sessions from your backend — use the [REST API](https://docs.didit.me) directly, not this server.)
|
|
110
|
+
>
|
|
111
|
+
> The one exception is the phone code pair, `didit_verify_phone_send` and `didit_verify_phone_check`: the console has no route for them, so the MCP reads the application's API key with your sign-in (a role with `create:sessions` and the `didit:management` scope, or an organization owner or admin for a local `didit_account_login` token) and calls the public phone API with it. The key is never returned, stored or logged.
|
|
70
112
|
|
|
71
113
|
See [Authentication](https://docs.didit.me/integration/mcp/authentication).
|
|
72
114
|
|
|
@@ -75,11 +117,52 @@ See [Authentication](https://docs.didit.me/integration/mcp/authentication).
|
|
|
75
117
|
140+ tools, grouped by area. The full catalogue with read/write/destructive markers is in [`docs/TOOLS.md`](docs/TOOLS.md) and at [docs.didit.me](https://docs.didit.me/integration/mcp/tools). Highlights:
|
|
76
118
|
|
|
77
119
|
- **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.
|
|
78
|
-
- **Sessions:** create, list, get decision, update status, reviews, bulk import, webhook delivery log + resend (`didit_session_webhooks` waits for a sandbox session's webhook so an integration can be verified end to end).
|
|
120
|
+
- **Sessions:** create, list, get decision, update status, reviews, bulk import, webhook delivery log + resend (`didit_session_webhooks` waits 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).
|
|
79
121
|
- **Verification APIs:** `didit_verify_id`, `didit_verify_aml`, `didit_verify_face_match`, `didit_verify_kyb_search`, …
|
|
80
122
|
- **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_catalog` and `didit_workflow_get_kyb_registry_catalog` answer 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).
|
|
123
|
+
- **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 without `confirm: true`, which a client sends only after the user approves that exact action. Every Investigator call sends `X-Didit-Actor-Via: mcp` (or `copilot` when the console assistant marks its request so), so the Investigator Activity shows where the user acted from.
|
|
81
124
|
- **Compliance:** transaction monitoring, custom and preset rule management with backtesting, lists/blocklist/allowlist, cases, reports, audit logs, alerts.
|
|
82
125
|
- **Workspace:** questionnaires, webhooks, members, billing, branding.
|
|
126
|
+
- **API key for your integration:** `didit_org_create_api_key` creates 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.
|
|
127
|
+
The secret is returned once; the person sees the key with the connected app in the console and can revoke it there.
|
|
128
|
+
- **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_details` and `didit_billing_update_details`.
|
|
129
|
+
No tool charges a card: when credit or a plan change is needed, the tools return console links (`next_steps.top_up_url` opens the top-up dialog with the amount filled in) and the person pays there.
|
|
130
|
+
The local stdio server and the unlisted `/mcp/payments` endpoint (below) also offer `didit_org_top_up`.
|
|
131
|
+
|
|
132
|
+
### Agent payments (`/mcp/payments`, stdio)
|
|
133
|
+
|
|
134
|
+
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.
|
|
135
|
+
`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.
|
|
136
|
+
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.
|
|
137
|
+
The local stdio server offers the same tool.
|
|
138
|
+
|
|
139
|
+
`didit_org_top_up` parameters:
|
|
140
|
+
|
|
141
|
+
| Parameter | Description |
|
|
142
|
+
|---|---|
|
|
143
|
+
| `amount_in_dollars` | USD, $50 to $20,000 per top-up. |
|
|
144
|
+
| `confirm` | Required, `true`, only after the person approved this exact action. |
|
|
145
|
+
| `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. |
|
|
146
|
+
| `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. |
|
|
147
|
+
|
|
148
|
+
`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).
|
|
149
|
+
While it is on, the saved primary card is charged off session at the normal self-serve amounts ($50 to $20,000).
|
|
150
|
+
`didit_org_get_balance` shows the switch as `agent_top_up: {enabled}` on `/mcp/payments` and stdio (and nowhere else).
|
|
151
|
+
A successful call returns the backend body (`outcome`, `top_up`).
|
|
152
|
+
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.
|
|
153
|
+
|
|
154
|
+
| Code | Meaning | The person |
|
|
155
|
+
|---|---|---|
|
|
156
|
+
| `agent_top_up_not_enabled` | The switch is off (the default). | Tops up in the console, or turns the switch on. |
|
|
157
|
+
| `authentication_required` | The card's bank asks the cardholder to approve; nothing was charged. | Approves it in the console. |
|
|
158
|
+
| `payment_method_required` | No saved card. | Adds a card. |
|
|
159
|
+
| `card_declined` | The card was declined. | Tops up in the console. |
|
|
160
|
+
| `billing_address_required`, `top_up_in_progress`, `payment_provider_error` | See `detail`. | Follows `next_step` (retry with the same key where it says so). |
|
|
161
|
+
|
|
162
|
+
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).
|
|
163
|
+
`didit_org_top_up` with `checkout` returns the same signed link as `next_steps.console_top_up_url`.
|
|
164
|
+
|
|
165
|
+
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.
|
|
83
166
|
|
|
84
167
|
### File inputs
|
|
85
168
|
|
|
@@ -119,7 +202,7 @@ A key that is not listed here is not part of the contract and is dropped silentl
|
|
|
119
202
|
|
|
120
203
|
<!-- BEGIN GENERATED FEATURE CONFIG REFERENCE -->
|
|
121
204
|
|
|
122
|
-
_Generated from `schema/feature-config-schema.json` (contract `sha256:
|
|
205
|
+
_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`._
|
|
123
206
|
|
|
124
207
|
### AGE_ESTIMATION
|
|
125
208
|
|
|
@@ -132,6 +215,7 @@ Configuration for Age Estimation feature.
|
|
|
132
215
|
| `enable_id_verification_fallback` | boolean \| null | boolean | |
|
|
133
216
|
| `external_capture_device_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when an external capture device is detected. |
|
|
134
217
|
| `face_audio_recording_enabled` | boolean \| null | boolean | Record the microphone during the selfie capture, so a reviewer can hear the session. Off by default. |
|
|
218
|
+
| `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). |
|
|
135
219
|
| `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. |
|
|
136
220
|
| `face_liveness_duplicated_face_name_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when a duplicate face is found under a different name. |
|
|
137
221
|
| `face_liveness_flash_mode` | string \| null | string | |
|
|
@@ -166,7 +250,7 @@ Configuration for AML feature (used for both KYC AML and KYB Company AML).
|
|
|
166
250
|
| `aml_country_weight` | integer \| null | integer >=0 <=100 | |
|
|
167
251
|
| `aml_dob_weight` | integer \| null | integer >=0 <=100 | |
|
|
168
252
|
| `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. |
|
|
169
|
-
| `aml_field_sources` | json \| null | {"full_name"\|"date_of_birth"\|"nationality"\|"document_number": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "<docai field key>\|<questionnaire node id>\|expected_details.<expected_details field>\|metadata.<key>"}} | 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
|
|
253
|
+
| `aml_field_sources` | json \| null | {"full_name"\|"date_of_birth"\|"nationality"\|"document_number": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "<docai field key>\|<questionnaire node id>\|expected_details.<expected_details field>\|metadata.<key>"}} | 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. |
|
|
170
254
|
| `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. |
|
|
171
255
|
| `aml_match_score_threshold` | integer \| null | integer >=0 <=100 | |
|
|
172
256
|
| `aml_name_weight` | integer \| null | integer >=0 <=100 | |
|
|
@@ -193,40 +277,74 @@ Configuration for Bank Verification feature.
|
|
|
193
277
|
|
|
194
278
|
| Key | Type | Accepts | Meaning |
|
|
195
279
|
| --- | --- | --- | --- |
|
|
280
|
+
| `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). |
|
|
281
|
+
| `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. |
|
|
282
|
+
| `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. |
|
|
283
|
+
| `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. |
|
|
284
|
+
| `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. |
|
|
285
|
+
| `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. |
|
|
196
286
|
| `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`). |
|
|
197
|
-
| `
|
|
198
|
-
| `
|
|
287
|
+
| `bank_account_type_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the verified account is a savings account. |
|
|
288
|
+
| `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`. |
|
|
289
|
+
| `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`. |
|
|
290
|
+
| `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. |
|
|
291
|
+
| `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. |
|
|
292
|
+
| `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. |
|
|
199
293
|
| `bank_business_account_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the institution types the holder as a business rather than a person. |
|
|
294
|
+
| `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. |
|
|
200
295
|
| `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. |
|
|
201
296
|
| `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`. |
|
|
202
|
-
| `
|
|
297
|
+
| `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. |
|
|
298
|
+
| `bank_countries` | json \| null | {"<ISO3>": {"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. |
|
|
203
299
|
| `bank_country_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the institution's country differs from the expected/document country. |
|
|
204
300
|
| `bank_currency_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the account currency is not in `bank_expected_currencies`. |
|
|
301
|
+
| `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. |
|
|
302
|
+
| `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. |
|
|
303
|
+
| `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`. |
|
|
205
304
|
| `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. |
|
|
305
|
+
| `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. |
|
|
306
|
+
| `bank_email_match_threshold` | integer \| null | integer >=50 <=100 | At or above this score the email matches, 50 to 100, defaulting to 70. |
|
|
307
|
+
| `bank_email_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the holder's email differs. Only with `bank_email_match_enabled`. |
|
|
308
|
+
| `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. |
|
|
206
309
|
| `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`. |
|
|
207
|
-
| `
|
|
310
|
+
| `bank_fallback_used_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the account was verified with micro-deposits or a statement upload. |
|
|
311
|
+
| `bank_field_sources` | json \| null | {"full_name"\|"first_name"\|"last_name"\|"address"\|"date_of_birth"\|"phone"\|"email": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "<docai field key>\|<questionnaire node id>\|expected_details.<expected_details field>\|metadata.<key>"}} | 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. |
|
|
208
312
|
| `bank_joint_account_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the account has more than one holder. |
|
|
209
313
|
| `bank_low_balance_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the available balance is below `bank_min_balance`. Needs the `balances` scope. |
|
|
210
|
-
| `
|
|
314
|
+
| `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. |
|
|
315
|
+
| `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`. |
|
|
316
|
+
| `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. |
|
|
317
|
+
| `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. |
|
|
211
318
|
| `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. |
|
|
319
|
+
| `bank_mule_score_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the mule score is at or above `bank_mule_score_threshold`. |
|
|
320
|
+
| `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). |
|
|
212
321
|
| `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. |
|
|
213
322
|
| `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`). |
|
|
214
323
|
| `bank_not_verifiable_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the institution connected but returned no holder identity to compare. |
|
|
324
|
+
| `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. |
|
|
215
325
|
| `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. |
|
|
216
|
-
| `bank_partial_match_floor` | integer \| null | integer >=0 <=99 |
|
|
217
|
-
| `
|
|
326
|
+
| `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. |
|
|
327
|
+
| `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. |
|
|
328
|
+
| `bank_phone_match_threshold` | integer \| null | integer >=50 <=100 | At or above this score the phone matches, 50 to 100, defaulting to 70. |
|
|
329
|
+
| `bank_phone_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the holder's phone differs. Only with `bank_phone_match_enabled`. |
|
|
330
|
+
| `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. |
|
|
331
|
+
| `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`. |
|
|
218
332
|
| `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`. |
|
|
219
333
|
| `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`. |
|
|
220
|
-
| `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
|
|
334
|
+
| `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. |
|
|
221
335
|
| `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. |
|
|
222
|
-
| `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. A scope that is off is never requested from the provider, so the bank never shows it on its consent screen. |
|
|
336
|
+
| `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. |
|
|
223
337
|
| `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. |
|
|
224
|
-
| `bank_skipped_action` | string \| null | 'REVIEW'\|'DECLINE' | Verdict when the
|
|
338
|
+
| `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. |
|
|
339
|
+
| `bank_statement_document_checks_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when an uploaded statement carries editing or tampering evidence. Defaults to `REVIEW`. |
|
|
340
|
+
| `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. |
|
|
341
|
+
| `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. |
|
|
225
342
|
| `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. |
|
|
226
343
|
| `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. |
|
|
227
|
-
| `
|
|
344
|
+
| `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. |
|
|
345
|
+
| `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. |
|
|
228
346
|
| `bank_unknown_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the evidence could not be fetched after retries - a transient failure. |
|
|
229
|
-
| `bank_unsupported_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the
|
|
347
|
+
| `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. |
|
|
230
348
|
| `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. |
|
|
231
349
|
| `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. |
|
|
232
350
|
| `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. |
|
|
@@ -239,8 +357,8 @@ Configuration for Database Validation feature.
|
|
|
239
357
|
|
|
240
358
|
| Key | Type | Accepts | Meaning |
|
|
241
359
|
| --- | --- | --- | --- |
|
|
242
|
-
| `database_validation_countries` | json \| null | {"<ISO3>": {"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)
|
|
243
|
-
| `database_validation_field_sources` | json \| null | {"<db_validation_input_field>": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "<docai field key>\|<questionnaire node id>\|expected_details.<expected_details field>\|metadata.<key>"}} | 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
|
|
360
|
+
| `database_validation_countries` | json \| null | {"<ISO3>": {"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. |
|
|
361
|
+
| `database_validation_field_sources` | json \| null | {"<db_validation_input_field>": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "<docai field key>\|<questionnaire node id>\|expected_details.<expected_details field>\|metadata.<key>"}} | 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. |
|
|
244
362
|
| `database_validation_no_match_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the database returns no match at all. |
|
|
245
363
|
| `database_validation_not_applicable_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when no selected database covers the holder's country or document. |
|
|
246
364
|
| `database_validation_partial_match_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the database matches some, but not all, of the submitted fields. |
|
|
@@ -309,32 +427,48 @@ Configuration for the Precise Location (GEOLOCATION) feature. Every threshold is
|
|
|
309
427
|
|
|
310
428
|
| Key | Type | Accepts | Meaning |
|
|
311
429
|
| --- | --- | --- | --- |
|
|
312
|
-
| `geolocation_accuracy_mode` | string \| null | 'approximate_allowed'\|'precise' |
|
|
313
|
-
| `geolocation_allow_qr_handoff` | boolean \| null | boolean |
|
|
314
|
-
| `geolocation_allow_skip` | boolean \| null | boolean |
|
|
430
|
+
| `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. |
|
|
431
|
+
| `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. |
|
|
432
|
+
| `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. |
|
|
315
433
|
| `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. |
|
|
316
|
-
| `
|
|
434
|
+
| `geolocation_areas` | json \| null | [{"id": "<1-64 of A-Z a-z 0-9 _ ->", "label"?: "<text>", "type": "allowed"\|"blocked", "kind": "country", "country": "<ISO3>"} \| {..., "kind": "region", "country": "<ISO3>", "regions": ["<ISO 3166-2>", ...]} \| {..., "kind": "circle", "center": {"latitude": <num>, "longitude": <num>}, "radius_km": <1-500>} \| {..., "kind": "polygon", "points": [{"latitude": <num>, "longitude": <num>}, ...]}] | 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`. |
|
|
435
|
+
| `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. |
|
|
436
|
+
| `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. |
|
|
437
|
+
| `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. |
|
|
438
|
+
| `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. |
|
|
317
439
|
| `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. |
|
|
318
|
-
| `
|
|
440
|
+
| `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). |
|
|
441
|
+
| `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. |
|
|
319
442
|
| `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. |
|
|
443
|
+
| `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. |
|
|
320
444
|
| `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. |
|
|
321
445
|
| `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`. |
|
|
322
446
|
| `geolocation_geofencing_by_country` | json \| null | {"<ISO3>": {"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. |
|
|
323
447
|
| `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. |
|
|
324
448
|
| `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. |
|
|
325
|
-
| `geolocation_ip_distance_km` | integer \| null | integer >=0 |
|
|
449
|
+
| `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. |
|
|
326
450
|
| `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. |
|
|
327
451
|
| `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. |
|
|
328
|
-
| `
|
|
452
|
+
| `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. |
|
|
453
|
+
| `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. |
|
|
329
454
|
| `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. |
|
|
330
|
-
| `geolocation_max_age_seconds` | integer \| null | integer |
|
|
331
|
-
| `geolocation_max_attempts` | integer \| null | integer |
|
|
455
|
+
| `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`. |
|
|
456
|
+
| `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. |
|
|
332
457
|
| `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). |
|
|
333
458
|
| `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. |
|
|
459
|
+
| `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. |
|
|
460
|
+
| `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. |
|
|
461
|
+
| `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. |
|
|
462
|
+
| `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). |
|
|
334
463
|
| `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. |
|
|
335
|
-
| `geolocation_timeout_seconds` | integer \| null | integer |
|
|
464
|
+
| `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`. |
|
|
465
|
+
| `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. |
|
|
466
|
+
| `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. |
|
|
467
|
+
| `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. |
|
|
468
|
+
| `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. |
|
|
336
469
|
| `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. |
|
|
337
|
-
| `
|
|
470
|
+
| `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. |
|
|
471
|
+
| `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. |
|
|
338
472
|
| `status_rules` | array | array | |
|
|
339
473
|
|
|
340
474
|
### IP_ANALYSIS
|
|
@@ -352,6 +486,8 @@ Configuration for Device & IP Analysis feature.
|
|
|
352
486
|
| `device_emulator_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the device is an emulator rather than real hardware. |
|
|
353
487
|
| `device_hooking_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when runtime hooking or instrumentation is detected. |
|
|
354
488
|
| `device_integrity_missing_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when no platform device-integrity attestation was returned. |
|
|
489
|
+
| `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). |
|
|
490
|
+
| `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). |
|
|
355
491
|
| `device_rooted_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the device is rooted or jailbroken. |
|
|
356
492
|
| `duplicated_device_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when this device was already used by another verified user. |
|
|
357
493
|
| `duplicated_ip_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when this IP was already used by another verified user. |
|
|
@@ -377,6 +513,7 @@ Configuration for Device & IP Analysis feature.
|
|
|
377
513
|
| `kyb_document_non_critical_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when a document contradicts the registry on a minor detail. |
|
|
378
514
|
| `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. |
|
|
379
515
|
| `kyb_document_tampering_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when a company document looks tampered with. |
|
|
516
|
+
| `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. |
|
|
380
517
|
| `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. |
|
|
381
518
|
| `status_rules` | array | array | |
|
|
382
519
|
|
|
@@ -430,6 +567,7 @@ Configuration for Liveness feature.
|
|
|
430
567
|
| `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. |
|
|
431
568
|
| `external_capture_device_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when an external capture device is detected. |
|
|
432
569
|
| `face_audio_recording_enabled` | boolean \| null | boolean | Record the microphone during the selfie capture, so a reviewer can hear the session. Off by default. |
|
|
570
|
+
| `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). |
|
|
433
571
|
| `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. |
|
|
434
572
|
| `face_liveness_duplicated_face_name_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when a duplicate face is found under a different name. |
|
|
435
573
|
| `face_liveness_flash_mode` | string \| null | string | |
|
|
@@ -463,6 +601,12 @@ Configuration for NFC/ePassport feature.
|
|
|
463
601
|
| Key | Type | Accepts | Meaning |
|
|
464
602
|
| --- | --- | --- | --- |
|
|
465
603
|
| `allow_nfc_skip` | boolean \| null | boolean | |
|
|
604
|
+
| `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. |
|
|
605
|
+
| `jpki_certificate_revoked_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the revocation check reports a My Number Card certificate revoked. Default DECLINE. |
|
|
606
|
+
| `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. |
|
|
607
|
+
| `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. |
|
|
608
|
+
| `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. |
|
|
609
|
+
| `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. |
|
|
466
610
|
| `skip_nfc_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the user skips the NFC chip read (only reachable with `allow_nfc_skip`). |
|
|
467
611
|
| `status_rules` | array | array | |
|
|
468
612
|
| `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. |
|
|
@@ -475,6 +619,8 @@ Configuration for OCR/ID Verification feature.
|
|
|
475
619
|
|
|
476
620
|
| Key | Type | Accepts | Meaning |
|
|
477
621
|
| --- | --- | --- | --- |
|
|
622
|
+
| `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. |
|
|
623
|
+
| `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. |
|
|
478
624
|
| `age_restrictions_by_country` | json \| null | {"<ISO3>": {"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. |
|
|
479
625
|
| `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. |
|
|
480
626
|
| `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. |
|
|
@@ -499,6 +645,7 @@ Configuration for OCR/ID Verification feature.
|
|
|
499
645
|
| `expected_details_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the extracted identity contradicts the `expected_details` sent with the session. |
|
|
500
646
|
| `expiration_date_not_detected_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when no expiry date could be read from the document. |
|
|
501
647
|
| `id_document_quality_threshold` | integer \| null | integer >=0 <=100 | |
|
|
648
|
+
| `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. |
|
|
502
649
|
| `id_verification_max_retry_attempts` | integer \| null | integer >=2 <=5 | |
|
|
503
650
|
| `id_verification_name_match_score_threshold` | integer \| null | integer >=0 <=100 | |
|
|
504
651
|
| `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. |
|
|
@@ -516,7 +663,7 @@ Configuration for OCR/ID Verification feature.
|
|
|
516
663
|
| `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. |
|
|
517
664
|
| `maximum_age` | integer \| null | integer >=1 <=120 | |
|
|
518
665
|
| `maximum_age_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the holder is older than `maximum_age`. |
|
|
519
|
-
| `methods` | json \| null | {"<ISO3>": {"document": {"enabled": 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"}}} | 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 fallback is `fallback_to_document` or `decline`; `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). |
|
|
666
|
+
| `methods` | json \| null | {"<ISO3>": {"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. |
|
|
520
667
|
| `minimum_age` | integer \| null | integer >=1 <=120 | |
|
|
521
668
|
| `minimum_age_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the holder is younger than `minimum_age`. |
|
|
522
669
|
| `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. |
|
|
@@ -560,8 +707,11 @@ Configuration for Proof of Address feature.
|
|
|
560
707
|
|
|
561
708
|
| Key | Type | Accepts | Meaning |
|
|
562
709
|
| --- | --- | --- | --- |
|
|
710
|
+
| `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. |
|
|
711
|
+
| `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. |
|
|
563
712
|
| `poa_document_authenticity_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the document fails authenticity checks. |
|
|
564
713
|
| `poa_document_issues_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the document is damaged, cropped or otherwise unusable. |
|
|
714
|
+
| `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. |
|
|
565
715
|
| `poa_documents_allowed` | json \| null | {"<ISO3>": {"<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. |
|
|
566
716
|
| `poa_issue_date_not_detected_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when no issue date could be read from the document. |
|
|
567
717
|
| `poa_issuer_not_identified_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the issuing company or authority cannot be identified. |
|
|
@@ -585,6 +735,28 @@ Configuration for Questionnaire feature.
|
|
|
585
735
|
| `review_questionnaire_manually` | boolean \| null | boolean | |
|
|
586
736
|
| `status_rules` | array | array | |
|
|
587
737
|
|
|
738
|
+
### SIGNATURE
|
|
739
|
+
|
|
740
|
+
| Key | Type | Accepts | Meaning |
|
|
741
|
+
| --- | --- | --- | --- |
|
|
742
|
+
| `signature_consent_per_document` | boolean | boolean | |
|
|
743
|
+
| `signature_declined_action` | string | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the signer declines; nothing is charged. |
|
|
744
|
+
| `signature_document_changed_action` | string | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when an original no longer matches its captured SHA-256. |
|
|
745
|
+
| `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. |
|
|
746
|
+
| `signature_documents_source` | string | 'both'\|'session'\|'workflow' | |
|
|
747
|
+
| `signature_email_signed_copy` | boolean | boolean | |
|
|
748
|
+
| `signature_evidence_page` | boolean | boolean | |
|
|
749
|
+
| `signature_format` | string | 'cades'\|'pades'\|'xades' | |
|
|
750
|
+
| `signature_identity_not_verified_action` | string | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the signer lacks approved identity evidence. |
|
|
751
|
+
| `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`. |
|
|
752
|
+
| `signature_link_validity_days` | integer | integer >=1 <=30 | |
|
|
753
|
+
| `signature_name_mismatch_action` | string | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the verified name does not match the requested signer. |
|
|
754
|
+
| `signature_otp_channel` | string | 'email'\|'sms' | |
|
|
755
|
+
| `signature_otp_failed_action` | string | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict after three invalid one-time codes. |
|
|
756
|
+
| `signature_require_read_to_end` | boolean | boolean | |
|
|
757
|
+
| `signature_signer` | string | 'key_people'\|'legal_representative'\|'verified_person' | |
|
|
758
|
+
| `status_rules` | array | array | |
|
|
759
|
+
|
|
588
760
|
<!-- END GENERATED FEATURE CONFIG REFERENCE -->
|
|
589
761
|
|
|
590
762
|
## Contributing
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
/** Request headers for a public product API that authenticates with the application API key. */
|
|
2
|
+
export declare function applicationApiKeyHeaders(): Promise<Record<string, string>>;
|
|
3
|
+
/** The resolved application's API key, read fresh on every call. */
|
|
4
|
+
export declare function applicationApiKey(): Promise<string>;
|
|
5
|
+
//# sourceMappingURL=app-api-key.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"app-api-key.d.ts","sourceRoot":"","sources":["../src/app-api-key.ts"],"names":[],"mappings":"AA2CA,gGAAgG;AAChG,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAEhF;AAED,oEAAoE;AACpE,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,CAuCzD"}
|