Identity verification API

Verify identities, run hosted verification sessions, batch and re-verify, store evidence, 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.

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 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 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 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 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())

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.

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. An unopened link keeps expiresInSeconds (default 24 hours). Once the customer first opens it the deadline tightens to min(expiresAt, openedAt + 30 minutes); the customer must finish capture inside that window. expiresAt in every response is Unix time in milliseconds.

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 the case (allow up to about 5 minutes after the decision), and a review_pending session never expires. 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.

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,
  "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"
    ],
    "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',
      ],
      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",
            ],
            "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; allow up to about 5 minutes between the decision and the delivery. Until then the only way to observe review_pending is this read. A rejected end state is not currently expressible by the review vocabulary.

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 emits no webhook at all. 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.

Rate limit. Shares the per-key limit (30 requests per 60 seconds) with the mint call, after the per-source-IP limit that applies to every request.

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

Parameters

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "session": {
    "id": "6d3c3a8e-6b4b-4a8f-8f4e-0a0e6b3d9d21",
    "status": "review_pending",
    "idType": "passport",
    "subjectId": "cust_4821",
    "captureStep": "submit",
    "createdAt": 1790762000000,
    "openedAt": 1790762100000,
    "expiresAt": 1790763900000,
    "completedAt": 1790762445000,
    "verificationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "reasonCodes": [
      "provider_manual_review"
    ],
    "purpose": "Open your brokerage account",
    "returnUrl": "https://merchant.example.com/kyc/return",
    "selectedIdType": "passport",
    "selectedIssuingCountry": "GB",
    "consentVersion": "2026-09-01",
    "consentAcceptedAt": 1790762110000,
    "speechProfilingConsentAcceptedAt": null,
    "ageGenderConsentAcceptedAt": null,
    "evidence": {
      "front": "obj_9c1e4a",
      "selfie": "obj_5b7d02"
    },
    "decision": {
      "outcome": "review_pending",
      "reasonCodes": [
        "provider_manual_review"
      ],
      "decidedAt": 1790762445000
    },
    "stages": {
      "scene_inventory": {
        "status": "pass",
        "score": 0.97,
        "reasonCodes": []
      },
      "document_type_id": {
        "status": "pass",
        "score": 0.94,
        "reasonCodes": []
      },
      "ocr_back": {
        "status": "skipped",
        "score": null,
        "reasonCodes": [
          "not_required"
        ]
      },
      "mrz_crosscheck": {
        "status": "pass",
        "score": 0.99,
        "reasonCodes": []
      },
      "selfie_quality": {
        "status": "pass",
        "score": 0.91,
        "reasonCodes": []
      },
      "document_near_face": {
        "status": "skipped",
        "score": null,
        "reasonCodes": [
          "not_required"
        ]
      },
      "active_liveness": {
        "status": "pass",
        "score": 0.93,
        "reasonCodes": []
      },
      "speech_profile": {
        "status": "skipped",
        "score": null,
        "reasonCodes": [
          "speech_profiling_not_requested"
        ]
      },
      "speech_analysis": {
        "status": "skipped",
        "score": null,
        "reasonCodes": [
          "speech_analysis_not_requested"
        ]
      },
      "age_gender": {
        "status": "skipped",
        "score": null,
        "reasonCodes": [
          "age_gender_not_requested"
        ]
      }
    },
    "scorecard": {
      "document_front": {
        "status": "pass",
        "score": 0.94,
        "checks": [],
        "reasonCodes": []
      },
      "document_back": {
        "status": "skipped",
        "score": 0,
        "checks": [],
        "reasonCodes": [
          "not_required"
        ]
      },
      "selfie": {
        "status": "pass",
        "score": 0.91,
        "checks": [],
        "reasonCodes": []
      },
      "liveness": {
        "status": "pass",
        "score": 0.93,
        "checks": [],
        "reasonCodes": []
      },
      "voice": {
        "status": "skipped",
        "score": 0,
        "checks": [],
        "reasonCodes": [
          "not_required"
        ]
      },
      "cross_validation": {
        "status": "pass",
        "score": 0.99,
        "checks": [],
        "reasonCodes": []
      },
      "overall": {
        "status": "pass",
        "score": 0.94,
        "checks": [],
        "reasonCodes": []
      }
    },
    "nvid": "NVID-7K3M-Q9XA-T2RW-4HZD"
  },
  "requestId": "req-test"
}

Example request

curl

curl "https://collect.noxtica.com/v1/kyc/sessions/example-sessionId" \
  -H "Authorization: Bearer $NOXTICA_API_KEY"

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

const response = await fetch('https://collect.noxtica.com/v1/kyc/sessions/example-sessionId', {
  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/sessions/example-sessionId",
    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 the current hosted session (browser-facing)

GET /v1/kyc/session-view

Called by the hosted verification page itself, never by a tenant backend. Noxtica Verification ID. Only when the Noxtica Verification ID (NVID) is enabled for the platform, the session object carries verificationIdentifier (KycVerificationIdentifier) — the NVID with its derived status and an emailOnFile flag — or null when the session has no NVID. It lets the page show the ID again when a finished link is reloaded. The key is absent while the feature is not enabled; the email address is never returned.

Authentication: Bearer token (SessionTokenAuth).

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "session": {
    "status": "opened",
    "idType": "passport",
    "captureStep": "consent",
    "expiresAt": 1790763900000,
    "openedAt": 1790762100000,
    "steps": [
      "consent",
      "id_front",
      "id_back",
      "selfie",
      "document_near_face",
      "liveness",
      "voice",
      "review",
      "submit"
    ],
    "configuration": {
      "businessName": "Example Bank",
      "purpose": "Open your brokerage account",
      "privacyUrl": "https://merchant.example.com/privacy",
      "supportUrl": "https://merchant.example.com/support",
      "returnUrl": "https://merchant.example.com/kyc/return",
      "privacyVersion": "2026-09-01",
      "documents": [
        {
          "idType": "passport",
          "issuingCountries": [
            "GB"
          ],
          "requireBack": false
        }
      ],
      "requireSelfie": true,
      "requireVoice": false,
      "livenessMode": "passive",
      "options": {
        "allowedDocumentTypes": [
          "passport"
        ],
        "allowDeviceUpload": false,
        "steps": {
          "documentBack": "auto",
          "documentNearFace": false,
          "activeLiveness": true,
          "speechAnalysis": false
        }
      }
    },
    "selection": null,
    "consent": null,
    "evidence": {},
    "resume": {
      "eligible": true
    },
    "failureBudget": {
      "front": {
        "attempts": 0,
        "max": 10
      },
      "back": {
        "attempts": 0,
        "max": 10
      },
      "selfie": {
        "attempts": 0,
        "max": 10
      },
      "liveness": {
        "attempts": 0,
        "max": 3
      },
      "voice": {
        "attempts": 0,
        "max": 10
      },
      "upload": {
        "attempts": 0,
        "max": 3
      }
    },
    "serverNow": 1790762150000,
    "sessionExpiresAt": 1790763900000
  },
  "requestId": "req-test"
}