Skip to content
API reference Get API keys

Reference · Chapter 14

API reference

Every endpoint, webhook and model, generated from the OpenAPI specification.

KYC Platform API

Version v1
Base URL https://kyc.goxost.net/api/v1

Tenant-facing REST API. Your backend creates an applicant, opens a verification session and hands the session url (hosted flow) or token (SDK) to the end user. The result arrives as a webhook (verification.completed / verification.on_hold); fetch the full result with GET /verifications/{id}.

Conventions

  • JSON, UTF-8. All times are ISO 8601 UTC (2026-11-07T10:00:00Z). Scores are floats in 0..1.
  • IDs: apl_… applicant, ses_… session, ver_… verification, whk_… webhook, whd_… delivery, evt_… event.
  • A key sees only its own tenant and environment (sandbox for sk_test_…, live for sk_live_…). Anything else returns 404 not_found. The same external_id in two environments is two different applicants.
  • Every response carries X-Request-Id: req_… (equal to error.request_id on errors).
  • Rate limit: 600 requests per minute per key (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After on 429).
  • Idempotency: write requests (POST, PATCH, DELETE) accept Idempotency-Key (8–64 chars, [A-Za-z0-9_-]). The same key returns the same response for 24 h with Idempotent-Replayed: true. Reusing a key with a different body → 409 idempotency_conflict; while the first request is still running → 409 conflict. 5xx responses are not stored. A malformed key → 400 bad_request.
  • Sandbox: with sk_test_ the result is mocked by the external_id suffix: -expired (RED retry, DOC_EXPIRED), -mismatch (RED final, FACE_MISMATCH), -hold (ON_HOLD, PEP_MATCH), -sanctions (RED final, SANCTIONS_MATCH), -duplicate (RED final, DUPLICATE from the duplicate check; no details.applicant_ids in sandbox), -underage (RED final, UNDERAGE), -age-unknown (ON_HOLD, AGE_UNKNOWN; only in a checks.age_only flow), -recapture (ON_HOLD, DOC_SCREEN_RECAPTURE from the document authenticity check doc_fraud), anything else → GREEN. Sandbox does not count towards the monthly limit.

Authentication

Authorization: Bearer sk_live_… (live) or sk_test_… (sandbox). Keep keys on your server; give the browser only a session token. A blocked tenant gets 403 forbidden.

Errors

400 bad_request, validation_failed · 401 unauthenticated · 403 forbidden · 404 not_found · 409 conflict, idempotency_conflict · 413 file_too_large (request body over the server limit) · 422 unprocessable · 429 rate_limited, plan_limit_reached · 5xx internal_error, aml_unavailable.

{
    "error": {
        "code": "validation_failed",
        "message": "The external id field is required.",
        "fields": {
            "external_id": [
                "The external id field is required."
            ]
        },
        "request_id": "req_01j9…"
    }
}

Applicants

The person being verified. One active session per applicant.

get /api/v1/applicants

List applicants

Newest first, cursor pagination.

Parameters

  • external_id string query
  • status ApplicantStatus query
  • decision Decision query
  • flow string query
    Flow key.
  • created_from string (date-time) query
  • created_to string (date-time) query
  • limit integer query
  • cursor string query
    Opaque next_cursor from the previous page.

Responses

200 A page of applicants. object
{
    "data": [
        {
            "id": "apl_01j9…",
            "external_id": "user-8812",
            "flow": "basic-kyc",
            "locale": "uz",
            "status": "init",
            "decision": "GREEN",
            "risk_score": 0.5,
            "last_verification_id": "string",
            "metadata": {},
            "purpose": "string",
            "valid_until": "2026-11-07T10:00:00Z",
            "created_at": "2026-11-07T10:00:00Z",
            "updated_at": "2026-11-07T10:00:00Z",
            "identity": {
                "verification_id": "string",
                "verified_at": "2026-11-07T10:00:00Z",
                "document": {
                    "type": "string",
                    "country": "string",
                    "data": {
                        "first_name": "ANNA MARIA",
                        "last_name": "ERIKSSON",
                        "middle_name": null,
                        "full_name": "ANNA MARIA ERIKSSON",
                        "birth_date": null,
                        "place_of_birth": null,
                        "sex": "M",
                        "nationality": "UTO",
                        "document_type": "passport",
                        "document_subtype": "P",
                        "issuing_country": "UTO",
                        "number": "L898902C3",
                        "personal_number": null,
                        "personal_number_type": "JShShIR (PINFL)",
                        "personal_number_valid": null,
                        "issue_date": null,
                        "expiry_date": null,
                        "issuing_authority": null,
                        "address": null,
                        "series": null,
                        "division_code": null,
                        "age": null,
                        "is_expired": null,
                        "days_to_expiry": null,
                        "names": null,
                        "fields": null
                    }
                }
            }
        }
    ],
    "next_cursor": "string"
}
400 validation_failed (field errors in error.fields) or bad_request. Error
{
    "error": {
        "code": "validation_failed",
        "message": "The external id field is required.",
        "fields": {
            "external_id": [
                "The external id field is required."
            ]
        },
        "request_id": "req_01j9…"
    }
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
429 rate_limited Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
post /api/v1/applicants

Create an applicant

Emits applicant.created.

Parameters

  • Idempotency-Key string header
    Same key → same response for 24 h (Idempotent-Replayed: true).

Request body ApplicantCreate

  • external_id string required
    Your user ID; printable ASCII, unique per environment.
  • flow string
  • locale Locale
  • purpose string | null
    Default verification purpose for this applicant's sessions.
  • metadata object
    Non-PII key/value strings, ≤ 2 KB as JSON.
  • email —
    Rejected for now: a non-empty value → 400 validation_failed (fields.email). Not stored or returned (encrypted contact storage is a later stage).
  • phone —
    Rejected for now: a non-empty value → 400 validation_failed (fields.phone). Not stored or returned.
{
    "external_id": "user-8812",
    "flow": "basic-kyc",
    "locale": "uz",
    "metadata": {
        "plan": "gold"
    }
}

Responses

201 Created. Applicant
{
    "id": "apl_01j9…",
    "external_id": "user-8812",
    "flow": "basic-kyc",
    "locale": "uz",
    "status": "init",
    "decision": "GREEN",
    "risk_score": 0.5,
    "last_verification_id": "string",
    "metadata": {},
    "purpose": "string",
    "valid_until": "2026-11-07T10:00:00Z",
    "created_at": "2026-11-07T10:00:00Z",
    "updated_at": "2026-11-07T10:00:00Z",
    "identity": {
        "verification_id": "string",
        "verified_at": "2026-11-07T10:00:00Z",
        "document": {
            "type": "string",
            "country": "string",
            "data": {
                "first_name": "ANNA MARIA",
                "last_name": "ERIKSSON",
                "middle_name": "string",
                "full_name": "ANNA MARIA ERIKSSON",
                "birth_date": "1994-03-12",
                "place_of_birth": "string",
                "sex": "M",
                "nationality": "UTO",
                "document_type": "passport",
                "document_subtype": "P",
                "issuing_country": "UTO",
                "number": "L898902C3",
                "personal_number": "string",
                "personal_number_type": "JShShIR (PINFL)",
                "personal_number_valid": true,
                "issue_date": "1994-03-12",
                "expiry_date": "1994-03-12",
                "issuing_authority": "string",
                "address": "string",
                "series": "string",
                "division_code": "string",
                "age": 0,
                "is_expired": true,
                "days_to_expiry": 0,
                "names": {
                    "mrz": {},
                    "viz": {},
                    "native": {}
                },
                "fields": {}
            }
        }
    }
}
400 validation_failed (field errors in error.fields) or bad_request. Error
{
    "error": {
        "code": "validation_failed",
        "message": "The external id field is required.",
        "fields": {
            "external_id": [
                "The external id field is required."
            ]
        },
        "request_id": "req_01j9…"
    }
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
409 conflict — external_id already exists in this environment, or an idempotency error. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
422 unprocessable — unknown flow. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
429 rate_limited Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/applicants/{id}

Get an applicant

Parameters

  • id string path required
  • include string query
    identity adds the document data of the latest GREEN verification (identity). Without it the key is absent and the vault is not read. Each read is audited (vault.read); include requests have their own per-key rate limit (30/min by default).

Responses

200 Current status and latest decision. Applicant
{
    "id": "apl_01j9…",
    "external_id": "user-8812",
    "flow": "basic-kyc",
    "locale": "uz",
    "status": "init",
    "decision": "GREEN",
    "risk_score": 0.5,
    "last_verification_id": "string",
    "metadata": {},
    "purpose": "string",
    "valid_until": "2026-11-07T10:00:00Z",
    "created_at": "2026-11-07T10:00:00Z",
    "updated_at": "2026-11-07T10:00:00Z",
    "identity": {
        "verification_id": "string",
        "verified_at": "2026-11-07T10:00:00Z",
        "document": {
            "type": "string",
            "country": "string",
            "data": {
                "first_name": "ANNA MARIA",
                "last_name": "ERIKSSON",
                "middle_name": "string",
                "full_name": "ANNA MARIA ERIKSSON",
                "birth_date": "1994-03-12",
                "place_of_birth": "string",
                "sex": "M",
                "nationality": "UTO",
                "document_type": "passport",
                "document_subtype": "P",
                "issuing_country": "UTO",
                "number": "L898902C3",
                "personal_number": "string",
                "personal_number_type": "JShShIR (PINFL)",
                "personal_number_valid": true,
                "issue_date": "1994-03-12",
                "expiry_date": "1994-03-12",
                "issuing_authority": "string",
                "address": "string",
                "series": "string",
                "division_code": "string",
                "age": 0,
                "is_expired": true,
                "days_to_expiry": 0,
                "names": {
                    "mrz": {},
                    "viz": {},
                    "native": {}
                },
                "fields": {}
            }
        }
    }
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — no such resource in this tenant and environment. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
delete /api/v1/applicants/{id}

Delete an applicant

Immediately: open sessions become abandoned, external_id becomes deleted:{id}, metadata is cleared, the applicant's vault key is destroyed (crypto-shred) and files and blind indexes are removed; the core replica is shredded too (retried every 5 minutes if core is down). Emits applicant.deleted (with the original external_id). Afterwards the applicant returns 404; the verification history stays without PII.

Parameters

  • id string path required
  • Idempotency-Key string header
    Same key → same response for 24 h (Idempotent-Replayed: true).

Responses

202 Deletion scheduled. object
{
    "id": "apl_01j9…",
    "status": "deletion_scheduled"
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — no such resource in this tenant and environment. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
post /api/v1/applicants/{id}/reset

Reopen for re-verification

Status → init, decision and risk score cleared, open sessions → abandoned. History is kept. Emits applicant.reset.

Parameters

  • id string path required
  • Idempotency-Key string header
    Same key → same response for 24 h (Idempotent-Replayed: true).

Responses

200 The reset applicant. Applicant
{
    "id": "apl_01j9…",
    "external_id": "user-8812",
    "flow": "basic-kyc",
    "locale": "uz",
    "status": "init",
    "decision": "GREEN",
    "risk_score": 0.5,
    "last_verification_id": "string",
    "metadata": {},
    "purpose": "string",
    "valid_until": "2026-11-07T10:00:00Z",
    "created_at": "2026-11-07T10:00:00Z",
    "updated_at": "2026-11-07T10:00:00Z",
    "identity": {
        "verification_id": "string",
        "verified_at": "2026-11-07T10:00:00Z",
        "document": {
            "type": "string",
            "country": "string",
            "data": {
                "first_name": "ANNA MARIA",
                "last_name": "ERIKSSON",
                "middle_name": "string",
                "full_name": "ANNA MARIA ERIKSSON",
                "birth_date": "1994-03-12",
                "place_of_birth": "string",
                "sex": "M",
                "nationality": "UTO",
                "document_type": "passport",
                "document_subtype": "P",
                "issuing_country": "UTO",
                "number": "L898902C3",
                "personal_number": "string",
                "personal_number_type": "JShShIR (PINFL)",
                "personal_number_valid": true,
                "issue_date": "1994-03-12",
                "expiry_date": "1994-03-12",
                "issuing_authority": "string",
                "address": "string",
                "series": "string",
                "division_code": "string",
                "age": 0,
                "is_expired": true,
                "days_to_expiry": 0,
                "names": {
                    "mrz": {},
                    "viz": {},
                    "native": {}
                },
                "fields": {}
            }
        }
    }
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — no such resource in this tenant and environment. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}

Sessions

A one-time link / SDK token for the hosted verification flow.

post /api/v1/applicants/{id}/sessions

Create a verification session

Only for an applicant with status = init (otherwise 409 conflict; call reset first). One active session per applicant: creating a new one expires the previous one. url opens the hosted flow, token starts the JS/mobile SDK. In live, a reached monthly limit returns 429 plan_limit_reached.

Parameters

  • id string path required
  • Idempotency-Key string header
    Same key → same response for 24 h (Idempotent-Replayed: true).

Request body object

  • redirect_url string (uri)
    "Back to service" button after the result.
  • expires_in integer
    Seconds.
  • locale Locale
    Defaults to the applicant's locale.
  • purpose string | null
    Why the check is done (shown in the certificate). Defaults to the applicant's purpose, then to your business profile's default purpose.
  • contract ContractBinding
    Binds the verification to your contract with the customer. Only the hash is stored; it is included in the signed certificate.
{
    "redirect_url": "https://shop.uz/kyc/done",
    "expires_in": 1800,
    "locale": "ru",
    "purpose": "Hisob ochish",
    "contract": {
        "reference": "DOG-2026/17",
        "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
    }
}

Responses

201 Created. object
{
    "id": "ses_01j9…",
    "url": "https://kyc.goxost.net/v/eyJhbGciOiJFZERTQSJ9…",
    "token": "string",
    "expires_at": "2026-11-07T10:00:00Z"
}
400 validation_failed (field errors in error.fields) or bad_request. Error
{
    "error": {
        "code": "validation_failed",
        "message": "The external id field is required.",
        "fields": {
            "external_id": [
                "The external id field is required."
            ]
        },
        "request_id": "req_01j9…"
    }
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — no such resource in this tenant and environment. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
409 conflict — applicant is not in init. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
422 unprocessable — the applicant's flow no longer exists. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
429 plan_limit_reached (live monthly limit) or rate_limited. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/sessions/{id}

Get a session

Parameters

  • id string path required

Responses

200 Session state. Session
{
    "id": "string",
    "applicant_id": "string",
    "status": "created",
    "locale": "uz",
    "flow_version": 0,
    "steps_done": [
        "string"
    ],
    "expires_at": "2026-11-07T10:00:00Z",
    "started_at": "2026-11-07T10:00:00Z",
    "submitted_at": "2026-11-07T10:00:00Z",
    "created_at": "2026-11-07T10:00:00Z",
    "purpose": "string",
    "contract": {
        "reference": "string",
        "sha256": "string"
    }
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — no such resource in this tenant and environment. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}

Verifications

Results, manual review of ON_HOLD decisions and stored face images.

get /api/v1/applicants/{id}/verifications

Verification history of an applicant

Newest first, up to the last 100 (no pagination). document.data is null unless include=document_data is sent: then every item is read from the vault and each read is audited (vault.read, with reason). include requests have their own per-key rate limit (30/min by default).

Parameters

  • id string path required
  • include string query
  • reason VaultReadReason query

Responses

200 History. object
{
    "data": [
        {
            "id": "ver_01j9…",
            "applicant_id": "string",
            "session_id": "string",
            "decision": "GREEN",
            "decision_type": "final",
            "reject_labels": [
                "BAD_QUALITY"
            ],
            "risk_score": 0.5,
            "checks": [
                {
                    "name": "document",
                    "status": "pass",
                    "score": 0.5,
                    "labels": [
                        "BAD_QUALITY"
                    ],
                    "details": {
                        "lists": [
                            "OFAC_SDN"
                        ],
                        "matches": [
                            null
                        ],
                        "applicant_ids": [
                            "apl_01j9…"
                        ],
                        "age_over": {
                            "threshold": 18,
                            "result": null
                        }
                    }
                }
            ],
            "document": {
                "type": "id_card",
                "country": "UZB",
                "data": {
                    "first_name": "ANNA MARIA",
                    "last_name": "ERIKSSON",
                    "middle_name": "string",
                    "full_name": "ANNA MARIA ERIKSSON",
                    "birth_date": "1994-03-12",
                    "place_of_birth": "string",
                    "sex": "M",
                    "nationality": "UTO",
                    "document_type": "passport",
                    "document_subtype": "P",
                    "issuing_country": "UTO",
                    "number": "L898902C3",
                    "personal_number": "string",
                    "personal_number_type": "JShShIR (PINFL)",
                    "personal_number_valid": true,
                    "issue_date": "1994-03-12",
                    "expiry_date": "1994-03-12",
                    "issuing_authority": "string",
                    "address": "string",
                    "series": "string",
                    "division_code": "string",
                    "age": 0,
                    "is_expired": true,
                    "days_to_expiry": 0,
                    "names": {
                        "mrz": null,
                        "viz": null,
                        "native": null
                    },
                    "fields": {}
                }
            },
            "summary": {
                "face_match": 0.5,
                "liveness": 0.5,
                "aml": {
                    "status": "pass",
                    "matches": [
                        {
                            "list": "OFAC_SDN",
                            "entry_id": null,
                            "score": null,
                            "matched_on": null
                        }
                    ],
                    "lists": [
                        "OFAC_SDN"
                    ]
                },
                "age_over": {
                    "threshold": 0,
                    "result": true
                }
            },
            "valid_until": "2026-11-07T10:00:00Z",
            "purpose": "string",
            "contract": {
                "reference": "string",
                "sha256": "string"
            },
            "review_deadline_at": "2026-11-07T10:00:00Z",
            "reviewed_by": 0,
            "reviewed_at": "2026-11-07T10:00:00Z",
            "created_at": "2026-11-07T10:00:00Z",
            "completed_at": "2026-11-07T10:00:00Z"
        }
    ]
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — no such resource in this tenant and environment. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/verifications/{id}

Get a verification result

document.data is decrypted from the vault and returned only in this response; every read is written to the audit log. With retention none it is available for 72 h after the result, then null (store it yourself), and null for sessions without storage. In sandbox it is a synthetic sample document matching the scenario (no vault read). Always null in age-only flows.

Parameters

Responses

200 Full result. Verification
{
    "id": "ver_01j9…",
    "applicant_id": "string",
    "session_id": "string",
    "decision": "GREEN",
    "decision_type": "final",
    "reject_labels": [
        "BAD_QUALITY"
    ],
    "risk_score": 0.5,
    "checks": [
        {
            "name": "document",
            "status": "pass",
            "score": 0.5,
            "labels": [
                "BAD_QUALITY"
            ],
            "details": {
                "lists": [
                    "OFAC_SDN"
                ],
                "matches": [
                    {
                        "list": "OFAC_SDN",
                        "entry_id": "string",
                        "score": 0.5,
                        "matched_on": [
                            "name"
                        ]
                    }
                ],
                "applicant_ids": [
                    "apl_01j9…"
                ],
                "age_over": {
                    "threshold": 18,
                    "result": true
                }
            }
        }
    ],
    "document": {
        "type": "id_card",
        "country": "UZB",
        "data": {
            "first_name": "ANNA MARIA",
            "last_name": "ERIKSSON",
            "middle_name": "string",
            "full_name": "ANNA MARIA ERIKSSON",
            "birth_date": "1994-03-12",
            "place_of_birth": "string",
            "sex": "M",
            "nationality": "UTO",
            "document_type": "passport",
            "document_subtype": "P",
            "issuing_country": "UTO",
            "number": "L898902C3",
            "personal_number": "string",
            "personal_number_type": "JShShIR (PINFL)",
            "personal_number_valid": true,
            "issue_date": "1994-03-12",
            "expiry_date": "1994-03-12",
            "issuing_authority": "string",
            "address": "string",
            "series": "string",
            "division_code": "string",
            "age": 0,
            "is_expired": true,
            "days_to_expiry": 0,
            "names": {
                "mrz": {},
                "viz": {},
                "native": {}
            },
            "fields": {}
        }
    },
    "summary": {
        "face_match": 0.5,
        "liveness": 0.5,
        "aml": {
            "status": "pass",
            "matches": [
                {
                    "list": "OFAC_SDN",
                    "entry_id": "string",
                    "score": 0.5,
                    "matched_on": [
                        "name"
                    ]
                }
            ],
            "lists": [
                "OFAC_SDN"
            ]
        },
        "age_over": {
            "threshold": 0,
            "result": true
        }
    },
    "valid_until": "2026-11-07T10:00:00Z",
    "purpose": "string",
    "contract": {
        "reference": "string",
        "sha256": "string"
    },
    "review_deadline_at": "2026-11-07T10:00:00Z",
    "reviewed_by": 0,
    "reviewed_at": "2026-11-07T10:00:00Z",
    "created_at": "2026-11-07T10:00:00Z",
    "completed_at": "2026-11-07T10:00:00Z"
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — no such resource in this tenant and environment. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
post /api/v1/verifications/{id}/review

Decide an ON_HOLD verification

Only ON_HOLD verifications can be reviewed (otherwise 409 conflict). If it is the applicant's latest verification, the applicant status is updated as well. Emits verification.reviewed. comment is not stored.

Parameters

  • id string path required
  • Idempotency-Key string header
    Same key → same response for 24 h (Idempotent-Replayed: true).

Request body ReviewRequest

  • decision string required
    GREEN RED
  • decision_type string
    Required for RED, forbidden for GREEN. final retry
  • reject_labels RejectLabel[]
    Required for RED, forbidden for GREEN.
  • comment string
    Not stored.
{
    "decision": "GREEN",
    "comment": "manual check ok"
}

Responses

200 The updated verification (document.data is null here). Verification
{
    "id": "ver_01j9…",
    "applicant_id": "string",
    "session_id": "string",
    "decision": "GREEN",
    "decision_type": "final",
    "reject_labels": [
        "BAD_QUALITY"
    ],
    "risk_score": 0.5,
    "checks": [
        {
            "name": "document",
            "status": "pass",
            "score": 0.5,
            "labels": [
                "BAD_QUALITY"
            ],
            "details": {
                "lists": [
                    "OFAC_SDN"
                ],
                "matches": [
                    {
                        "list": "OFAC_SDN",
                        "entry_id": "string",
                        "score": 0.5,
                        "matched_on": [
                            "name"
                        ]
                    }
                ],
                "applicant_ids": [
                    "apl_01j9…"
                ],
                "age_over": {
                    "threshold": 18,
                    "result": true
                }
            }
        }
    ],
    "document": {
        "type": "id_card",
        "country": "UZB",
        "data": {
            "first_name": "ANNA MARIA",
            "last_name": "ERIKSSON",
            "middle_name": "string",
            "full_name": "ANNA MARIA ERIKSSON",
            "birth_date": "1994-03-12",
            "place_of_birth": "string",
            "sex": "M",
            "nationality": "UTO",
            "document_type": "passport",
            "document_subtype": "P",
            "issuing_country": "UTO",
            "number": "L898902C3",
            "personal_number": "string",
            "personal_number_type": "JShShIR (PINFL)",
            "personal_number_valid": true,
            "issue_date": "1994-03-12",
            "expiry_date": "1994-03-12",
            "issuing_authority": "string",
            "address": "string",
            "series": "string",
            "division_code": "string",
            "age": 0,
            "is_expired": true,
            "days_to_expiry": 0,
            "names": {
                "mrz": {},
                "viz": {},
                "native": {}
            },
            "fields": {}
        }
    },
    "summary": {
        "face_match": 0.5,
        "liveness": 0.5,
        "aml": {
            "status": "pass",
            "matches": [
                {
                    "list": "OFAC_SDN",
                    "entry_id": "string",
                    "score": 0.5,
                    "matched_on": [
                        "name"
                    ]
                }
            ],
            "lists": [
                "OFAC_SDN"
            ]
        },
        "age_over": {
            "threshold": 0,
            "result": true
        }
    },
    "valid_until": "2026-11-07T10:00:00Z",
    "purpose": "string",
    "contract": {
        "reference": "string",
        "sha256": "string"
    },
    "review_deadline_at": "2026-11-07T10:00:00Z",
    "reviewed_by": 0,
    "reviewed_at": "2026-11-07T10:00:00Z",
    "created_at": "2026-11-07T10:00:00Z",
    "completed_at": "2026-11-07T10:00:00Z"
}
400 validation_failed (field errors in error.fields) or bad_request. Error
{
    "error": {
        "code": "validation_failed",
        "message": "The external id field is required.",
        "fields": {
            "external_id": [
                "The external id field is required."
            ]
        },
        "request_id": "req_01j9…"
    }
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — no such resource in this tenant and environment. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
409 conflict — the verification is not ON_HOLD. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/verifications/{id}/media

Stored face images

Face images (AVIF, usually 2–8 KB); the full document image is never stored. Each item has a signed URL valid for 60 seconds (no-store, expired or unsigned link → 403). With retention none images are kept 72 h only for ON_HOLD decisions, otherwise items is empty.

Parameters

  • id string path required

Responses

200 Media list. object
{
    "items": [
        {
            "kind": "document_front",
            "content_type": "image/avif",
            "bytes": 0,
            "sha256": "string",
            "url": "https://…",
            "expires_at": "2026-11-07T10:00:00Z",
            "stored_until": "2026-11-07T10:00:00Z"
        }
    ]
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — no such resource in this tenant and environment. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/verifications/{id}/certificate

Signed verification certificate

Electronically signed certificate ("Tekshiruv dalolatnomasi") for a final (GREEN/RED) verification. Anyone can check it on the public page /verify/{certificate_id} (register, document number or the PDF file). A certificate never changes: a new decision issues a new version and marks the old one superseded. ?format=pdf returns the printable PDF with a QR code to /verify/{certificate_id}. ON_HOLD → 409 conflict; signing key not configured → 503 certificate_unavailable.

Parameters

  • id string path required
  • format string query

Responses

200 Signed certificate (JSON) or PDF file. SignedCertificate
{
    "certificate": {
        "schema": "goxost-kyc/certificate@1",
        "id": "crt_01j9…",
        "version": 0,
        "issued_at": "2026-11-07T10:00:00Z",
        "verify_url": "https://…",
        "issuer": {},
        "requester": {
            "tenant_id": "string",
            "name": "string",
            "project": "string",
            "website": "string"
        },
        "purpose": "string",
        "subject": {},
        "verification": {},
        "checks": [
            {}
        ],
        "images": [
            {
                "kind": "string",
                "sha256": "string"
            }
        ],
        "valid_until": "2026-11-07T10:00:00Z",
        "contract": {
            "reference": "string",
            "sha256": "string"
        },
        "consent": {
            "text_version": "2026-11",
            "given_at": "2026-11-07T10:00:00Z",
            "biometric": true,
            "ip": "string",
            "ip_country": "UZ",
            "device": "iOS 17 · Safari",
            "user_agent": "string"
        }
    },
    "signature": {
        "kid": "string",
        "value": "string"
    },
    "meta": {
        "status": "current",
        "superseded_by": "string"
    }
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — no such resource in this tenant and environment. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
409 conflict — the verification is not final (ON_HOLD). Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
503 certificate_unavailable Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/certificates/{certificate_id}

Certificate status

Status of one of your own certificates (this tenant and environment). No PII. valid is true only when the certificate is the current version, the decision is GREEN and valid_until has not passed.

Parameters

  • certificate_id string path required

Responses

200 Certificate status. CertificateStatus
{
    "certificate_id": "string",
    "version": 0,
    "status": "current",
    "signature_valid": true,
    "valid": true,
    "decision": "GREEN",
    "outcome": "string",
    "issued_at": "2026-11-07T10:00:00Z",
    "valid_until": "2026-11-07T10:00:00Z",
    "expired": true,
    "superseded_by": "string",
    "verify_url": "https://…"
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — no such resource in this tenant and environment. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}

AML

Standalone sanctions screening (OFAC SDN, UN, UK, EU; natural persons only).

post /api/v1/aml/screen

Screen a name against sanctions lists

Same rules as the in-flow aml check: match (RED) only with name + exact birth date. The name and date are never stored or logged. Each successful search increments usage.aml_checks; in live up to the plan limit per month, then 429 plan_limit_reached. Lists not loaded or core down → 503 aml_unavailable (not counted).

Parameters

  • Idempotency-Key string header
    Same key → same response for 24 h (Idempotent-Replayed: true).

Request body object

  • name string required
    Cyrillic or Latin.
  • birth_date string (date) | null
    YYYY-MM-DD, before today. Optional but recommended to rule out namesakes.
{
    "name": "Alisher Karimov",
    "birth_date": "1994-03-12"
}

Responses

200 Screening result. AmlScreenResult
{
    "result": "clear",
    "labels": [
        "SANCTIONS_MATCH"
    ],
    "matches": [
        {
            "list": "OFAC_SDN",
            "entry_id": "string",
            "score": 0.5,
            "matched_on": [
                "name"
            ]
        }
    ],
    "lists": [
        {
            "list": "string",
            "version": "string",
            "entries": 0,
            "updated_at": "2026-11-07T10:00:00Z"
        }
    ]
}
400 validation_failed (field errors in error.fields) or bad_request. Error
{
    "error": {
        "code": "validation_failed",
        "message": "The external id field is required.",
        "fields": {
            "external_id": [
                "The external id field is required."
            ]
        },
        "request_id": "req_01j9…"
    }
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
429 plan_limit_reached (live monthly limit) or rate_limited. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
503 aml_unavailable Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}

Flows

Verification configuration. Read-only; edited in the panel (each change is a new version).

get /api/v1/flows

List flows

The latest active version of each flow key. Every new tenant has basic-kyc.

Responses

200 Flows. object
{
    "data": [
        {
            "key": "basic-kyc",
            "name": "Basic KYC",
            "version": 0,
            "steps": [
                "consent"
            ],
            "documents": {
                "allowed_countries": [
                    "string"
                ],
                "types": [
                    "passport"
                ],
                "nfc": "off",
                "nfc_fallback": "hold"
            },
            "min_age": 0,
            "checks": {
                "aml": true,
                "duplicate": true,
                "age_only": true
            },
            "retention": {
                "mode": "standard",
                "ttl": "24h"
            },
            "max_attempts": 0
        }
    ]
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/flows/{key}

Get a flow

Parameters

  • key string path required

Responses

200 Latest active version. Flow
{
    "key": "basic-kyc",
    "name": "Basic KYC",
    "version": 0,
    "steps": [
        "consent"
    ],
    "documents": {
        "allowed_countries": [
            "string"
        ],
        "types": [
            "passport"
        ],
        "nfc": "off",
        "nfc_fallback": "hold"
    },
    "min_age": 0,
    "checks": {
        "aml": true,
        "duplicate": true,
        "age_only": true
    },
    "retention": {
        "mode": "standard",
        "ttl": "24h"
    },
    "max_attempts": 0
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — no such resource in this tenant and environment. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}

Webhooks

Endpoints that receive events. Signed with KYC-Signature.

get /api/v1/webhooks

List webhook endpoints

Responses

200 Endpoints of this environment. object
{
    "data": [
        {
            "id": "whk_01j9…",
            "url": "https://…",
            "events": [
                "string"
            ],
            "include_document_data": true,
            "is_active": true,
            "status": "ok",
            "created_at": "2026-11-07T10:00:00Z"
        }
    ]
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
post /api/v1/webhooks

Create a webhook endpoint

url must be https:// and resolve to a public IP (local, private and link-local addresses are rejected with 400); redirects are not followed. At most 10 endpoints per environment (422). The signing secret is returned only once, in this response.

Parameters

  • Idempotency-Key string header
    Same key → same response for 24 h (Idempotent-Replayed: true).

Request body WebhookInput + any

  • url string (uri) required
  • events EventType | "*"[] required
  • is_active boolean
  • include_document_data boolean
    Opt-in: add extracted identity data (PII) to verification.completed. Default off.
{
    "url": "https://shop.uz/kyc/webhook",
    "events": [
        "verification.completed",
        "verification.on_hold"
    ]
}

Responses

201 Created. Webhook + object
{
    "id": "whk_01j9…",
    "url": "https://…",
    "events": [
        "string"
    ],
    "include_document_data": true,
    "is_active": true,
    "status": "ok",
    "created_at": "2026-11-07T10:00:00Z",
    "secret": "whsec_…"
}
400 validation_failed (field errors in error.fields) or bad_request. Error
{
    "error": {
        "code": "validation_failed",
        "message": "The external id field is required.",
        "fields": {
            "external_id": [
                "The external id field is required."
            ]
        },
        "request_id": "req_01j9…"
    }
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
422 unprocessable — endpoint limit (10) reached. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
patch /api/v1/webhooks/{id}

Update a webhook endpoint

Partial update. Set is_active to false to pause deliveries.

Parameters

  • id string path required
  • Idempotency-Key string header
    Same key → same response for 24 h (Idempotent-Replayed: true).

Request body WebhookInput

  • url string (uri)
  • events EventType | "*"[]
  • is_active boolean
  • include_document_data boolean
    Opt-in: add extracted identity data (PII) to verification.completed. Default off.
{
    "is_active": false
}

Responses

200 Updated endpoint. Webhook
{
    "id": "whk_01j9…",
    "url": "https://…",
    "events": [
        "string"
    ],
    "include_document_data": true,
    "is_active": true,
    "status": "ok",
    "created_at": "2026-11-07T10:00:00Z"
}
400 validation_failed (field errors in error.fields) or bad_request. Error
{
    "error": {
        "code": "validation_failed",
        "message": "The external id field is required.",
        "fields": {
            "external_id": [
                "The external id field is required."
            ]
        },
        "request_id": "req_01j9…"
    }
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — no such resource in this tenant and environment. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
delete /api/v1/webhooks/{id}

Delete a webhook endpoint

Parameters

  • id string path required
  • Idempotency-Key string header
    Same key → same response for 24 h (Idempotent-Replayed: true).

Responses

204 Deleted.
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — no such resource in this tenant and environment. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
post /api/v1/webhooks/{id}/test

Send a test event

Queues a webhook.test event, even if the endpoint is paused.

Parameters

  • id string path required
  • Idempotency-Key string header
    Same key → same response for 24 h (Idempotent-Replayed: true).

Responses

202 Queued. object
{
    "delivery_id": "whd_01j9…"
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — no such resource in this tenant and environment. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/webhooks/{id}/deliveries

Delivery log

The last 100 deliveries of the endpoint, newest first.

Parameters

  • id string path required

Responses

200 Deliveries. object
{
    "data": [
        {
            "id": "whd_01j9…",
            "event_id": "evt_01j9…",
            "event": "applicant.created",
            "status": "pending",
            "attempt": 0,
            "status_code": 0,
            "next_retry_at": "2026-11-07T10:00:00Z",
            "delivered_at": "2026-11-07T10:00:00Z",
            "created_at": "2026-11-07T10:00:00Z"
        }
    ]
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — no such resource in this tenant and environment. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
post /api/v1/webhooks/deliveries/{id}/retry

Retry a delivery now

Attempts the delivery immediately; later retries follow the normal backoff.

Parameters

  • id string path required
    Delivery ID from the delivery log.
  • Idempotency-Key string header
    Same key → same response for 24 h (Idempotent-Replayed: true).

Responses

200 Status after the attempt. object
{
    "status": "pending"
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — no such resource in this tenant and environment. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}

Usage

Monthly counters and plan limit.

get /api/v1/usage

Monthly usage

Parameters

  • period string query
    YYYY-MM, defaults to the current month (UTC).

Responses

200 Counters. object
{
    "period": "2026-11",
    "plan": "free",
    "limit": 0,
    "live": {
        "verifications": 0,
        "aml_checks": 0,
        "direct_checks": 0
    },
    "sandbox": {
        "verifications": 0,
        "direct_checks": 0
    },
    "core_url": "https://kyc-core.9k.uz/v1"
}
400 validation_failed (field errors in error.fields) or bad_request. Error
{
    "error": {
        "code": "validation_failed",
        "message": "The external id field is required.",
        "fields": {
            "external_id": [
                "The external id field is required."
            ]
        },
        "request_id": "req_01j9…"
    }
}
401 unauthenticated — missing or invalid API key. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}

Documents

Public catalog of supported identity documents per country and their support level. No API key.

get /api/v1/documents/catalog

Supported documents catalog

Public, read-only, no API key (rate limit 60/min per IP). Lists, per issuing country (ISO 3166-1 alpha-3; mrz_code is the issuing-state code printed on the document, e.g. Germany = D), which document types are verified and at which level: mrz_full (document data fully read and checked, can be GREEN automatically), mrz_basic (data read but a key field is derived — always ON_HOLD with DOC_REVIEW_REQUIRED), viz_ocr and manual_review (never GREEN automatically). A standard international passport is read even if its issuer is missing from the list. Generated from core (contracts/document_catalog.json).

Responses

200 Catalog. object
{
    "version": "2026-11-08",
    "support_levels": [
        "mrz_full"
    ],
    "types": [
        {
            "type": "passport",
            "formats": [
                "TD3"
            ],
            "support": "mrz_full"
        }
    ],
    "countries": [
        {
            "country": "UZB",
            "mrz_code": "UZB",
            "personal_number": "string",
            "documents": [
                {
                    "type": "passport",
                    "format": "TD3",
                    "support": "mrz_full"
                }
            ],
            "field_profile": {}
        }
    ],
    "field_expectations": [
        "present"
    ],
    "field_profile_defaults": {},
    "field_profiles": {}
}
429 Too many requests.

Webhooks

post applicant.created

Applicant created

Sent after POST /applicants.

Parameters

  • KYC-Signature string header required
    t=<unix seconds>,v1=<hex> where v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Verify the HMAC over the raw body and reject t older than ±5 minutes. Non-2xx responses are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h; after all attempts fail the endpoint is marked failing until the next successful delivery.

Request body Event + object

  • id string required
  • type EventType required
  • created_at string (date-time) required
  • env Environment required
  • data object required
    • applicant_id string required
    • external_id string required
{
    "id": "evt_01j9…",
    "type": "applicant.created",
    "created_at": "2026-11-07T10:00:00Z",
    "env": "sandbox",
    "data": {
        "applicant_id": "string",
        "external_id": "string"
    }
}

Responses

2XX Acknowledge with any 2xx.
post session.started

Session started

The applicant gave consent and started the flow. Sent once per session.

Parameters

  • KYC-Signature string header required
    t=<unix seconds>,v1=<hex> where v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Verify the HMAC over the raw body and reject t older than ±5 minutes. Non-2xx responses are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h; after all attempts fail the endpoint is marked failing until the next successful delivery.

Request body Event + object

  • id string required
  • type EventType required
  • created_at string (date-time) required
  • env Environment required
  • data object required
    • applicant_id string required
    • external_id string required
    • session_id string required
{
    "id": "evt_01j9…",
    "type": "applicant.created",
    "created_at": "2026-11-07T10:00:00Z",
    "env": "sandbox",
    "data": {
        "applicant_id": "string",
        "external_id": "string",
        "session_id": "string"
    }
}

Responses

2XX Acknowledge with any 2xx.
post verification.submitted

Verification submitted

The applicant submitted all steps; checks start. Sent once per session, after session.started.

Parameters

  • KYC-Signature string header required
    t=<unix seconds>,v1=<hex> where v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Verify the HMAC over the raw body and reject t older than ±5 minutes. Non-2xx responses are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h; after all attempts fail the endpoint is marked failing until the next successful delivery.

Request body Event + object

  • id string required
  • type EventType required
  • created_at string (date-time) required
  • env Environment required
  • data object required
    • applicant_id string required
    • external_id string required
    • session_id string required
{
    "id": "evt_01j9…",
    "type": "applicant.created",
    "created_at": "2026-11-07T10:00:00Z",
    "env": "sandbox",
    "data": {
        "applicant_id": "string",
        "external_id": "string",
        "session_id": "string"
    }
}

Responses

2XX Acknowledge with any 2xx.
post verification.completed

Final decision (GREEN/RED)

Fetch the full result with GET /verifications/{verification_id}.

Parameters

  • KYC-Signature string header required
    t=<unix seconds>,v1=<hex> where v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Verify the HMAC over the raw body and reject t older than ±5 minutes. Non-2xx responses are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h; after all attempts fail the endpoint is marked failing until the next successful delivery.

Request body Event + object

  • id string required
  • type EventType required
  • created_at string (date-time) required
  • env Environment required
  • data object required
    • applicant_id string required
    • external_id string required
    • verification_id string required
    • decision Decision required
    • decision_type DecisionType required
      For RED — retry (the applicant may try again after reset) or final.
    • reject_labels RejectLabel[] required
    • document_data object | null
      Only in verification.completed when the endpoint has include_document_data: true — same shape as document.data with ?include=document_data. Each delivery attempt is an audited vault read (reason webhook_delivery).
    • document_data_status string
      Present together with document_data. not_stored — retention expired, applicant deleted or nothing stored; not_applicable — age-only mode or no document. included not_stored not_applicable
{
    "id": "evt_01j9…",
    "type": "verification.completed",
    "created_at": "2026-11-07T10:05:00Z",
    "env": "live",
    "data": {
        "applicant_id": "apl_01j9…",
        "external_id": "user-8812",
        "verification_id": "ver_01j9…",
        "decision": "GREEN",
        "decision_type": null,
        "reject_labels": []
    }
}

Responses

2XX Acknowledge with any 2xx.
post verification.on_hold

Manual review needed

Decision is ON_HOLD; resolve in the panel or via POST /verifications/{id}/review.

Parameters

  • KYC-Signature string header required
    t=<unix seconds>,v1=<hex> where v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Verify the HMAC over the raw body and reject t older than ±5 minutes. Non-2xx responses are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h; after all attempts fail the endpoint is marked failing until the next successful delivery.

Request body Event + object

  • id string required
  • type EventType required
  • created_at string (date-time) required
  • env Environment required
  • data object required
    • applicant_id string required
    • external_id string required
    • verification_id string required
    • decision Decision required
    • decision_type DecisionType required
      For RED — retry (the applicant may try again after reset) or final.
    • reject_labels RejectLabel[] required
    • document_data object | null
      Only in verification.completed when the endpoint has include_document_data: true — same shape as document.data with ?include=document_data. Each delivery attempt is an audited vault read (reason webhook_delivery).
    • document_data_status string
      Present together with document_data. not_stored — retention expired, applicant deleted or nothing stored; not_applicable — age-only mode or no document. included not_stored not_applicable
{
    "id": "evt_01j9…",
    "type": "verification.completed",
    "created_at": "2026-11-07T10:05:00Z",
    "env": "live",
    "data": {
        "applicant_id": "apl_01j9…",
        "external_id": "user-8812",
        "verification_id": "ver_01j9…",
        "decision": "GREEN",
        "decision_type": null,
        "reject_labels": []
    }
}

Responses

2XX Acknowledge with any 2xx.
post verification.reviewed

Reviewer decided

An ON_HOLD verification was decided by an operator or via the API — or cancelled by the system when review_deadline_at passed: then decision: RED, decision_type: retry, reject_labels: [REVIEW_EXPIRED] (a pending four-eyes proposal is discarded).

Parameters

  • KYC-Signature string header required
    t=<unix seconds>,v1=<hex> where v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Verify the HMAC over the raw body and reject t older than ±5 minutes. Non-2xx responses are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h; after all attempts fail the endpoint is marked failing until the next successful delivery.

Request body Event + object

  • id string required
  • type EventType required
  • created_at string (date-time) required
  • env Environment required
  • data object required
    • applicant_id string required
    • external_id string required
    • verification_id string required
    • decision Decision required
    • decision_type DecisionType required
      For RED — retry (the applicant may try again after reset) or final.
    • reject_labels RejectLabel[] required
    • document_data object | null
      Only in verification.completed when the endpoint has include_document_data: true — same shape as document.data with ?include=document_data. Each delivery attempt is an audited vault read (reason webhook_delivery).
    • document_data_status string
      Present together with document_data. not_stored — retention expired, applicant deleted or nothing stored; not_applicable — age-only mode or no document. included not_stored not_applicable
{
    "id": "evt_01j9…",
    "type": "verification.completed",
    "created_at": "2026-11-07T10:05:00Z",
    "env": "live",
    "data": {
        "applicant_id": "apl_01j9…",
        "external_id": "user-8812",
        "verification_id": "ver_01j9…",
        "decision": "GREEN",
        "decision_type": null,
        "reject_labels": []
    }
}

Responses

2XX Acknowledge with any 2xx.
post verification.review_reminder

Manual review deadline reminder

Sent for an ON_HOLD verification right after it is put on hold, when 2 days are left and when 24 hours are left (each stage at most once; checked hourly). After review_deadline_at the verification is cancelled (verification.reviewed with REVIEW_EXPIRED).

Parameters

  • KYC-Signature string header required
    t=<unix seconds>,v1=<hex> where v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Verify the HMAC over the raw body and reject t older than ±5 minutes. Non-2xx responses are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h; after all attempts fail the endpoint is marked failing until the next successful delivery.

Request body Event + object

  • id string required
  • type EventType required
  • created_at string (date-time) required
  • env Environment required
  • data object required
    • verification_id string required
    • applicant_id string required
    • review_deadline_at string (date-time) required
    • hours_left integer required
{
    "id": "evt_01j9…",
    "type": "applicant.created",
    "created_at": "2026-11-07T10:00:00Z",
    "env": "sandbox",
    "data": {
        "verification_id": "string",
        "applicant_id": "string",
        "review_deadline_at": "2026-11-07T10:00:00Z",
        "hours_left": 0
    }
}

Responses

2XX Acknowledge with any 2xx.
post certificate.issued

Certificate issued

A signed certificate (or a new version after re-review) was issued, about 5 minutes after the final decision. Download it with certificate_url / pdf_url and your API key. With include_document_data: true the event also carries certificate (the signed document), pdf_base64 and certificate_status (included · not_stored).

Parameters

  • KYC-Signature string header required
    t=<unix seconds>,v1=<hex> where v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Verify the HMAC over the raw body and reject t older than ±5 minutes. Non-2xx responses are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h; after all attempts fail the endpoint is marked failing until the next successful delivery.

Request body Event + object

  • id string required
  • type EventType required
  • created_at string (date-time) required
  • env Environment required
  • data object required
    • certificate_id string required
    • version integer required
    • verification_id string required
    • applicant_id string required
    • external_id string | null
    • decision string required
      GREEN RED
    • issued_at string (date-time) required
    • valid_until string (date-time) | null
    • supersedes string | null
    • verify_url string (uri) required
    • certificate_url string (uri) required
    • pdf_url string (uri) required
    • certificate SignedCertificate
    • pdf_base64 string | null
    • certificate_status string
      included not_stored
{
    "id": "evt_01j9…",
    "type": "applicant.created",
    "created_at": "2026-11-07T10:00:00Z",
    "env": "sandbox",
    "data": {
        "certificate_id": "string",
        "version": 0,
        "verification_id": "string",
        "applicant_id": "string",
        "external_id": "string",
        "decision": "GREEN",
        "issued_at": "2026-11-07T10:00:00Z",
        "valid_until": "2026-11-07T10:00:00Z",
        "supersedes": "string",
        "verify_url": "https://…",
        "certificate_url": "https://…",
        "pdf_url": "https://…",
        "certificate": {
            "certificate": {
                "schema": "goxost-kyc/certificate@1",
                "id": "crt_01j9…",
                "version": 0,
                "issued_at": "2026-11-07T10:00:00Z",
                "verify_url": "https://…",
                "issuer": {},
                "requester": {
                    "tenant_id": "string",
                    "name": "string",
                    "project": "string",
                    "website": "string"
                },
                "purpose": "string",
                "subject": {},
                "verification": {},
                "checks": [
                    {}
                ],
                "images": [
                    {
                        "kind": "string",
                        "sha256": "string"
                    }
                ],
                "valid_until": "2026-11-07T10:00:00Z",
                "contract": {
                    "reference": "string",
                    "sha256": "string"
                },
                "consent": {
                    "text_version": "2026-11",
                    "given_at": "2026-11-07T10:00:00Z",
                    "biometric": true,
                    "ip": "string",
                    "ip_country": "UZ",
                    "device": "iOS 17 · Safari",
                    "user_agent": "string"
                }
            },
            "signature": {
                "kid": "string",
                "value": "string"
            },
            "meta": {
                "status": "current",
                "superseded_by": "string"
            }
        },
        "pdf_base64": "string",
        "certificate_status": "included"
    }
}

Responses

2XX Acknowledge with any 2xx.
post applicant.reverification_due

Re-verification due

A GREEN verification is valid for 2 years (valid_until). Sent once when 30 days are left (stage: due_soon) and once on expiry (stage: expired); checked daily, only for the applicant's latest verification.

Parameters

  • KYC-Signature string header required
    t=<unix seconds>,v1=<hex> where v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Verify the HMAC over the raw body and reject t older than ±5 minutes. Non-2xx responses are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h; after all attempts fail the endpoint is marked failing until the next successful delivery.

Request body Event + object

  • id string required
  • type EventType required
  • created_at string (date-time) required
  • env Environment required
  • data object required
    • applicant_id string required
    • verification_id string required
    • valid_until string (date-time) required
    • stage string required
      due_soon expired
{
    "id": "evt_01j9…",
    "type": "applicant.created",
    "created_at": "2026-11-07T10:00:00Z",
    "env": "sandbox",
    "data": {
        "applicant_id": "string",
        "verification_id": "string",
        "valid_until": "2026-11-07T10:00:00Z",
        "stage": "due_soon"
    }
}

Responses

2XX Acknowledge with any 2xx.
post applicant.reset

Applicant reset

Parameters

  • KYC-Signature string header required
    t=<unix seconds>,v1=<hex> where v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Verify the HMAC over the raw body and reject t older than ±5 minutes. Non-2xx responses are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h; after all attempts fail the endpoint is marked failing until the next successful delivery.

Request body Event + object

  • id string required
  • type EventType required
  • created_at string (date-time) required
  • env Environment required
  • data object required
    • applicant_id string required
    • external_id string required
{
    "id": "evt_01j9…",
    "type": "applicant.created",
    "created_at": "2026-11-07T10:00:00Z",
    "env": "sandbox",
    "data": {
        "applicant_id": "string",
        "external_id": "string"
    }
}

Responses

2XX Acknowledge with any 2xx.
post applicant.deleted

Applicant deleted

data.external_id is the original value (before anonymisation).

Parameters

  • KYC-Signature string header required
    t=<unix seconds>,v1=<hex> where v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Verify the HMAC over the raw body and reject t older than ±5 minutes. Non-2xx responses are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h; after all attempts fail the endpoint is marked failing until the next successful delivery.

Request body Event + object

  • id string required
  • type EventType required
  • created_at string (date-time) required
  • env Environment required
  • data object required
    • applicant_id string required
    • external_id string required
{
    "id": "evt_01j9…",
    "type": "applicant.created",
    "created_at": "2026-11-07T10:00:00Z",
    "env": "sandbox",
    "data": {
        "applicant_id": "string",
        "external_id": "string"
    }
}

Responses

2XX Acknowledge with any 2xx.
post aml.match

Ongoing monitoring match

Reserved for ongoing AML monitoring (not emitted yet).

Parameters

  • KYC-Signature string header required
    t=<unix seconds>,v1=<hex> where v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Verify the HMAC over the raw body and reject t older than ±5 minutes. Non-2xx responses are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h; after all attempts fail the endpoint is marked failing until the next successful delivery.

Request body Event + object

  • id string required
  • type EventType required
  • created_at string (date-time) required
  • env Environment required
  • data object required
    • applicant_id string required
    • external_id string required
{
    "id": "evt_01j9…",
    "type": "applicant.created",
    "created_at": "2026-11-07T10:00:00Z",
    "env": "sandbox",
    "data": {
        "applicant_id": "string",
        "external_id": "string"
    }
}

Responses

2XX Acknowledge with any 2xx.
post webhook.test

Test event

Sent by POST /webhooks/{id}/test.

Parameters

  • KYC-Signature string header required
    t=<unix seconds>,v1=<hex> where v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Verify the HMAC over the raw body and reject t older than ±5 minutes. Non-2xx responses are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h; after all attempts fail the endpoint is marked failing until the next successful delivery.

Request body Event + object

  • id string required
  • type EventType required
  • created_at string (date-time) required
  • env Environment required
  • data object required
    • webhook_id string required
{
    "id": "evt_01j9…",
    "type": "applicant.created",
    "created_at": "2026-11-07T10:00:00Z",
    "env": "sandbox",
    "data": {
        "webhook_id": "string"
    }
}

Responses

2XX Acknowledge with any 2xx.

Models

Error

object
  • error object required
    • code ErrorCode required
      400 bad_request, validation_failed · 401 unauthenticated · 403 forbidden · 404 not_found · 409 conflict, idempotency_conflict · 413 file_too_large (request body over the server limit) · 422 unprocessable · 429 rate_limited, plan_limit_reached · 5xx internal_error, aml_unavailable.
    • message string required
    • fields object
      Field → list of messages (validation errors only).
    • request_id string required

ErrorCode

string

400 bad_request, validation_failed · 401 unauthenticated · 403 forbidden · 404 not_found · 409 conflict, idempotency_conflict · 413 file_too_large (request body over the server limit) · 422 unprocessable · 429 rate_limited, plan_limit_reached · 5xx internal_error, aml_unavailable.

bad_request validation_failed unauthenticated forbidden not_found conflict idempotency_conflict file_too_large unprocessable rate_limited plan_limit_reached internal_error aml_unavailable

Locale

string
uz ru en

Environment

string
sandbox live

ApplicantStatus

string

init — new, after reset or after a RED retry; pending is reserved and currently never set.

init pending on_hold completed

Decision

string
GREEN RED ON_HOLD

DecisionType

string | null

For RED — retry (the applicant may try again after reset) or final.

final retry

RejectLabel

string

Reason code (see the reject label table). DOC_RECAPTURE (RED retry) only when the operator enables it. AGE_UNKNOWN (review → ON_HOLD) only in age-only flows (checks.age_only). PERSONAL_NUMBER_INVALID and DOC_REVIEW_REQUIRED are review labels (→ ON_HOLD). Document data reading: MRZ_NOT_READABLE (retry) — the data could not be read reliably, ask for a new photo; MRZ_INVALID — the submitted document data or its dates are invalid; MRZ_LOW_CONFIDENCE (→ ON_HOLD) — the data was read with low confidence; DOC_DATA_MISMATCH — the document data is inconsistent. Electronic document check (flow documents.nfc, mobile SDK only): CHIP_HASH_MISMATCH, CHIP_SIGNATURE_INVALID, CHIP_MRZ_MISMATCH are final RED; CHIP_CHAIN_UNVERIFIED, CHIP_CLONE_SUSPECTED, CHIP_NOT_READ are review labels (→ ON_HOLD). Document authenticity check (doc_fraud): DOC_SCREEN_RECAPTURE, DOC_PRINTED_COPY, DOC_PHOTO_TAMPERED, DOC_TEMPLATE_MISMATCH mean the document image did not pass the authenticity check; they are review labels (→ ON_HOLD). REVIEW_EXPIRED (RED retry) is set only by the system when an ON_HOLD verification was not reviewed before review_deadline_at; it cannot be chosen in a manual review.

BAD_QUALITY DOC_NOT_SUPPORTED MRZ_NOT_READABLE MRZ_INVALID MRZ_LOW_CONFIDENCE DOC_DATA_MISMATCH DOC_EXPIRED DOC_RECAPTURE DOC_FORGED UNDERAGE FACE_NOT_FOUND FACE_MISMATCH FACE_MATCH_UNCERTAIN LIVENESS_FAILED LIVENESS_SPOOF LIVENESS_UNCERTAIN SANCTIONS_MATCH SANCTIONS_POSSIBLE CHECK_UNAVAILABLE PEP_MATCH DUPLICATE MAX_ATTEMPTS DOC_FACE_UNBOUND AML_NO_NAME AGE_UNKNOWN PERSONAL_NUMBER_INVALID DOC_REVIEW_REQUIRED CHIP_HASH_MISMATCH CHIP_SIGNATURE_INVALID CHIP_CHAIN_UNVERIFIED CHIP_MRZ_MISMATCH CHIP_CLONE_SUSPECTED CHIP_NOT_READ DOC_SCREEN_RECAPTURE DOC_PRINTED_COPY DOC_PHOTO_TAMPERED DOC_TEMPLATE_MISMATCH REVIEW_EXPIRED

DocumentType

string

residence_permit and visa were added on 2026-11-08; a flow that lists only the legacy types (id_card, passport, ru_internal_passport) and includes id_card also accepts residence_permit (previously reported as id_card). driving_licence is reserved (not yet read automatically).

passport id_card residence_permit ru_internal_passport visa driving_licence

SupportLevel

string
mrz_full mrz_basic viz_ocr manual_review

CertificateStatus

object
  • certificate_id string | null required
  • version integer | null required
  • status string required
    current superseded revoked invalid_signature unknown
  • signature_valid boolean required
  • valid boolean required
    current + GREEN + not expired
  • decision string | null required
    GREEN RED
  • outcome string | null
  • issued_at string (date-time) | null required
  • valid_until string (date-time) | null required
  • expired boolean required
  • superseded_by string | null required
  • verify_url string (uri) | null required

EventType

string
applicant.created session.started verification.submitted verification.completed verification.on_hold verification.reviewed verification.review_reminder applicant.reverification_due certificate.issued applicant.reset applicant.deleted aml.match webhook.test

ApplicantCreate

object
  • external_id string required
    Your user ID; printable ASCII, unique per environment.
  • flow string
  • locale Locale
  • purpose string | null
    Default verification purpose for this applicant's sessions.
  • metadata object
    Non-PII key/value strings, ≤ 2 KB as JSON.
  • email —
    Rejected for now: a non-empty value → 400 validation_failed (fields.email). Not stored or returned (encrypted contact storage is a later stage).
  • phone —
    Rejected for now: a non-empty value → 400 validation_failed (fields.phone). Not stored or returned.

Applicant

object
  • id string required
  • external_id string required
  • flow string required
  • locale Locale required
  • status ApplicantStatus required
    init — new, after reset or after a RED retry; pending is reserved and currently never set.
  • decision Decision | null required
  • risk_score number | null required
  • last_verification_id string | null required
  • metadata object required
  • purpose string | null
  • valid_until string (date-time) | null
    Validity of the latest verification (GREEN only, decision + 2 years).
  • created_at string (date-time) required
  • updated_at string (date-time) required
  • identity object | null
    Only with ?include=identity. null when the applicant has no GREEN verification.
    • verification_id string required
    • verified_at string (date-time) required
    • document object | null required
      • type string required
      • country string | null required
      • data DocumentData | null required

Session

object
  • id string required
  • applicant_id string required
  • status string required
    created started submitted processed expired abandoned
  • locale Locale required
  • flow_version integer required
  • steps_done string[] required
  • expires_at string (date-time) required
  • started_at string (date-time) | null required
  • submitted_at string (date-time) | null required
  • created_at string (date-time) required
  • purpose string | null
  • contract ContractBinding | null

ContractBinding

object

Binds the verification to your contract with the customer. Only the hash is stored; it is included in the signed certificate.

  • reference string | null
    Your contract number.
  • sha256 string required
    SHA-256 of the contract file (hex; returned lowercase).

SignedCertificate

object
  • certificate object required
    Signed fields (see API.md §3.3 for the full example). Keys without a value are omitted, except consent.
    • schema "goxost-kyc/certificate@1" required
    • id string required
    • version integer required
    • issued_at string (date-time) required
    • verify_url string (uri) required
    • issuer object required
    • requester object required
      • tenant_id string required
      • name string required
        Legal name from the business profile, otherwise the company name.
      • project string
      • website string
    • purpose string
    • subject object required
      applicant_id, external_id, full_name, birth_date and document {type, country, number_masked}.
    • verification object required
    • checks object[] required
    • images object[] required
      • kind string
      • sha256 string
    • valid_until string (date-time)
    • contract ContractBinding
      Binds the verification to your contract with the customer. Only the hash is stored; it is included in the signed certificate.
    • consent object | null required
      Consent evidence (also in sandbox). Always present; null when consent was not recorded (older verifications). The IP and user agent appear only in the certificate — never in GET /verifications/{id}, webhooks or the public /verify page. Schema stays goxost-kyc/certificate@1.
      • text_version string required
      • given_at string (date-time) required
      • biometric boolean required
        Biometric (face) processing consent.
      • ip string | null required
        IPv4 or IPv6 address the consent came from.
      • ip_country string | null required
      • device string | null required
        Short summary of the user agent.
      • user_agent string | null required
  • signature object required
    • kid string required
    • value string required
      Electronic signature of certificate. It is checked only by GOXOST KYC.
  • meta object required
    Not signed.
    • status string
      current superseded
    • superseded_by string | null

Check

object
  • name string required
  • status string required
    pass warn fail error
  • score number | null required
  • labels RejectLabel[] required
  • details object
    Present only for some checks (aml → lists and, on a hit, matches; duplicate → applicant_ids, age → age_over). No PII.
    • lists string[]
      Sanctions lists this aml check actually screened. An optional list (EU) is absent when it is missing or stale.
    • matches AmlMatch[]
    • applicant_ids string[]
      Other applicants of your tenant with the same document number (oldest first). Not returned in sandbox.
    • age_over object
      Age-only flows (checks.age_only). The date of birth itself is never returned.
      • threshold integer required
        The flow min_age.
      • result boolean | null required
        true — at least threshold years old, false — younger (UNDERAGE), null — date of birth unknown (AGE_UNKNOWN).

Verification

object
  • id string required
  • applicant_id string required
  • session_id string required
  • decision Decision required
  • decision_type DecisionType required
    For RED — retry (the applicant may try again after reset) or final.
  • reject_labels RejectLabel[] required
  • risk_score number | null required
  • checks Check[] required
  • document object | null required
    • type string required
      A DocumentType, or unknown.
    • country string | null required
      ISO 3166-1 alpha-3.
    • data DocumentData | null required
      Decrypted document fields (PII). See the operation description for availability. Always null in age-only flows.
  • summary object
    PII-free digest of the check scores. A key is null when that check did not run.
    • face_match number | null
    • liveness number | null
    • aml object | null
      • status string
        pass warn fail error
      • matches AmlMatch[]
      • lists string[]
    • age_over object | null
      • threshold integer
      • result boolean | null
  • valid_until string (date-time) | null
    GREEN only: decision time + 2 years. Re-verify before it (applicant.reverification_due).
  • purpose string | null
  • contract ContractBinding | null
  • review_deadline_at string (date-time) | null
    ON_HOLD only: review before this time (ON_HOLD + 7 days), otherwise the verification is cancelled (RED REVIEW_EXPIRED). null for automatic decisions.
  • reviewed_by integer | null required
    Panel user ID of the reviewer; null for automatic decisions, API reviews and system cancellation.
  • reviewed_at string (date-time) | null required
  • created_at string (date-time) required
  • completed_at string (date-time) | null required
    null while ON_HOLD.

VaultReadReason

string

Audited reason of a vault read (default api_request). Unknown value → 400 validation_failed.

panel_view manual_review customer_request compliance_audit legal_request api_request

DocumentData

object

Fields read from the document (PII). Only keys are added over time, never removed; a field that was not read is null. Older vault records have null for the newer keys. Example values are the synthetic "Utopia" sample document.

  • first_name string | null
  • last_name string | null
  • middle_name string | null
    Patronymic (RU internal passport also keeps patronymic).
  • full_name string | null
    first_name middle_name last_name.
  • birth_date string (date) | null
  • place_of_birth string | null
  • sex string | null
    M F X
  • nationality string | null
  • document_type string | null
  • document_subtype string | null
    Document type code printed on the document.
  • issuing_country string | null
  • number string | null
  • personal_number string | null
  • personal_number_type string | null
  • personal_number_valid boolean | null
    National checksum algorithm result; null when no validator exists.
  • issue_date string (date) | null
  • expiry_date string (date) | null
  • issuing_authority string | null
  • address string | null
    Not read from any document yet; see fields.address.status.
  • series string
    RU internal passport only.
  • division_code string
    RU internal passport only.
  • age integer | null
    Computed at read time (UTC today).
  • is_expired boolean | null
  • days_to_expiry integer | null
    Negative when expired.
  • names object | null
    • mrz object | null
      Latin names as read from the document.
    • viz object | null
      Names from the fallback reading when the main reading was not possible.
    • native object | null
      Native script (RU internal passport — Cyrillic).
  • fields object | null
    Per field. Every read field, plus middle_name, issue_date, place_of_birth, issuing_authority, address, native_name and personal_number even when their value is null (with status). The status never changes the decision.

ReviewRequest

object
  • decision string required
    GREEN RED
  • decision_type string
    Required for RED, forbidden for GREEN. final retry
  • reject_labels RejectLabel[]
    Required for RED, forbidden for GREEN.
  • comment string
    Not stored.

MediaItem

object
  • kind string required
    What the image shows. document_front document_back document_face selfie_face liveness_frame
  • content_type string required
  • bytes integer required
  • sha256 string | null
    SHA-256 of the image bytes (null for objects stored before 2026-11-08).
  • url string (uri) required
  • expires_at string (date-time) required
    The signed URL expires at this time.
  • stored_until string (date-time) | null
    The image itself is deleted at this time (7 days after processing).

AmlMatch

object
  • list string required
    OFAC_SDN UN UK EU
  • entry_id string required
    Open the entry on the list's source site by this ID (the listed name is not returned).
  • score number required
  • matched_on string[] required

AmlScreenResult

object
  • result string required
    possible needs manual review; match = name + exact birth date. clear possible match
  • labels string[] required
  • matches AmlMatch[] required
  • lists object[] required
    Versions of the lists used for this search (an optional list such as EU is absent when missing or stale).
    • list string required
    • version string required
      Leading part of the source file sha256.
    • entries integer required
    • updated_at string (date-time) required

Flow

object
  • key string required
  • name string required
  • version integer required
  • steps string[] required
  • documents object required
    • allowed_countries string[]
      Issuing-state codes as printed on the document (1–3 letters, e.g. UZB, Germany = D), or ["*"] = any.
    • types DocumentType[]
    • nfc string
      Electronic document check in the mobile SDK (chip check). Not available in the web flow. off optional required
    • nfc_fallback string
      required but the electronic document check did not run (e.g. web flow): hold → CHIP_NOT_READ (ON_HOLD); block → submit answers 409 nfc_required. hold block
  • min_age integer required
  • checks object required
    • aml boolean
    • duplicate boolean
    • age_only boolean
      Confirm only that the applicant is at least min_age (an age check); no document data is returned or stored. Never combined with aml or duplicate.
  • retention object required
    • mode string
      standard (default for new tenants) — images 7 days + text for ttl; none — text not kept, images only for ON_HOLD (7 days). compact is a legacy value treated as standard. standard none compact
    • ttl string | null
      Text data term for standard/compact (1y or 5y, default 5y; 24h/30d legacy only), null for none. 24h 30d 1y 5y
  • max_attempts integer required
    Informational only — not enforced yet (MAX_ATTEMPTS is never emitted).

WebhookInput

object
  • url string (uri)
  • events EventType | "*"[]
  • is_active boolean
  • include_document_data boolean
    Opt-in: add extracted identity data (PII) to verification.completed. Default off.

Webhook

object
  • id string required
  • url string (uri) required
  • events string[] required
  • include_document_data boolean required
  • is_active boolean required
  • status string required
    failing — the last delivery failed after all retries. ok failing
  • created_at string (date-time) required

DeliveryStatus

string
pending delivered failed

WebhookDelivery

object
  • id string required
  • event_id string required
  • event EventType required
  • status DeliveryStatus required
  • attempt integer required
  • status_code integer | null required
    HTTP status returned by your endpoint.
  • next_retry_at string (date-time) | null required
  • delivered_at string (date-time) | null required
  • created_at string (date-time) required

Event

object

Webhook payload envelope. Contains no PII; fetch details via the API.

  • id string required
  • type EventType required
  • created_at string (date-time) required
  • env Environment required
  • data object required
    Depends on type: - applicant.created, applicant.reset, applicant.deleted — {applicant_id, external_id} (for deleted, the original external_id; sent before the stored data is destroyed). - session.started, verification.submitted — {applicant_id, external_id, session_id}. - verification.completed, verification.on_hold, verification.reviewed — {applicant_id, external_id, verification_id, decision, decision_type, reject_labels}. - webhook.test — {webhook_id}. Delivery: first attempt + 6 retries (1 min, 5 min, 30 min, 2 h, 6 h, 24 h), 10 s timeout.