Identity verification API

Verify identities, run hosted verification sessions, batch and re-verify, store evidence, read extracted identity details, and receive signed KYC, KYB and KYM webhooks.

Credential: ApiKeyAuth, SessionTokenAuth. See Authentication.

Verify an identity

POST /v1/kyc/verify

Two branches, selected by the body’s action field (verify is the implicit default when action is omitted — every pre-existing caller is unaffected):

action:'verify' admits, screens, policy-enforces, and finalizes a single identity verification against the tenant’s configured provider. The admission → spend-reservation → provider-call → finalize pipeline is shared byte-for-byte with the hosted-session submit path (POST /v1/kyc/session-submit) and the batch processor — there is exactly one verify pipeline in this system. It requires a nonce obtained from a prior action:'mint' call to the SAME endpoint (the only route that legitimately issues one) or a valid hosted-session-derived nonce.

action:'mint' issues that admission nonce: a fresh, tenant-scoped, single-use nonce bound in KV to the calling tenant (TTL 300s). It is the ONLY way a server-to-server caller can obtain a nonce a subsequent action:'verify' call will accept — without it, evidence-handle/cross-match/reverify are unreachable S2S, since every one of those requires an admitted verificationId a real verify call produces. Mint runs the SAME auth/module-gate/legal-basis preflight as verify, but NEVER meters, NEVER reserves spend, and makes ZERO provider calls.

Your own capture screens. If your application captures the document and selfie itself, mint with evidenceGroup: true. The response also carries an evidenceGroupId. Upload each capture into that group with POST /v1/kyc/evidence/handle (send evidenceGroupId instead of verificationId) and POST /v1/kyc/evidence/finalize, then verify with payload: {evidenceGroupId} and a fresh nonce. Noxtica resolves the uploaded evidence from the group — you never name evidence object ids — and the verificationId of the result equals the evidenceGroupId. A group accepts up to 16 evidence objects, closes after one hour, and serves exactly one verification (a retake needs a new group). A verify that names a group is refused before anything is admitted when the group is unknown (404 evidence_group_not_found, also for another organisation’s group), just expired (410 evidence_group_expired), incomplete (409 evidence_incomplete, with missingEvidence), or malformed (400); no nonce is spent and nothing is billed.

Authentication: Bearer token (ApiKeyAuth), scope write:identity.

Parameters

Request body

Content type application/json, required.

The body of POST /v1/kyc/verify — either branch selected by action (verify is the implicit default when action is omitted). Named as its own component (rather than an inline oneOf) so openapi/generate.sh’s csharp/generichost codegen produces a distinct composed wrapper type instead of colliding with either member schema’s own generated name.

Variant KycVerifyMintRequest

Variant KycVerifyVerifyRequest

Responses

Response headers

Response fields (200, application/json)

Variant KycVerifyMintResponse

Variant KycVerifyResponse

Response example (200)

{
  "ok": true,
  "nonce": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ttlSeconds": 300
}

Example request

curl

curl -X POST "https://collect.noxtica.com/v1/kyc/verify" \
  -H "Authorization: Bearer $NOXTICA_API_KEY" \
  -H "Idempotency-Key: example-Idempotency-Key" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "mint"
}'

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/kyc/verify', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
    'Idempotency-Key': 'example-Idempotency-Key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    action: 'mint',
  }),
});
console.log(response.status, await response.text());

Python (standard library)

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/kyc/verify",
    data=json.dumps({
        "action": "mint",
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
        "Idempotency-Key": "example-Idempotency-Key",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

Cross-match a self-uploaded proof-of-address document

POST /v1/kyc/verify/{verificationId}/address-document

Re-OCRs a proof-of-address document (already uploaded as KYC evidence) and the target verification’s already-captured ID-front document, then runs a deterministic name/address/freshness cross-match. This is the only cross-validation capability Noxtica offers today — it is a self-uploaded-document cross-match, never an authoritative registry lookup (USPS/Loqate/Experian), as the response’s own disclosure field states. There is no generic OCR↔MRZ↔barcode consistency check.

Authentication: Bearer token (ApiKeyAuth), scope write:identity.

Parameters

Request body

Content type application/json, required.

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "verdict": "pass",
  "disclosure": "example-disclosure",
  "requestId": "req-test"
}

Example request

curl

curl -X POST "https://collect.noxtica.com/v1/kyc/verify/00000000-0000-4000-8000-000000000000/address-document" \
  -H "Authorization: Bearer $NOXTICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "evidenceObjectId": "obj-front"
}'

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/kyc/verify/00000000-0000-4000-8000-000000000000/address-document', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    evidenceObjectId: 'obj-front',
  }),
});
console.log(response.status, await response.text());

Python (standard library)

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/kyc/verify/00000000-0000-4000-8000-000000000000/address-document",
    data=json.dumps({
        "evidenceObjectId": "obj-front",
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

Submit a batch verification manifest

POST /v1/kyc/verify/batch

Submits a CSV (text/csv) or JSON (application/json, {"items":[...]}) manifest of up to 500 rows. Each well-formed row is admitted asynchronously, off the response path, through the identical POST /v1/kyc/verify admission entry point — this endpoint does not verify anything itself, it only records per-item outcomes.

Authentication: Bearer token (ApiKeyAuth), scope write:identity.

Parameters

Request body

Content type application/json, required.

Content type text/csv, required.

Type: string.

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "batchId": "batch_5a1f9c3e7b2d4a6f8091c2d3e4f5a6b7",
  "status": "processing",
  "itemCount": 1,
  "items": [
    {
      "rowIndex": 0,
      "status": "pending",
      "errorCode": "missing_id_type"
    }
  ],
  "requestId": "req-test"
}

Response fields (202, application/json)

Response example (202)

{
  "ok": true,
  "batchId": "batch_5a1f9c3e7b2d4a6f8091c2d3e4f5a6b7",
  "status": "processing",
  "itemCount": 1,
  "items": [
    {
      "rowIndex": 0,
      "status": "pending",
      "errorCode": "missing_id_type"
    }
  ],
  "requestId": "req-test"
}

Example request

curl

curl -X POST "https://collect.noxtica.com/v1/kyc/verify/batch" \
  -H "Authorization: Bearer $NOXTICA_API_KEY" \
  -H "Idempotency-Key: example-Idempotency-Key" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "id_type": "passport",
      "purpose": "identity_verification",
      "payload": {}
    }
  ]
}'

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/kyc/verify/batch', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
    'Idempotency-Key': 'example-Idempotency-Key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [
      {
        id_type: 'passport',
        purpose: 'identity_verification',
        payload: {},
      },
    ],
  }),
});
console.log(response.status, await response.text());

Python (standard library)

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/kyc/verify/batch",
    data=json.dumps({
        "items": [
            {
                "id_type": "passport",
                "purpose": "identity_verification",
                "payload": {},
            },
        ],
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
        "Idempotency-Key": "example-Idempotency-Key",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

Read a batch job’s aggregate status

GET /v1/kyc/verify/batch/{batchId}/status

Authentication: Bearer token (ApiKeyAuth), scope write:identity.

Parameters

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "batchId": "batch_5a1f9c3e7b2d4a6f8091c2d3e4f5a6b7",
  "status": "processing",
  "itemCount": 1,
  "pendingCount": 0,
  "admittedCount": 1,
  "completedCount": 0,
  "rejectedCount": 0,
  "cancelledCount": 0,
  "requestId": "req-test"
}

Example request

curl

curl "https://collect.noxtica.com/v1/kyc/verify/batch/example-batchId/status" \
  -H "Authorization: Bearer $NOXTICA_API_KEY"

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/kyc/verify/batch/example-batchId/status', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
  },
});
console.log(response.status, await response.text());

Python (standard library)

import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/kyc/verify/batch/example-batchId/status",
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
    },
    method="GET",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

Read a batch job’s per-item outcomes

GET /v1/kyc/verify/batch/{batchId}/results

Authentication: Bearer token (ApiKeyAuth), scope write:identity.

Parameters

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "batchId": "batch_5a1f9c3e7b2d4a6f8091c2d3e4f5a6b7",
  "items": [
    {
      "rowIndex": 0,
      "status": "pending",
      "verificationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "verdict": "verified",
      "errorCode": "missing_id_type"
    }
  ],
  "requestId": "req-test"
}

Example request

curl

curl "https://collect.noxtica.com/v1/kyc/verify/batch/example-batchId/results" \
  -H "Authorization: Bearer $NOXTICA_API_KEY"

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/kyc/verify/batch/example-batchId/results', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
  },
});
console.log(response.status, await response.text());

Python (standard library)

import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/kyc/verify/batch/example-batchId/results",
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
    },
    method="GET",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

Cancel every still-pending item of a batch

POST /v1/kyc/verify/batch/{batchId}/cancel

A compare-and-swap UPDATE ... WHERE status = 'pending'. An item already admitted/evaluating/completed already holds (or held) a real verification claim and is never retroactively un-admitted.

Authentication: Bearer token (ApiKeyAuth), scope write:identity.

Parameters

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "batchId": "batch_5a1f9c3e7b2d4a6f8091c2d3e4f5a6b7",
  "cancelledCount": 0,
  "requestId": "req-test"
}

Example request

curl

curl -X POST "https://collect.noxtica.com/v1/kyc/verify/batch/example-batchId/cancel" \
  -H "Authorization: Bearer $NOXTICA_API_KEY"

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/kyc/verify/batch/example-batchId/cancel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
  },
});
console.log(response.status, await response.text());

Python (standard library)

import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/kyc/verify/batch/example-batchId/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
    },
    method="POST",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

Re-check an already-established identity’s device/verification level

POST /v1/kyc/reverify

A metered, read-shaped check against the authoritative device registry — it does not re-run document/biometric capture. Requires the device-registry module to be enabled for your organisation in addition to the KYC module; when it is not, the route answers the GatedNotFound 404.

Authentication: Bearer token (ApiKeyAuth), scope write:identity.

Request body

Content type application/json, required.

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "verified": true,
  "verificationLevel": "verified",
  "stepUp": "satisfied",
  "requestId": "req-test"
}

Example request

curl

curl -X POST "https://collect.noxtica.com/v1/kyc/reverify" \
  -H "Authorization: Bearer $NOXTICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "subjectId": "subj_4821",
  "requiredLevel": "verified",
  "stepUpReference": "example-stepUpReference"
}'

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/kyc/reverify', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    subjectId: 'subj_4821',
    requiredLevel: 'verified',
    stepUpReference: 'example-stepUpReference',
  }),
});
console.log(response.status, await response.text());

Python (standard library)

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/kyc/reverify",
    data=json.dumps({
        "subjectId": "subj_4821",
        "requiredLevel": "verified",
        "stepUpReference": "example-stepUpReference",
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

Mint a single-use ciphertext-upload handle

POST /v1/kyc/evidence/handle

Step 1 of 2 for raw evidence storage. Mints an opaque, short-lived (15-minute) upload handle plus a fresh per-object Data Encryption Key (DEK) wrapped under the tenant’s active Key Encryption Key (KEK). The caller encrypts the evidence bytes client-side with the returned dek and presents only ciphertext to POST /v1/kyc/evidence/finalize — Noxtica’s server never sees plaintext evidence at this step. No R2 storage URL, internal key, or sk_ value is ever returned (D27).

Authentication: Bearer token (ApiKeyAuth), scope write:identity.

Request body

Content type application/json, required.

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "handle": "example-handle",
  "dek": "example-dek",
  "wrappedDek": "example-wrappedDek",
  "envelope": {
    "envelope_version": 1,
    "cipher_suite": "example-cipher_suite",
    "kek_kid": "example-kek_kid"
  },
  "uploadTarget": {
    "objectId": "example-objectId",
    "schemaVersion": 1
  },
  "expiresAt": 1768435200,
  "requestId": "req-test"
}

Example request

curl

curl -X POST "https://collect.noxtica.com/v1/kyc/evidence/handle" \
  -H "Authorization: Bearer $NOXTICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "verificationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "jurisdiction": "TR",
  "evidenceKind": "id_document_front",
  "purpose": "identity_verification",
  "contentType": "image/jpeg",
  "contentLength": 1
}'

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/kyc/evidence/handle', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    verificationId: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    jurisdiction: 'TR',
    evidenceKind: 'id_document_front',
    purpose: 'identity_verification',
    contentType: 'image/jpeg',
    contentLength: 1,
  }),
});
console.log(response.status, await response.text());

Python (standard library)

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/kyc/evidence/handle",
    data=json.dumps({
        "verificationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "jurisdiction": "TR",
        "evidenceKind": "id_document_front",
        "purpose": "identity_verification",
        "contentType": "image/jpeg",
        "contentLength": 1,
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

Upload sealed ciphertext and finalize the evidence object

POST /v1/kyc/evidence/finalize

Step 2 of 2. Presents the handle from POST /v1/kyc/evidence/handle plus the chunked-AEAD-sealed ciphertext body. The server performs a controlled in-memory decrypt → structural inspection (never persisting plaintext) and promotes the object to usable or rejected. A repeated call with the same handle/body replays the stored terminal result byte-for-byte (idempotent by construction, not by an Idempotency-Key header).

Authentication: Bearer token (ApiKeyAuth), scope write:identity.

Request body

Content type application/json, required.

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "state": "usable",
  "reasonCode": "evidence_kind_forbidden",
  "objectId": "example-objectId",
  "requestId": "req-test"
}

Example request

curl

curl -X POST "https://collect.noxtica.com/v1/kyc/evidence/finalize" \
  -H "Authorization: Bearer $NOXTICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "handle": "example-handle",
  "objectId": "example-objectId",
  "commitment": {
    "total_chunks": 1,
    "total_plaintext_length": 0
  },
  "chunks": [
    "example-chunks"
  ]
}'

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/kyc/evidence/finalize', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    handle: 'example-handle',
    objectId: 'example-objectId',
    commitment: {
      total_chunks: 1,
      total_plaintext_length: 0,
    },
    chunks: [
      'example-chunks',
    ],
  }),
});
console.log(response.status, await response.text());

Python (standard library)

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/kyc/evidence/finalize",
    data=json.dumps({
        "handle": "example-handle",
        "objectId": "example-objectId",
        "commitment": {
            "total_chunks": 1,
            "total_plaintext_length": 0,
        },
        "chunks": [
            "example-chunks",
        ],
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

List the evidence images of a verification

GET /v1/kyc/verifications/{verificationId}/evidence

Server-to-server. Lists the images a person captured during one of your own verifications, so that your own operators can look at them: the front and back of an identity document, a passport page, a proof of address, a selfie, a capture of the document held next to the face, and supporting documents. Only still images whose storage finished successfully are listed. Videos, voice recordings, the identity details Noxtica extracted (read those with GET /v1/kyc/verifications/{verificationId}/identity) and anything Noxtica derived from the images are never listed and cannot be opened through these routes. The response holds no image bytes: ask for one with POST /v1/kyc/verifications/{verificationId}/evidence/{itemId}/access, then fetch the signed URL it returns.

Opt-in. The key needs the read:evidence scope, and every evidence image route answers 403 evidence_read_not_enabled until a tenant administrator enables evidence image access for your organisation in the Backoffice (KYC → Invitations → Settings tab, card “Evidence image API”): the administrator records the legal basis for receiving these images, Article 6 and Article 9 of the GDPR, with step-up multi-factor authentication. Identity document images and selfies are special-category personal data: enable the access only for the operators who need it. Evidence storage must also be armed for your organisation (card “Evidence storage” on the same tab), otherwise the answer is 403 evidence_storage_not_armed. While Noxtica has the evidence image API off for the platform, every route answers the byte-identical 404 of an unknown path. A key keeps its scopes until a tenant administrator changes them (Edit scopes on the key in the Backoffice, API Configuration): add read:evidence to the key, or create a new key that carries it. When a tenant administrator withdraws the enablement, the very next request is refused, a signed URL that has not expired yet included.

Which id. verificationId is the id returned by POST /v1/kyc/verify (a UUID) or the verificationId of a hosted session (hosted: followed by 64 lower-case hexadecimal characters); see KycVerificationId for the formats and the 128-character maximum. The id of a hosted session and the evidenceGroupId of a verification made from your own capture screens are accepted too and resolve to the same verification. An id that is malformed, unknown, or belongs to another organisation gets the same byte-identical 404 as an unknown path.

What is listed. Newest first, at most 100 items, only images that are ready to be opened. type and side tell the images apart:

contentType is image/jpeg, image/png or image/webp, size is the size in bytes and capturedAt is when Noxtica received the image. An item has no hash, purpose or storage detail.

Audit and handling. Listing does not release an image and is not itself recorded in the access log; asking for access and fetching an image are (see kycVerificationEvidenceAccess and kycEvidenceContent). Every response of this route carries Cache-Control: no-store, private. Images are never sent in webhooks.

Rate limit. A per-key limit applies to this route, the access route and the access log together; a limited request answers 429 with Retry-After. Fetching a signed URL has a separate per-key limit.

Authentication: Bearer token (ApiKeyAuth), scope read:evidence.

Parameters

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "verificationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "items": [
    {
      "itemId": "evd_example_0003",
      "type": "selfie",
      "side": null,
      "contentType": "image/png",
      "size": 95311,
      "capturedAt": "2026-11-05T10:12:40.000Z"
    },
    {
      "itemId": "evd_example_0002",
      "type": "document",
      "side": "back",
      "contentType": "image/jpeg",
      "size": 171903,
      "capturedAt": "2026-11-05T10:11:58.000Z"
    },
    {
      "itemId": "evd_example_0001",
      "type": "document",
      "side": "front",
      "contentType": "image/jpeg",
      "size": 183422,
      "capturedAt": "2026-11-05T10:11:12.000Z"
    }
  ],
  "requestId": "req-test"
}

Example request

curl

curl "https://collect.noxtica.com/v1/kyc/verifications/example-verificationId/evidence" \
  -H "Authorization: Bearer $NOXTICA_API_KEY"

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/kyc/verifications/example-verificationId/evidence', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
  },
});
console.log(response.status, await response.text());

Python (standard library)

import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/kyc/verifications/example-verificationId/evidence",
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
    },
    method="GET",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

Get a short-lived signed URL for one evidence image

POST /v1/kyc/verifications/{verificationId}/evidence/{itemId}/access

Server-to-server. Returns a signed URL for one image listed by GET /v1/kyc/verifications/{verificationId}/evidence. Hand the URL to the operator’s browser, or fetch it from your backend and pass the bytes on. The URL is the credential: GET /v1/kyc/evidence/content needs no Authorization header. The key needs the read:evidence scope, and the opt-in described on kycVerificationEvidenceList applies.

The URL. It is valid for 120 seconds from the grant (see expiresAt). The lifetime is fixed: it cannot be extended or requested longer. Within that time the URL can be fetched more than once, for example when a browser reloads the image; every fetch is recorded and rate limited. Anyone who holds the URL can fetch the image until it expires, so treat it as a secret: give it only to the operator who asked to open the image, never log or store it, and never put it on a page that loads content from other sites. Ask for a new URL instead of keeping one. The URL has the host you called, and its query holds an opaque token: do not parse, shorten or rebuild it.

What stops a URL early. A URL stops working at once when the key that asked for it is revoked or loses the read:evidence scope, when a tenant administrator withdraws the enablement, and when the image no longer exists.

Which ids. verificationId is accepted in the same forms as on kycVerificationEvidenceList. itemId is the itemId of an item of that list. A malformed or unknown id, an item that belongs to another verification or another organisation, and an item that is not a readable image (a video, a voice recording, extracted data) all get the same byte-identical 404 as an unknown path.

Availability. An item of this verification that is an image but whose storage did not finish successfully answers 409 evidence_not_available with reason not_usable. A verification you deleted answers 410 verification_deleted.

Audit and handling. Each grant is recorded for your organisation before the URL is released: the key, the verification, the type of image, the time and, as Noxtica saw them, the caller address and user agent; never the image. If the record cannot be written, nothing is released and the answer is 503 evidence_audit_unavailable. Read the record with GET /v1/kyc/verifications/{verificationId}/evidence/access-log. Every response of this route carries Cache-Control: no-store, private: do not cache or log the body.

Request body. None is needed. An empty JSON object is accepted and ignored.

Rate limit. The same per-key limit as kycVerificationEvidenceList.

Authentication: Bearer token (ApiKeyAuth), scope read:evidence.

Parameters

Request body

Content type application/json, optional.

Type: object.

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "verificationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "itemId": "evd_example_0001",
  "url": "https://collect.noxtica.com/v1/kyc/evidence/content?token=v1.EXAMPLE_PAYLOAD.EXAMPLE_SIGNATURE",
  "expiresAt": "2026-11-05T10:13:12.000Z",
  "expiresInSeconds": 120,
  "contentType": "image/jpeg",
  "size": 183422,
  "requestId": "req-test"
}

Example request

curl

curl -X POST "https://collect.noxtica.com/v1/kyc/verifications/example-verificationId/evidence/example-itemId/access" \
  -H "Authorization: Bearer $NOXTICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/kyc/verifications/example-verificationId/evidence/example-itemId/access', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
console.log(response.status, await response.text());

Python (standard library)

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/kyc/verifications/example-verificationId/evidence/example-itemId/access",
    data=json.dumps({}).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

Fetch an evidence image with a signed URL

GET /v1/kyc/evidence/content

Returns the bytes of one image. The signed URL that kycVerificationEvidenceAccess returned is the credential: send no Authorization header, and use the URL exactly as it was given.

The response. 200 carries the image itself. Content-Type is the type of the stored image (image/jpeg, image/png or image/webp), Content-Disposition is inline; filename="evidence-<itemId>.<jpg|png|webp>" and Content-Length is the exact size. Every response of this route, errors included, carries Cache-Control: no-store, private, X-Content-Type-Options: nosniff and Referrer-Policy: no-referrer: do not cache or store the response.

Checks on every fetch. A URL that was altered, is malformed or has expired answers 401 invalid_or_expired_url; the body is the same for every one of those causes. The same 401 follows when the key that asked for the URL has been revoked or no longer carries the read:evidence scope. The tenant administrator’s enablement and evidence storage must still be in place, otherwise the answer is 403 evidence_read_not_enabled or 403 evidence_storage_not_armed. An image that no longer exists, or that is not a readable image of the verification the URL was granted for, answers the byte-identical 404.

Audit. Each fetch is recorded for your organisation before any byte is released, with the key, the verification, the type of image, the time and, as Noxtica saw them, the caller address and user agent. If the record cannot be written, nothing is released and the answer is 503 evidence_audit_unavailable. A request that is refused before that point is not recorded. The record is readable with GET /v1/kyc/verifications/{verificationId}/evidence/access-log.

Stored image check. Noxtica checks that the bytes are an image of the type they were stored as before serving them. If they are not, nothing is served and the answer is 502 evidence_unreadable.

Rate limit. A per-key limit applies to fetches, separate from the one on the other evidence image routes; a limited request answers 429 with Retry-After.

Authentication: none. This operation does not take a credential.

Parameters

Responses

Response headers

Example request

curl

curl "https://collect.noxtica.com/v1/kyc/evidence/content?token=v1.EXAMPLE_PAYLOAD.EXAMPLE_SIGNATURE"

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/kyc/evidence/content?token=v1.EXAMPLE_PAYLOAD.EXAMPLE_SIGNATURE', {
  method: 'GET',
});
console.log(response.status, await response.text());

Python (standard library)

import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/kyc/evidence/content?token=v1.EXAMPLE_PAYLOAD.EXAMPLE_SIGNATURE",
    method="GET",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

List who opened the evidence images of a verification

GET /v1/kyc/verifications/{verificationId}/evidence/access-log

Server-to-server. Lists the openings of the images of one of your own verifications, newest first: one row for each access grant and one for each fetch of a signed URL. Use it to answer who looked at an image, from where and when. A row never holds image bytes, a signed URL or its token. The key needs the read:evidence scope.

After the enablement is withdrawn. Unlike the other evidence image routes, this one does not need the tenant administrator’s enablement to be in place, nor evidence storage to be on, so you can still read the history after the enablement was withdrawn. It is not available while evidence image access is not available for your organisation (404).

Which id. verificationId is accepted in the same forms as on kycVerificationEvidenceList; a malformed, unknown or foreign id gets the same byte-identical 404. A verification you deleted answers 410 verification_deleted.

Rows. event is grant (a signed URL was issued) or fetch (the image was served). itemId is the image, apiKeyId the key that asked for the URL, and at the time. ip and userAgent are what Noxtica saw on the request (the address the request came from and its User-Agent header, shortened to 256 characters) and are null when there was none.

Paging. limit is 1 to 100 (default 50). When more rows exist, nextBefore is a cursor in Unix milliseconds: pass it unchanged as before to read the next page. It is null on the last page. A limit or before that is repeated, not a whole number or out of range answers 400 invalid_request.

Handling. Every response of this route carries Cache-Control: no-store, private.

Rate limit. The same per-key limit as kycVerificationEvidenceList.

Authentication: Bearer token (ApiKeyAuth), scope read:evidence.

Parameters

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "verificationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "events": [
    {
      "id": "req-example-0002",
      "at": "2026-11-05T10:11:40.000Z",
      "event": "fetch",
      "itemId": "evd_example_0001",
      "apiKeyId": "key_example_01",
      "ip": "203.0.113.7",
      "userAgent": "ExampleBackend/1.0"
    },
    {
      "id": "req-example-0001",
      "at": "2026-11-05T10:11:12.000Z",
      "event": "grant",
      "itemId": "evd_example_0001",
      "apiKeyId": "key_example_01",
      "ip": "203.0.113.7",
      "userAgent": "ExampleBackend/1.0"
    }
  ],
  "nextBefore": null,
  "requestId": "req-test"
}

Example request

curl

curl "https://collect.noxtica.com/v1/kyc/verifications/example-verificationId/evidence/access-log" \
  -H "Authorization: Bearer $NOXTICA_API_KEY"

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/kyc/verifications/example-verificationId/evidence/access-log', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
  },
});
console.log(response.status, await response.text());

Python (standard library)

import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/kyc/verifications/example-verificationId/evidence/access-log",
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
    },
    method="GET",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

Mint a Noxtica-hosted KYC verification-session link

POST /v1/kyc/sessions

Server-to-server. Creates a hosted verification session and returns a one-shot, opaque URL to hand to your end customer (redirect, email, SMS or QR). The URL embeds a bearer session token that is never returned again by any route: treat it as a secret, do not log it and do not put it in an analytics URL. Minting is free; the verification is counted when the customer submits.

Before you can mint. (1) The identity verification module must be enabled for your organisation; until it is, this route answers the same byte-identical 404 as an unknown path. (2) Your sk_ key needs the write:identity scope (a key created with the default scope is refused with 403). (3) A tenant administrator must have recorded an active legal-basis receipt for hosted document capture in the Backoffice; without it the mint is refused with 403 kyc_legal_basis_receipt_required. Noxtica never selects a legal basis for you. (4) Your organisation needs a hosted configuration (business name, privacy URL, supported documents) in the Backoffice, or the customer sees “Verification isn’t ready yet”; the mint itself does not check this. (5) Your organisation’s raw-evidence storage must be provisioned in the Backoffice: evidence storage armed and an evidence residency of TR, EU or US set. A link for an organisation that cannot store the customer’s capture would fail after the first photo, so the mint is refused before any session exists with 403 evidence_not_provisioned and a reason (raw_storage_not_armed or residency_unconfigured). Retrying does not help until the organisation is provisioned.

Request. subjectRef is required. The expiry field is expiresInSeconds: a key named ttlSeconds is not read and is silently ignored (the link then lasts the 24 hour default). Unknown keys are ignored. The snake_case spellings subject_ref, return_url, id_type, expires_in_seconds and hosted_options are also accepted; the camelCase names are the contract. Locale, customer name, email and phone are not request fields: the page language follows the customer’s browser and cannot be forced, and the webhook endpoint is registered once for your organisation in the Backoffice, not per session.

Lifetime and expiry. expiresAt is Unix time in milliseconds in every response. At mint it is now + expiresInSeconds: 24 hours (86400 s) by default, or the 5 minutes (300 s) to 7 days (604800 s) you ask for; a value outside that range is refused with 400 invalid_request and is never clamped. An unopened link keeps that whole validity. The first customer action the platform records on the hosted page (for example accepting the privacy notice) opens the session: openedAt is stamped and expiresAt becomes min(expiresAt, openedAt + 30 minutes), so the customer must finish capture inside that window. The deadline only ever moves earlier: a link minted for 10 minutes still ends 10 minutes after mint, and a link minted for 24 hours ends 30 minutes after the customer first acts. It is never extended and there is no renewal call: when a customer needs more time, mint a new session. Each timed capture step (document front or back, selfie, document near face, liveness, voice) also has its own 10 minute limit; a step that runs out restarts and the session carries on until its own deadline. When the deadline passes the session is expired: the platform records it on the next read or on its expiry sweep (every 5 minutes), the hosted page answers 410 session_expired, GET /v1/kyc/sessions/{sessionId} keeps answering 200 with status: "expired", a session that was never submitted is never billed, and kyc.session.completed is never sent. A session in review_pending never expires: it waits for a Backoffice reviewer.

Using the link. The hosted page cannot be embedded in an iframe (X-Frame-Options: DENY); open it in a new tab, or redirect the customer to it. The page never posts a message to the opener or parent window and never redirects on its own. If you minted with a returnUrl, the page shows a plain “Return to <business>” link to exactly that URL (nothing is appended) on the completion and status screens only for a completed outcome, and on the screen shown when a step cannot continue. Sessions created from Backoffice invitations carry no returnUrl. Correlate by the sessionId you stored at mint, and never treat a visit to your return page as proof of completion.

Outcome. Learn the outcome with the kyc.session.completed webhook or by polling GET /v1/kyc/sessions/{sessionId}. With the identity provider configured today every successful capture ends in review_pending, not completed: the webhook fires only after a Backoffice reviewer approves or overrides the case (usually within seconds, at most about 5 minutes after the decision), and a review_pending session never expires. Read verification and review on the status read to tell an approval from an override. See that route for the status table.

Email verification (optional step). hostedOptions.steps.emailVerification (off, optional or required) adds an email-verification step to the hosted flow: the customer types an address, receives one confirmation link, and only a click on that link marks the address verified. Omit the key to use your organisation’s default (Hosted configuration); an explicit value for this link wins in both directions. The effective mode is resolved once, here, and is fixed for the session. This is available only once the platform has enabled hosted email verification: until then an explicit optional or required is refused with 400 email_verification_unavailable (an explicit off is always accepted, and your organisation default is ignored), so a required session can never silently run unverified.

Domains (optional). One organisation can own several domains, and each domain can carry its own hosted configuration (business name, purpose, privacy and support pages, supported documents, approved return hosts, embed origins, email verification) that overrides your organisation default field by field; see GET /v1/kyc/config. The invitation is created for one domain, chosen in this order: domainId in the body, then siteKey in the body, then the request’s Origin header when it exactly equals the origin of one of your active domains (any other origin is ignored). With none of these the invitation uses your organisation default. A domainId and a siteKey that name different domains are refused with 400 domain_mismatch; an unknown or disabled domain, or one that belongs to another organisation, is refused with 404 domain_not_found (the same answer in all three cases, so the route cannot be used to discover other organisations’ domains). The domain is fixed at mint: the returnUrl check and the email-verification mode use that domain’s configuration, and the hosted page always shows the configuration the domain has at that moment (if you remove a domain’s override later, its sessions fall back to your organisation default). The mint response and the status read carry the session’s domainId, null for the organisation default. Until a domain has its own configuration, every invitation behaves as before.

Countries (optional). hostedOptions.allowedIssuingCountries narrows one invitation to some issuing countries, for example the countries you expect this customer to come from, without changing your hosted configuration. Send any ISO 3166-1 alpha-2 codes (CountryCodeList: 1 to 249 distinct codes; all 249 is the same as sending none). Each document type your configuration accepts keeps only the issuing countries that are also in the list, and a document type left with no country is dropped from the invitation. When no document type is left the mint is refused with 400 invalid_hosted_options (field allowedIssuingCountries, reason no_matching_document_country) and no session is created. Omit the key to keep every configured country. A list outside your configuration is not an error as long as one document type remains. hostedOptions must be the complete object when you send it, so send this key together with the other required keys. The list is fixed at mint: the hosted page shows your configuration at that moment narrowed by it, and the customer cannot choose a country outside it.

Idempotency. Idempotency-Key is optional (8 to 128 characters). Without it every call mints a fresh session. With it, a retry under the same key returns the SAME session with replayed: true and WITHOUT the url: the one-shot URL of a lost response cannot be recovered, so mint a new session under a new key instead. The replay matches on the key only; a different body under the same key still returns the original session.

Rate limits. A per-source-IP limit applies first, before authentication, then a per-key limit shared with the status read. See “Rate limits” above.

Authentication: Bearer token (ApiKeyAuth), scope write:identity.

Parameters

Request body

Content type application/json, required.

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "sessionId": "6d3c3a8e-6b4b-4a8f-8f4e-0a0e6b3d9d21",
  "url": "https://verify.noxtica.com/s/kycs.tenant_42.q3JkT0vN8mYb1xW6cE4aZ7uP2sH9dLfR5gKiA0oXyUw",
  "expiresAt": 1790765600000,
  "domainId": null,
  "requestId": "req-test"
}

Example request

curl

curl -X POST "https://collect.noxtica.com/v1/kyc/sessions" \
  -H "Authorization: Bearer $NOXTICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "subjectRef": "cust_4821",
  "returnUrl": "https://merchant.example.com/kyc/return",
  "purpose": "Open your brokerage account",
  "idType": "passport",
  "expiresInSeconds": 3600,
  "hostedOptions": {
    "allowedDocumentTypes": [
      "passport",
      "national_id"
    ],
    "allowedIssuingCountries": [
      "TR",
      "GB",
      "DE"
    ],
    "allowDeviceUpload": false,
    "steps": {
      "documentBack": "auto",
      "documentNearFace": false,
      "activeLiveness": true,
      "speechAnalysis": false,
      "ageGenderEstimation": false
    }
  }
}'

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/kyc/sessions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    subjectRef: 'cust_4821',
    returnUrl: 'https://merchant.example.com/kyc/return',
    purpose: 'Open your brokerage account',
    idType: 'passport',
    expiresInSeconds: 3600,
    hostedOptions: {
      allowedDocumentTypes: [
        'passport',
        'national_id',
      ],
      allowedIssuingCountries: [
        'TR',
        'GB',
        'DE',
      ],
      allowDeviceUpload: false,
      steps: {
        documentBack: 'auto',
        documentNearFace: false,
        activeLiveness: true,
        speechAnalysis: false,
        ageGenderEstimation: false,
      },
    },
  }),
});
console.log(response.status, await response.text());

Python (standard library)

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/kyc/sessions",
    data=json.dumps({
        "subjectRef": "cust_4821",
        "returnUrl": "https://merchant.example.com/kyc/return",
        "purpose": "Open your brokerage account",
        "idType": "passport",
        "expiresInSeconds": 3600,
        "hostedOptions": {
            "allowedDocumentTypes": [
                "passport",
                "national_id",
            ],
            "allowedIssuingCountries": [
                "TR",
                "GB",
                "DE",
            ],
            "allowDeviceUpload": False,
            "steps": {
                "documentBack": "auto",
                "documentNearFace": False,
                "activeLiveness": True,
                "speechAnalysis": False,
                "ageGenderEstimation": False,
            },
        },
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

Read a hosted session’s current status (tenant backend read)

GET /v1/kyc/sessions/{sessionId}

Server-to-server. The authoritative tenant-side read of a hosted session; use it to confirm any webhook before you act on it, and to poll when you have no webhook endpoint. Everything is nested under session, and every timestamp is Unix time in milliseconds. A session that is past its deadline reads 200 with status: "expired" (never 410; the 410 answers belong to the customer’s browser routes). A session id that does not exist, or belongs to another organisation, gets the same byte-identical 404 as an unknown path.

Status lifecycle.

review_pending to completed. kyc.session.completed does not fire when a session lands in review_pending. It fires when a Backoffice reviewer approves or overrides the case, usually within seconds and at most about 5 minutes after the decision. Until then the only way to observe review_pending is this read. An override also moves the session to completed, so completed is not an approval. decision.outcome is derived from status alone (completed reads approved), so it reads approved after an override too: do not use it to tell the two apart. Use verification and review.

Verification outcome and review. Once the session has a verificationId (the customer submitted), session carries two more blocks that state what the verification finally is; before that neither key is present.

• verification.status is the outcome: verified, unverified, failed, error or pending (the verification has no verdict yet). verification.source says who produced it: pipeline is the automated verdict exactly as recorded, review means a reviewer’s approve decision was applied over it. Only approve ever turns the reported status into verified; an override is reported in review but never upgrades the status.
• review is null while no reviewer has acted, otherwise {state, decision, version, decidedAt}. state is in_review (escalated, no decision yet), approved or overridden; the vocabulary also holds open and closed, which no review action writes today. decision is approve, override, or null while the state is in_review. version is the number of review writes, starting at 1 and increasing by one with every write. decidedAt is Unix ms of the last decision, or null while there is none. No reviewer identity and no reviewer note is ever returned.

reasonCodes keeps the automated reasons after a review: provider_manual_review stays in the list once a reviewer has approved the case, so it does not mean the case is still waiting. Read status, verification and review instead.

There is no reject decision in the review vocabulary today, and a rejected end state cannot be expressed. kyc.verification.completed is sent once, when the automated verification ends (for a hosted session, unverified with provider_manual_review); it is never sent again after a review, so do not wait for it: read review.

Review decision and status events. A reviewer’s approve or override is announced by the kyc.review.decided event, for hosted sessions and for verifications you created through the API; for a hosted session that was review_pending, kyc.session.completed follows. An escalation (in_review) sends nothing. Each status a session enters is also announced by its own opt-in event: kyc.session.created (pending), kyc.session.opened, kyc.session.verifying, kyc.session.review_pending, kyc.session.unverified, kyc.session.error and kyc.session.expired; see the webhooks section.

Cancellation. status: cancelled_by_user is reported here, but cancelledAt and cancelReason are NOT part of this response; they are delivered in the kyc.session.cancelled webhook. An expiry never sends kyc.session.completed or kyc.session.cancelled. A cancelled or expired session is never billed as a verification (the kyc.verification meter is recorded only at submit-time admission); only the request-level endpoint.collect.request counts.

Email verification result. Only when hosted email verification is enabled for the platform AND the session’s effective mode is not off or an address is stored, the session object also carries email (the normalised address the customer entered, or null), emailVerified (true only after the customer clicked the confirmation link for that exact address), emailVerifiedAt (Unix ms, or null) and emailVerification (the effective mode: off, optional or required). Treat email with emailVerified: false as an unverified, customer-typed value. Otherwise these four keys are absent.

Noxtica Verification ID. Only when the Noxtica Verification ID (NVID) is enabled for the platform, the session object also carries nvid: the session’s NVID (NVID-XXXX-XXXX-XXXX-XXXX) or null (none was issued: an NVID is issued when the submit ends completed or review_pending). The key is absent while the feature is not enabled. The public status page of an NVID is https://verify.<environment host>/v/<NVID>; the public lookup route behind it can only be called from the hosted site’s browser origin, never from a tenant backend.

Check results. The per-check results below are evidence for a reviewer and for your own risk rules. Every number is a value the service uses today and may be retuned without a version bump unless a row says otherwise; model, engine and vendor names are deliberately not published.

• Nothing here rejects a person by itself. Every hosted verification currently ends verification.status: unverified with reasonCodes: [provider_manual_review]; a reviewer’s approval completes it (verification.source: review). A check result never changes verification.status on its own.
• fail means a confident failure; review means no confident answer, a person should look. An advisory or unqualified signal can only read review. A fail on a person who is clearly genuine is a false reject: report it with the sessionId.
• While presentation-attack detection (PAD) is advisory, liveness and selfie never read pass. Their best outcome is review, so scorecard.overall is at best review for every session today. This is expected and is not a problem with the person’s capture.

What these readings mean for your integration, what to automate and what not to, and every PAD and liveness reason code are on the page Liveness & PAD policy.

Thresholds are platform-wide. Every threshold named below (the selfie quality limits, the face-match bands, the liveness and blink limits, the document-authenticity bands and the PAD operating points) is one value for all customers. No request carries a tenant, profile or threshold parameter, and neither your organisation default, a domain override nor an invitation changes a threshold: there is no tenant-level or domain-level threshold setting today. What you can configure, per organisation, per domain (a domain overrides your organisation default field by field) and per invitation, is which steps and documents run and which identity fields must be read: in the hosted verification configuration (GET /v1/kyc/config) documents[] (idType, issuingCountries, requiredIdentityFields), requireSelfie, requireVoice, allowDeviceUpload and emailVerification; on an invitation (POST /v1/kyc/sessions) hostedOptions (allowedDocumentTypes, allowedIssuingCountries and steps, for example steps.activeLiveness). None of these changes how a check is judged. The verdict of a hosted verification (unverified with provider_manual_review until a reviewer approves) is not configurable either.

Where the results appear: session.scorecard.<step> for document_front, document_back, selfie, liveness, voice, cross_validation and overall ({status, score 0..1, checks[{name, pass, score}], reasonCodes[]}), and session.stages.<stage> ({status, score, reasonCodes[]}). The identity read (GET /v1/kyc/verifications/{verificationId}/identity, scope read:identity_details) returns the verdicts only, as checks.documentAuthenticity, checks.faceMatch, checks.liveness and checks.selfie, without scores.

Reading a scorecard reason code.

Document authenticity (checks.documentAuthenticity, step document_front). Advisory: the analysis is an unqualified classical image analysis whose own decision is always manual review. A failed check reads review at most; only an overall pass reads pass. It is never used to reject.

The analysis is fail when a hard-gate check fails or the weighted score is below the fail band; pass only when every check passes, the score is in the pass band and card_geometry was actually measured; everything else is inconclusive. The numeric bands and the forensic thresholds of copy_move, ela, moire_recapture, print_consistency and hologram_presence are not published. The advisory portrait-substitution observation (doc_auth_portrait_substitution) is computed after the verdict and is not part of the score: it appears in checks[] when it did not pass, adds no _failed code and never lowers a pass. card_geometry_failed on a real card almost always means the document was not found or was held at a strong angle: ask for a flat, well-lit capture with the whole card in view. A document other than the supported card layout (for example a driving licence) is measured against the card profile, so its layout and hologram results are weaker evidence. session.scorecard.document_front is wider than checks.documentAuthenticity: it also folds in the document recognition and text reading rows of the front. The text reading row is always inconclusive today (document_text_reading_inconclusive), so document_front reads review at best, even when checks.documentAuthenticity reads pass. Treat review as “a person should look”.

Liveness (checks.liveness, step liveness, stage active_liveness). Advisory evidence plus a capture gate in the page: the hosted page does not accept a gesture until the person has moved by the capture thresholds below. The server then re-checks the captured frames independently, and the browser’s own measurements can only make a result worse, never rescue a failed server check. Five gestures are captured in the order turn_up, turn_down, turn_left, turn_right, blink. Checks in the scorecard: active_liveness (the overall result), turn_left, turn_right, turn_up, turn_down, blink and pad.

Publishable capture thresholds (browser, per gesture, relative to the start pose): turn left or right at least 6 degrees; look up or down at least 4.5 degrees; at most 42 degrees sideways or 38 degrees up and down is accepted; blink between 50 and 1500 ms. The server-side gate, its noise margins and the PAD operating points are not published.

turn_*_failed on a genuine person usually means the head barely moved, a very small face or poor light: ask the person to turn clearly past the on-screen mark. blink_inconclusive is common and means “not measured”, not “no blink”; together with blink_closed_plateau, blink_scene_changed or blink_cycle_partial it means a blink-like movement was seen but not confirmed, so a person should look at it. A server result stored for the session counts as proof that the challenge was captured: the liveness step is not pending once that result exists, even when the browser never reported a completed gesture.

Selfie quality (checks.selfie, step selfie, stage selfie_quality). The hard checks are flow-affecting (the hosted page asks for a retake); the soft checks are advisory. Every check after face_count needs exactly one detected face. A failed check is reported as <check>_failed, with the check name from the first column, in scorecard.selfie.reasonCodes and session.stages.selfie_quality.reasonCodes; the overall result of the quality analysis adds face_quality_fail or face_quality_inconclusive. The quality analysis also has internal issue names (for example eyes_not_open, image_too_blurry, exposure_out_of_range); they are not reason codes of the scorecard and are not returned in these lists.