Customer verification policies

Configure verification rules in Console → Settings → Verification policy, or through the API and SDKs. The backend enforces the same policy for hosted KYC, asynchronous /v1/verify, synchronous /v1/verify/id-document, and KYB. Client hints and UI props cannot waive server rules. The standalone selfie/profile comparison endpoint is a face-comparison utility; it does not establish document country, nationality, age, or full KYC approval.

Available rules

Group	Settings
Countries	Separate allowed/blocked lists for ID-issuing countries, nationalities, and company-registration countries. Use uppercase ISO 3166-1 alpha-2 codes, such as SZ and ZA. Nationality restrictions also apply to submitted KYB directors.
Decision thresholds	Minimum face and OCR scores for automatic approval and for entering manual review. Both scores must meet the relevant band. Scores below either review floor reject. Scores are 0–100. Review floors cannot exceed approval thresholds.
Manual review	Require manual review for every otherwise approved KYC result. This does not upgrade a hard rejection.
Identity documents	Accepted types: national_id, passport, drivers_license; require a back image; minimum remaining validity in days (0–3650).
Age	Minimum and maximum completed years, each nullable or 0–120. Birthdays are evaluated as calendar dates.
KYB	Mandatory/optional signatory KYC, required director DOB/nationality, and additional required supporting documents. Customer requirements cannot waive the platform country checklist.
Hosted links	Action-session lifetime: 5–1440 minutes. KYB resume-link lifetime: 1–90 days.

An empty allowed-country list permits all countries except those blocked. A country cannot appear in both lists. When restrictions apply, missing or unrecognized OCR evidence routes KYC to manual review; it is never treated as a permitted country. Explicitly disallowed evidence rejects. Issuing country is not inferred from nationality. KYB director input with missing/unrecognized/disallowed nationality is rejected when the policy requires that information, before storing or screening the roster.

Document type is checked against the actual OCR result, in addition to validating the caller's hint. Unknown identity document type requires review. Expired documents and detected spoofing still reject; missing expiry, uncertain liveness, and AML hits/errors still block automatic approval. Customer policy cannot disable these platform checks.

The existing Require liveness setting remains in Console Settings and at PUT /v1/account/liveness. Its value is included alongside the policy configuration and captured on accepted cases. Branding, webhooks, retention and billing continue to use their existing settings endpoints.

API

Authenticate with a live X-API-Key or console session to edit policy. Sandbox keys can read the account policy and test KYC with the fixed sandbox identity, but cannot modify live-account settings or create live credentials. A simulation may be made stricter by policy; sandbox country ZZ is intentionally not a real jurisdiction and will require review under a country restriction. No paid providers are called in sandbox.

• GET /v1/settings/verification-policy returns { success: true, data: { version, config, requireLiveness, origin } }.
• PUT /v1/settings/verification-policy accepts the entire configuration, plus the last-read version: { version, config }.
• GET /v1/settings/verification-policy/history returns up to 100 revisions, newest first, including the saved configuration, actor and timestamp.

Unknown fields, invalid country codes, duplicate/conflicting entries, invalid ranges and missing required configuration sections return 400 VALIDATION_ERROR. A stale version returns 409 POLICY_VERSION_CONFLICT: reload and reconcile the changes before saving. The server does not overwrite another operator's policy or retry the write automatically. An upload or creation that violates policy returns 400 VERIFICATION_POLICY_VIOLATION. Global account writes using a sandbox key return 403 LIVE_KEY_REQUIRED.

Node example

Use SDK 1.1.0 or later. SDK repositories require GitHub access; these versions are Git tags, not public registry releases.

const current = await client.getVerificationPolicy();
const config = structuredClone(current.config);
config.countries.allowedIssuingCountries = ['SZ', 'ZA'];
config.countries.blockedIssuingCountries = [];
config.kyc.autoApproveFaceScore = 95;
config.kyc.autoApproveOcrConfidence = 80;
config.kyc.manualReviewFaceScore = 70;
config.kyc.manualReviewOcrConfidence = 50;
config.kyc.minimumAge = 18;
config.kyc.minimumDocumentValidityDays = 30;
config.kyc.allowedDocumentTypes = ['passport', 'national_id'];
config.kyb.requireSignatory = true;
config.kyb.additionalDocuments = [
  { docType: 'source_of_funds', label: 'Source of funds evidence' },
];
const saved = await client.updateVerificationPolicy(current.version, config);
const history = await client.getVerificationPolicyHistory();

SDKs and capture

Node and React Native clients expose getVerificationPolicy, updateVerificationPolicy(version, config) and getVerificationPolicyHistory. React exports getVerificationPolicy({ apiKey, baseUrl }) and updateVerificationPolicy(options, version, config); its widget loads the server policy before capture and honors mandatory back-image and liveness capture.

Flutter exposes the same three client methods using maps; Kotlin uses JSONObject. Swift exposes typed VerificationPolicySettings/VerificationPolicy models and updateVerificationPolicy(version:config:). Nullable policy fields must remain JSON null when writing the complete configuration; the Swift SDK handles this explicitly.

For native capture UIs, fetch policy before constructing the screen, choose a permitted document type, and pass config.kyc.requireIdBack and the account's requireLiveness to supported capture options. When using custom capture, supply both liveness frames and the challenge through the client when liveness is required. Hosted verification reads the policy automatically, limits document choices, collects additional KYB documents, and applies configured session lifetimes. The server still enforces every rule if a client omits or alters those UI options.

CLI 0.2.0 adds policy-get, policy-set --file policy.json (a {version,config} JSON file), and policy-history. MCP 0.2.0 exposes get_verification_policy, update_verification_policy, and get_verification_policy_history for the same workflow.

Policy history and accepted cases

Each accepted KYC/KYB case stores a policySnapshot containing the configuration, version and liveness setting. Changing account policy affects new cases; processing retries and KYB resume/review use the accepted case's snapshot. Signatory KYC inherits the parent company's policy. The platform KYB country-document matrix remains centrally managed and is not editable by customers.

Records existing before this feature are explicitly marked origin: migration-baseline. This records a migration baseline, not a claim that an original historical customer policy was recovered. New accepted cases are marked origin: customer-policy. Policy history is scoped to the authenticated customer, and concurrent edits use an atomic version check.

Scope

These settings do not implement residence verification, beneficial-owner ownership-percentage rules, team roles or dual-review approval, localization, per-key scopes/expiry, or arbitrary webhook event subscriptions. Those fields are not accepted as configuration. Retention settings are separate: a saved retention window does not prove a scheduled purge has run.