Asosiy qismga oʻtish
API hujjati API kalitini olish

Maʼlumotnoma · 14-bob

API hujjati

Har bir manzil (endpoint), webhook va model — OpenAPI spetsifikatsiyasidan avtomatik yaratilgan.

KYC platformasi API

Versiya v1
Asosiy URL https://kyc.goxost.net/api/v1

Biznes (tenant) uchun REST API. Backendingiz arizachi yaratadi, tekshiruv sessiyasini ochadi va sessiya url ini (hosted senariy) yoki token ini (SDK) foydalanuvchiga beradi. Natija webhook bilan keladi (verification.completed / verification.on_hold); toʻliq natijani GET /verifications/{id} bilan oling.

Kelishuvlar

  • JSON, UTF-8. Barcha vaqtlar ISO 8601 UTC da (2026-11-07T10:00:00Z). Ballar 0..1 oraligʻidagi kasr sonlar.
  • ID lar: apl_… arizachi, ses_… sessiya, ver_… tekshiruv, whk_… webhook, whd_… yuborish, evt_… hodisa.
  • Kalit faqat oʻz biznesi va muhitini koʻradi (sk_test_… uchun sandbox, sk_live_… uchun live). Boshqa hamma narsa 404 not_found qaytaradi. Ikki muhitdagi bir xil external_id — bu ikki xil arizachi.
  • Har bir javobda X-Request-Id: req_… bor (xatolarda error.request_id ga teng).
  • Soʻrov limiti: har bir kalitga daqiqasiga 600 soʻrov (X-RateLimit-Limit, X-RateLimit-Remaining, 429 da Retry-After).
  • Idempotentlik: yozuvchi soʻrovlar (POST, PATCH, DELETE) Idempotency-Key ni qabul qiladi (8–64 belgi, [A-Za-z0-9_-]). Bir xil kalit 24 h davomida Idempotent-Replayed: true bilan bir xil javobni qaytaradi. Kalitni boshqa tana bilan qayta ishlatish → 409 idempotency_conflict; birinchi soʻrov hali bajarilayotgan boʻlsa → 409 conflict. 5xx javoblar saqlanmaydi. Notoʻgʻri formatdagi kalit → 400 bad_request.
  • Sinov rejimi: sk_test_ bilan natija external_id qoʻshimchasiga qarab soxta qilib beriladi: -expired (RED retry, DOC_EXPIRED), -mismatch (RED final, FACE_MISMATCH), -hold (ON_HOLD, PEP_MATCH), -sanctions (RED final, SANCTIONS_MATCH), -duplicate (duplicate tekshiruvidan RED final, DUPLICATE; sinov rejimida details.applicant_ids yoʻq), -underage (RED final, UNDERAGE), -age-unknown (ON_HOLD, AGE_UNKNOWN; faqat checks.age_only oqimida), -recapture (hujjat haqiqiyligini tekshirish doc_fraud dan ON_HOLD, DOC_SCREEN_RECAPTURE), qolgan hammasi → GREEN. Sinov rejimi oylik limitga hisoblanmaydi.

Autentifikatsiya

Authorization: Bearer sk_live_… (ishchi rejim) yoki sk_test_… (sinov rejimi). Kalitlarni serveringizda saqlang; brauzerga faqat sessiya tokenini bering. Bloklangan biznes 403 forbidden oladi.

Xatolar

400 bad_request, validation_failed · 401 unauthenticated · 403 forbidden · 404 not_found · 409 conflict, idempotency_conflict · 413 file_too_large (soʻrov tanasi server limitidan katta) · 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…"
    }
}

Arizachilar

Tekshirilayotgan odam. Har bir arizachi uchun bitta faol sessiya.

get /api/v1/applicants

Arizachilar roʻyxati

Eng yangisi birinchi, kursorli sahifalash.

Parametrlar

  • external_id string query
  • status ApplicantStatus query
  • decision Decision query
  • flow string query
    Senariy kaliti.
  • created_from string (date-time) query
  • created_to string (date-time) query
  • limit integer query
  • cursor string query
    Oldingi sahifadagi shaffof boʻlmagan next_cursor.

Javoblar

200 Arizachilar sahifasi. 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 (maydon xatolari error.fields da) yoki 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 — API kalit yoʻq yoki notoʻgʻri. 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

Arizachi yaratish

applicant.created hodisasini yuboradi.

Parametrlar

  • Idempotency-Key string header
    Bir xil kalit → 24 h davomida bir xil javob (Idempotent-Replayed: true).

Soʻrov tanasi ApplicantCreate

  • external_id string majburiy
    Sizdagi foydalanuvchi ID si; bosma ASCII, har bir muhitda yagona.
  • flow string
  • locale Locale
  • purpose string | null
    Shu arizachi sessiyalari uchun tekshiruvning sukut boʻyicha maqsadi.
  • metadata object
    Shaxsiy maʼlumot boʻlmagan kalit/qiymat satrlari, JSON koʻrinishida ≤ 2 KB.
  • email —
    Hozircha rad etiladi: boʻsh boʻlmagan qiymat → 400 validation_failed (fields.email). Saqlanmaydi va qaytarilmaydi (aloqa maʼlumotlarini shifrlab saqlash keyingi bosqichda).
  • phone —
    Hozircha rad etiladi: boʻsh boʻlmagan qiymat → 400 validation_failed (fields.phone). Saqlanmaydi va qaytarilmaydi.
{
    "external_id": "user-8812",
    "flow": "basic-kyc",
    "locale": "uz",
    "metadata": {
        "plan": "gold"
    }
}

Javoblar

201 Yaratildi. 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 (maydon xatolari error.fields da) yoki 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 — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
409 conflict — bu muhitda shunday external_id allaqachon bor yoki idempotentlik xatosi. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
422 unprocessable — notanish 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}

Arizachini olish

Parametrlar

  • id string path majburiy
  • include string query
    identity oxirgi GREEN tekshiruvning hujjat maʼlumotlarini (identity) qoʻshadi. Usiz bu kalit boʻlmaydi va shifrlangan omborga murojaat qilinmaydi. Har bir oʻqish auditga yoziladi (vault.read); include soʻrovlarining har bir kalit uchun alohida limiti bor (sukut boʻyicha 30/min).

Javoblar

200 Joriy holat va oxirgi qaror. 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 — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — bu biznes va muhitda bunday resurs yoʻq. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
delete /api/v1/applicants/{id}

Arizachini oʻchirish

Darhol: ochiq sessiyalar abandoned boʻladi, external_id deleted:{id} ga aylanadi, metadata tozalanadi, arizachining shifrlangan ombor kaliti yoʻq qilinadi (crypto-shred), fayllar va blind indekslar oʻchiriladi; core dagi nusxa ham yoʻq qilinadi (core ishlamayotgan boʻlsa, har 5 daqiqada qayta uriniladi). applicant.deleted hodisasini yuboradi (asl external_id bilan). Shundan keyin arizachi 404 qaytaradi; tekshiruvlar tarixi shaxsiy maʼlumotlarsiz qoladi.

Parametrlar

  • id string path majburiy
  • Idempotency-Key string header
    Bir xil kalit → 24 h davomida bir xil javob (Idempotent-Replayed: true).

Javoblar

202 Oʻchirish rejalashtirildi. object
{
    "id": "apl_01j9…",
    "status": "deletion_scheduled"
}
401 unauthenticated — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — bu biznes va muhitda bunday resurs yoʻq. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
post /api/v1/applicants/{id}/reset

Qayta tekshiruv uchun qayta ochish

Holat → init, qaror va risk bali tozalanadi, ochiq sessiyalar → abandoned. Tarix saqlanadi. applicant.reset hodisasini yuboradi.

Parametrlar

  • id string path majburiy
  • Idempotency-Key string header
    Bir xil kalit → 24 h davomida bir xil javob (Idempotent-Replayed: true).

Javoblar

200 Qayta ochilgan arizachi. 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 — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — bu biznes va muhitda bunday resurs yoʻq. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}

Sessiyalar

Hosted tekshiruv senariysi uchun bir martalik havola / SDK tokeni.

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

Tekshiruv sessiyasini yaratish

Faqat status = init boʻlgan arizachi uchun (aks holda 409 conflict; avval reset ni chaqiring). Har bir arizachi uchun bitta faol sessiya: yangisini yaratish oldingisining muddatini tugatadi. url hosted senariyni ochadi, token JS/mobil SDK ni ishga tushiradi. live da oylik limit tugagan boʻlsa, 429 plan_limit_reached qaytadi.

Parametrlar

  • id string path majburiy
  • Idempotency-Key string header
    Bir xil kalit → 24 h davomida bir xil javob (Idempotent-Replayed: true).

Soʻrov tanasi object

  • redirect_url string (uri)
    Natijadan keyingi "Xizmatga qaytish" tugmasi.
  • expires_in integer
    Soniya.
  • locale Locale
    Sukut boʻyicha arizachining tili.
  • purpose string | null
    Tekshiruv nima uchun qilinadi (dalolatnomada koʻrinadi). Sukut boʻyicha arizachining purpose i, u boʻlmasa biznes profilingizdagi sukut boʻyicha maqsad.
  • contract ContractBinding
    Tekshiruvni mijoz bilan tuzgan shartnomangizga bogʻlaydi. Faqat xesh saqlanadi; u imzolangan dalolatnomaga kiritiladi.
{
    "redirect_url": "https://shop.uz/kyc/done",
    "expires_in": 1800,
    "locale": "ru",
    "purpose": "Hisob ochish",
    "contract": {
        "reference": "DOG-2026/17",
        "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
    }
}

Javoblar

201 Yaratildi. object
{
    "id": "ses_01j9…",
    "url": "https://kyc.goxost.net/v/eyJhbGciOiJFZERTQSJ9…",
    "token": "string",
    "expires_at": "2026-11-07T10:00:00Z"
}
400 validation_failed (maydon xatolari error.fields da) yoki 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 — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — bu biznes va muhitda bunday resurs yoʻq. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
409 conflict — arizachi init holatida emas. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
422 unprocessable — arizachining senariysi endi mavjud emas. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
429 plan_limit_reached (ishchi rejimning oylik limiti) yoki rate_limited. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/sessions/{id}

Sessiyani olish

Parametrlar

  • id string path majburiy

Javoblar

200 Sessiya holati. 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 — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — bu biznes va muhitda bunday resurs yoʻq. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}

Tekshiruvlar

Natijalar, ON_HOLD qarorlarni qoʻlda koʻrib chiqish va saqlangan yuz rasmlari.

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

Arizachining tekshiruvlar tarixi

Eng yangisi birinchi, oxirgi 100 tagacha (sahifalashsiz). include=document_data yuborilmasa, document.data null boʻladi: yuborilsa, har bir element shifrlangan ombordan oʻqiladi va har bir oʻqish auditga yoziladi (vault.read, reason bilan). include soʻrovlarining har bir kalit uchun alohida limiti bor (sukut boʻyicha 30/min).

Parametrlar

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

Javoblar

200 Tarix. 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 — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — bu biznes va muhitda bunday resurs yoʻq. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/verifications/{id}

Tekshiruv natijasini olish

document.data shifrlangan ombordan ochiladi va faqat shu javobda qaytariladi; har bir oʻqish audit jurnaliga yoziladi. Saqlash none boʻlsa, u natijadan keyin 72 h davomida mavjud, keyin null (oʻzingiz saqlang), saqlashsiz sessiyalarda esa null. Sinov rejimida bu senariyga mos sintetik namuna hujjat (shifrlangan omborga murojaat qilinmaydi). Faqat yoshni tekshiradigan senariylarda doim null.

Parametrlar

Javoblar

200 Toʻliq natija. 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 — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — bu biznes va muhitda bunday resurs yoʻq. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
post /api/v1/verifications/{id}/review

ON_HOLD tekshiruv boʻyicha qaror chiqarish

Faqat ON_HOLD tekshiruvlarni koʻrib chiqish mumkin (aks holda 409 conflict). Agar bu arizachining oxirgi tekshiruvi boʻlsa, arizachi holati ham yangilanadi. verification.reviewed hodisasini yuboradi. comment saqlanmaydi.

Parametrlar

  • id string path majburiy
  • Idempotency-Key string header
    Bir xil kalit → 24 h davomida bir xil javob (Idempotent-Replayed: true).

Soʻrov tanasi ReviewRequest

  • decision string majburiy
    GREEN RED
  • decision_type string
    RED uchun majburiy, GREEN uchun taqiqlangan. final retry
  • reject_labels RejectLabel[]
    RED uchun majburiy, GREEN uchun taqiqlangan.
  • comment string
    Saqlanmaydi.
{
    "decision": "GREEN",
    "comment": "manual check ok"
}

Javoblar

200 Yangilangan tekshiruv (bu yerda document.data null). 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 (maydon xatolari error.fields da) yoki 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 — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — bu biznes va muhitda bunday resurs yoʻq. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
409 conflict — tekshiruv ON_HOLD emas. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/verifications/{id}/media

Saqlangan yuz rasmlari

Yuz rasmlari (AVIF, odatda 2–8 KB); hujjatning toʻliq rasmi hech qachon saqlanmaydi. Har bir elementda 60 soniya amal qiladigan imzolangan URL bor (no-store, muddati oʻtgan yoki imzosiz havola → 403). Saqlash none boʻlsa, rasmlar faqat ON_HOLD qarorlar uchun 72 h saqlanadi, aks holda items boʻsh.

Parametrlar

  • id string path majburiy

Javoblar

200 Media roʻyxati. 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 — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — bu biznes va muhitda bunday resurs yoʻq. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/verifications/{id}/certificate

Imzolangan tekshiruv dalolatnomasi

Yakuniy (GREEN/RED) tekshiruv uchun elektron imzo bilan tasdiqlangan dalolatnoma («Tekshiruv dalolatnomasi»). Uni istalgan odam /verify/{certificate_id} ochiq sahifasida tekshira oladi (reyestr, hujjat raqami yoki PDF fayl orqali). Dalolatnoma hech qachon oʻzgarmaydi: yangi qaror yangi version beradi va eskisini almashtirilgan deb belgilaydi. ?format=pdf /verify/{certificate_id} ga olib boradigan QR kodli, chop etishga tayyor PDF ni qaytaradi. ON_HOLD → 409 conflict; elektron imzo sozlanmagan → 503 certificate_unavailable.

Parametrlar

  • id string path majburiy
  • format string query

Javoblar

200 Imzolangan dalolatnoma (JSON) yoki PDF fayl. 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 — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — bu biznes va muhitda bunday resurs yoʻq. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
409 conflict — tekshiruv yakuniy emas (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}

Dalolatnoma holati

Oʻzingizning dalolatnomalaringizdan birining holati (shu biznes va muhit). Shaxsiy maʼlumot yoʻq. valid faqat dalolatnoma joriy versiya boʻlsa, qaror GREEN boʻlsa va valid_until oʻtmagan boʻlsa true boʻladi.

Parametrlar

  • certificate_id string path majburiy

Javoblar

200 Dalolatnoma holati. 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 — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — bu biznes va muhitda bunday resurs yoʻq. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}

AML

Alohida sanksiyalar tekshiruvi (OFAC SDN, UN, UK, EU; faqat jismoniy shaxslar).

post /api/v1/aml/screen

Ismni sanksiyalar roʻyxatlari boʻyicha tekshirish

Senariy ichidagi aml tekshiruvi bilan bir xil qoidalar: match (RED) faqat ism + aniq tugʻilgan sana bilan. Ism va sana hech qachon saqlanmaydi va logga yozilmaydi. Har bir muvaffaqiyatli qidiruv usage.aml_checks ni oshiradi; live da oyiga tarif limit igacha, keyin 429 plan_limit_reached. Roʻyxatlar yuklanmagan yoki core ishlamayapti → 503 aml_unavailable (hisoblanmaydi).

Parametrlar

  • Idempotency-Key string header
    Bir xil kalit → 24 h davomida bir xil javob (Idempotent-Replayed: true).

Soʻrov tanasi object

  • name string majburiy
    Kirill yoki lotin yozuvida.
  • birth_date string (date) | null
    YYYY-MM-DD, bugungi kundan oldin. Ixtiyoriy, lekin adashlarni chiqarib tashlash uchun tavsiya qilinadi.
{
    "name": "Alisher Karimov",
    "birth_date": "1994-03-12"
}

Javoblar

200 Tekshiruv natijasi. 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 (maydon xatolari error.fields da) yoki 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 — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
429 plan_limit_reached (ishchi rejimning oylik limiti) yoki 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…"
    }
}

Senariylar

Tekshiruv sozlamalari. Faqat oʻqish uchun; panelda tahrirlanadi (har bir oʻzgarish — yangi versiya).

get /api/v1/flows

Senariylar roʻyxati

Har bir senariy kalitining oxirgi faol versiyasi. Har bir yangi biznesda basic-kyc bor.

Javoblar

200 Senariylar. 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 — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/flows/{key}

Senariyni olish

Parametrlar

  • key string path majburiy

Javoblar

200 Oxirgi faol versiya. 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 — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — bu biznes va muhitda bunday resurs yoʻq. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}

Webhooklar

Hodisalarni qabul qiladigan manzillar. KYC-Signature bilan imzolanadi.

get /api/v1/webhooks

Webhook manzillari roʻyxati

Javoblar

200 Shu muhitning manzillari. 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 — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
post /api/v1/webhooks

Webhook manzilini yaratish

url https:// boʻlishi va ochiq IP ga yoʻnaltirilishi kerak (lokal, xususiy va link-local manzillar 400 bilan rad etiladi); redirectlarga oʻtilmaydi. Har bir muhitda koʻpi bilan 10 ta manzil (422). Imzo siri secret faqat bir marta, shu javobda qaytariladi.

Parametrlar

  • Idempotency-Key string header
    Bir xil kalit → 24 h davomida bir xil javob (Idempotent-Replayed: true).

Soʻrov tanasi WebhookInput + any

  • url string (uri) majburiy
  • events EventType | "*"[] majburiy
  • is_active boolean
  • include_document_data boolean
    Ixtiyoriy: verification.completed ga hujjatdan olingan shaxsiy maʼlumotlarni qoʻshish. Sukut boʻyicha oʻchiq.
{
    "url": "https://shop.uz/kyc/webhook",
    "events": [
        "verification.completed",
        "verification.on_hold"
    ]
}

Javoblar

201 Yaratildi. 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 (maydon xatolari error.fields da) yoki 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 — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
422 unprocessable — manzillar limiti (10) tugadi. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
patch /api/v1/webhooks/{id}

Webhook manzilini yangilash

Qisman yangilash. Yuborishni toʻxtatib turish uchun is_active ni false qiling.

Parametrlar

  • id string path majburiy
  • Idempotency-Key string header
    Bir xil kalit → 24 h davomida bir xil javob (Idempotent-Replayed: true).

Soʻrov tanasi WebhookInput

  • url string (uri)
  • events EventType | "*"[]
  • is_active boolean
  • include_document_data boolean
    Ixtiyoriy: verification.completed ga hujjatdan olingan shaxsiy maʼlumotlarni qoʻshish. Sukut boʻyicha oʻchiq.
{
    "is_active": false
}

Javoblar

200 Yangilangan manzil. 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 (maydon xatolari error.fields da) yoki 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 — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — bu biznes va muhitda bunday resurs yoʻq. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
delete /api/v1/webhooks/{id}

Webhook manzilini oʻchirish

Parametrlar

  • id string path majburiy
  • Idempotency-Key string header
    Bir xil kalit → 24 h davomida bir xil javob (Idempotent-Replayed: true).

Javoblar

204 Oʻchirildi.
401 unauthenticated — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — bu biznes va muhitda bunday resurs yoʻq. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
post /api/v1/webhooks/{id}/test

Sinov hodisasini yuborish

Manzil toʻxtatilgan boʻlsa ham webhook.test hodisasini navbatga qoʻyadi.

Parametrlar

  • id string path majburiy
  • Idempotency-Key string header
    Bir xil kalit → 24 h davomida bir xil javob (Idempotent-Replayed: true).

Javoblar

202 Navbatga qoʻyildi. object
{
    "delivery_id": "whd_01j9…"
}
401 unauthenticated — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — bu biznes va muhitda bunday resurs yoʻq. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/webhooks/{id}/deliveries

Yuborishlar jurnali

Manzilga oxirgi 100 ta yuborish, eng yangisi birinchi.

Parametrlar

  • id string path majburiy

Javoblar

200 Yuborishlar. 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 — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — bu biznes va muhitda bunday resurs yoʻq. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
post /api/v1/webhooks/deliveries/{id}/retry

Yuborishni hozir qayta urinish

Yuborishga darhol urinadi; keyingi qayta urinishlar odatdagi oraliqlar bilan davom etadi.

Parametrlar

  • id string path majburiy
    Yuborishlar jurnalidagi yuborish ID si.
  • Idempotency-Key string header
    Bir xil kalit → 24 h davomida bir xil javob (Idempotent-Replayed: true).

Javoblar

200 Urinishdan keyingi holat. object
{
    "status": "pending"
}
401 unauthenticated — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — bu biznes va muhitda bunday resurs yoʻq. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}

Foydalanish

Oylik hisoblagichlar va tarif limiti.

get /api/v1/usage

Oylik foydalanish

Parametrlar

  • period string query
    YYYY-MM, sukut boʻyicha joriy oy (UTC).

Javoblar

200 Hisoblagichlar. 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 (maydon xatolari error.fields da) yoki 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 — API kalit yoʻq yoki notoʻgʻri. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}

Hujjatlar

Har bir mamlakat boʻyicha qoʻllab-quvvatlanadigan shaxs hujjatlari va ularning qoʻllab-quvvatlanish darajasi — ochiq katalog. API kalit kerak emas.

get /api/v1/documents/catalog

Qoʻllab-quvvatlanadigan hujjatlar katalogi

Ochiq, faqat oʻqish uchun, API kalitsiz (soʻrov limiti har bir IP ga 60/min). Har bir hujjat bergan mamlakat boʻyicha (ISO 3166-1 alpha-3; mrz_code — hujjatda yozilgan, hujjat bergan davlat kodi, masalan Germaniya = D) qaysi hujjat turlari va qaysi darajada tekshirilishini koʻrsatadi: mrz_full (hujjat maʼlumotlari toʻliq oʻqiladi va tekshiriladi, avtomatik GREEN boʻlishi mumkin), mrz_basic (maʼlumotlar oʻqiladi, lekin muhim maydonlardan biri hisoblab chiqariladi — doim DOC_REVIEW_REQUIRED bilan ON_HOLD), viz_ocr va manual_review (hech qachon avtomatik GREEN boʻlmaydi). Xalqaro standartdagi pasport, uni bergan davlat roʻyxatda boʻlmasa ham, oʻqiladi. Core dan generatsiya qilinadi (contracts/document_catalog.json).

Javoblar

200 Katalog. 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 Soʻrovlar juda koʻp.

Webhooklar

post applicant.created

Arizachi yaratildi

POST /applicants dan keyin yuboriladi.

Parametrlar

  • KYC-Signature string header majburiy
    t=<unix seconds>,v1=<hex>, bunda v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). HMAC ni xom tana boʻyicha tekshiring va ±5 daqiqadan eski t ni rad eting. 2xx boʻlmagan javoblarda qayta urinish 1 min, 5 min, 30 min, 2 h, 6 h va 24 h dan keyin boʻladi; barcha urinishlar muvaffaqiyatsiz boʻlsa, manzil keyingi muvaffaqiyatli yuborishgacha failing deb belgilanadi.

Soʻrov tanasi Event + object

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

Javoblar

2XX Istalgan 2xx bilan tasdiqlang.
post session.started

Sessiya boshlandi

Arizachi rozilik berdi va senariyni boshladi. Har bir sessiyada bir marta yuboriladi.

Parametrlar

  • KYC-Signature string header majburiy
    t=<unix seconds>,v1=<hex>, bunda v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). HMAC ni xom tana boʻyicha tekshiring va ±5 daqiqadan eski t ni rad eting. 2xx boʻlmagan javoblarda qayta urinish 1 min, 5 min, 30 min, 2 h, 6 h va 24 h dan keyin boʻladi; barcha urinishlar muvaffaqiyatsiz boʻlsa, manzil keyingi muvaffaqiyatli yuborishgacha failing deb belgilanadi.

Soʻrov tanasi Event + object

  • id string majburiy
  • type EventType majburiy
  • created_at string (date-time) majburiy
  • env Environment majburiy
  • data object majburiy
    • applicant_id string majburiy
    • external_id string majburiy
    • session_id string majburiy
{
    "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"
    }
}

Javoblar

2XX Istalgan 2xx bilan tasdiqlang.
post verification.submitted

Tekshiruv topshirildi

Arizachi barcha qadamlarni topshirdi; tekshiruvlar boshlanadi. Har bir sessiyada bir marta, session.started dan keyin yuboriladi.

Parametrlar

  • KYC-Signature string header majburiy
    t=<unix seconds>,v1=<hex>, bunda v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). HMAC ni xom tana boʻyicha tekshiring va ±5 daqiqadan eski t ni rad eting. 2xx boʻlmagan javoblarda qayta urinish 1 min, 5 min, 30 min, 2 h, 6 h va 24 h dan keyin boʻladi; barcha urinishlar muvaffaqiyatsiz boʻlsa, manzil keyingi muvaffaqiyatli yuborishgacha failing deb belgilanadi.

Soʻrov tanasi Event + object

  • id string majburiy
  • type EventType majburiy
  • created_at string (date-time) majburiy
  • env Environment majburiy
  • data object majburiy
    • applicant_id string majburiy
    • external_id string majburiy
    • session_id string majburiy
{
    "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"
    }
}

Javoblar

2XX Istalgan 2xx bilan tasdiqlang.
post verification.completed

Yakuniy qaror (GREEN/RED)

Toʻliq natijani GET /verifications/{verification_id} bilan oling.

Parametrlar

  • KYC-Signature string header majburiy
    t=<unix seconds>,v1=<hex>, bunda v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). HMAC ni xom tana boʻyicha tekshiring va ±5 daqiqadan eski t ni rad eting. 2xx boʻlmagan javoblarda qayta urinish 1 min, 5 min, 30 min, 2 h, 6 h va 24 h dan keyin boʻladi; barcha urinishlar muvaffaqiyatsiz boʻlsa, manzil keyingi muvaffaqiyatli yuborishgacha failing deb belgilanadi.

Soʻrov tanasi Event + object

  • id string majburiy
  • type EventType majburiy
  • created_at string (date-time) majburiy
  • env Environment majburiy
  • data object majburiy
    • applicant_id string majburiy
    • external_id string majburiy
    • verification_id string majburiy
    • decision Decision majburiy
    • decision_type DecisionType majburiy
      RED uchun — retry (arizachi reset dan keyin qayta urinishi mumkin) yoki final.
    • reject_labels RejectLabel[] majburiy
    • document_data object | null
      Faqat verification.completed da, manzilda include_document_data: true boʻlsa — shakli ?include=document_data bilan olingan document.data bilan bir xil. Har bir yuborish urinishi shifrlangan ombordan auditga yoziladigan oʻqish hisoblanadi (sabab webhook_delivery).
    • document_data_status string
      document_data bilan birga keladi. not_stored — saqlash muddati tugagan, arizachi oʻchirilgan yoki hech narsa saqlanmagan; not_applicable — faqat yoshni tekshirish rejimi yoki hujjat yoʻq. 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": []
    }
}

Javoblar

2XX Istalgan 2xx bilan tasdiqlang.
post verification.on_hold

Qoʻlda koʻrib chiqish kerak

Qaror ON_HOLD; panelda yoki POST /verifications/{id}/review orqali hal qiling.

Parametrlar

  • KYC-Signature string header majburiy
    t=<unix seconds>,v1=<hex>, bunda v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). HMAC ni xom tana boʻyicha tekshiring va ±5 daqiqadan eski t ni rad eting. 2xx boʻlmagan javoblarda qayta urinish 1 min, 5 min, 30 min, 2 h, 6 h va 24 h dan keyin boʻladi; barcha urinishlar muvaffaqiyatsiz boʻlsa, manzil keyingi muvaffaqiyatli yuborishgacha failing deb belgilanadi.

Soʻrov tanasi Event + object

  • id string majburiy
  • type EventType majburiy
  • created_at string (date-time) majburiy
  • env Environment majburiy
  • data object majburiy
    • applicant_id string majburiy
    • external_id string majburiy
    • verification_id string majburiy
    • decision Decision majburiy
    • decision_type DecisionType majburiy
      RED uchun — retry (arizachi reset dan keyin qayta urinishi mumkin) yoki final.
    • reject_labels RejectLabel[] majburiy
    • document_data object | null
      Faqat verification.completed da, manzilda include_document_data: true boʻlsa — shakli ?include=document_data bilan olingan document.data bilan bir xil. Har bir yuborish urinishi shifrlangan ombordan auditga yoziladigan oʻqish hisoblanadi (sabab webhook_delivery).
    • document_data_status string
      document_data bilan birga keladi. not_stored — saqlash muddati tugagan, arizachi oʻchirilgan yoki hech narsa saqlanmagan; not_applicable — faqat yoshni tekshirish rejimi yoki hujjat yoʻq. 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": []
    }
}

Javoblar

2XX Istalgan 2xx bilan tasdiqlang.
post verification.reviewed

Tekshiruvchi qaror qildi

ON_HOLD tekshiruv boʻyicha xodim yoki API orqali qaror qilindi — yoki review_deadline_at oʻtgani uchun tizim uni bekor qildi: bunda decision: RED, decision_type: retry, reject_labels: [REVIEW_EXPIRED] (kutilayotgan toʻrt koʻz taklifi bekor qilinadi).

Parametrlar

  • KYC-Signature string header majburiy
    t=<unix seconds>,v1=<hex>, bunda v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). HMAC ni xom tana boʻyicha tekshiring va ±5 daqiqadan eski t ni rad eting. 2xx boʻlmagan javoblarda qayta urinish 1 min, 5 min, 30 min, 2 h, 6 h va 24 h dan keyin boʻladi; barcha urinishlar muvaffaqiyatsiz boʻlsa, manzil keyingi muvaffaqiyatli yuborishgacha failing deb belgilanadi.

Soʻrov tanasi Event + object

  • id string majburiy
  • type EventType majburiy
  • created_at string (date-time) majburiy
  • env Environment majburiy
  • data object majburiy
    • applicant_id string majburiy
    • external_id string majburiy
    • verification_id string majburiy
    • decision Decision majburiy
    • decision_type DecisionType majburiy
      RED uchun — retry (arizachi reset dan keyin qayta urinishi mumkin) yoki final.
    • reject_labels RejectLabel[] majburiy
    • document_data object | null
      Faqat verification.completed da, manzilda include_document_data: true boʻlsa — shakli ?include=document_data bilan olingan document.data bilan bir xil. Har bir yuborish urinishi shifrlangan ombordan auditga yoziladigan oʻqish hisoblanadi (sabab webhook_delivery).
    • document_data_status string
      document_data bilan birga keladi. not_stored — saqlash muddati tugagan, arizachi oʻchirilgan yoki hech narsa saqlanmagan; not_applicable — faqat yoshni tekshirish rejimi yoki hujjat yoʻq. 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": []
    }
}

Javoblar

2XX Istalgan 2xx bilan tasdiqlang.
post verification.review_reminder

Qoʻlda koʻrib chiqish muddati eslatmasi

ON_HOLD tekshiruv uchun u kutishga qoʻyilishi bilan darhol, 2 kun qolganda va 24 soat qolganda yuboriladi (har bir bosqich koʻpi bilan bir marta; har soatda tekshiriladi). review_deadline_at dan keyin tekshiruv bekor qilinadi (REVIEW_EXPIRED bilan verification.reviewed).

Parametrlar

  • KYC-Signature string header majburiy
    t=<unix seconds>,v1=<hex>, bunda v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). HMAC ni xom tana boʻyicha tekshiring va ±5 daqiqadan eski t ni rad eting. 2xx boʻlmagan javoblarda qayta urinish 1 min, 5 min, 30 min, 2 h, 6 h va 24 h dan keyin boʻladi; barcha urinishlar muvaffaqiyatsiz boʻlsa, manzil keyingi muvaffaqiyatli yuborishgacha failing deb belgilanadi.

Soʻrov tanasi Event + object

  • id string majburiy
  • type EventType majburiy
  • created_at string (date-time) majburiy
  • env Environment majburiy
  • data object majburiy
    • verification_id string majburiy
    • applicant_id string majburiy
    • review_deadline_at string (date-time) majburiy
    • hours_left integer majburiy
{
    "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
    }
}

Javoblar

2XX Istalgan 2xx bilan tasdiqlang.
post certificate.issued

Dalolatnoma berildi

Imzolangan dalolatnoma (yoki qayta koʻrib chiqishdan keyin yangi versiyasi) berildi — yakuniy qarordan taxminan 5 daqiqa keyin. Uni certificate_url / pdf_url va API kalitingiz bilan yuklab oling. include_document_data: true boʻlsa, hodisada certificate (imzolangan hujjat), pdf_base64 va certificate_status (included · not_stored) ham boʻladi.

Parametrlar

  • KYC-Signature string header majburiy
    t=<unix seconds>,v1=<hex>, bunda v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). HMAC ni xom tana boʻyicha tekshiring va ±5 daqiqadan eski t ni rad eting. 2xx boʻlmagan javoblarda qayta urinish 1 min, 5 min, 30 min, 2 h, 6 h va 24 h dan keyin boʻladi; barcha urinishlar muvaffaqiyatsiz boʻlsa, manzil keyingi muvaffaqiyatli yuborishgacha failing deb belgilanadi.

Soʻrov tanasi Event + object

  • id string majburiy
  • type EventType majburiy
  • created_at string (date-time) majburiy
  • env Environment majburiy
  • data object majburiy
    • certificate_id string majburiy
    • version integer majburiy
    • verification_id string majburiy
    • applicant_id string majburiy
    • external_id string | null
    • decision string majburiy
      GREEN RED
    • issued_at string (date-time) majburiy
    • valid_until string (date-time) | null
    • supersedes string | null
    • verify_url string (uri) majburiy
    • certificate_url string (uri) majburiy
    • pdf_url string (uri) majburiy
    • 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"
    }
}

Javoblar

2XX Istalgan 2xx bilan tasdiqlang.
post applicant.reverification_due

Qayta tekshiruv vaqti keldi

GREEN tekshiruv 2 yil amal qiladi (valid_until). 30 kun qolganda bir marta (stage: due_soon) va muddat tugaganda bir marta (stage: expired) yuboriladi; har kuni, faqat arizachining oxirgi tekshiruvi uchun tekshiriladi.

Parametrlar

  • KYC-Signature string header majburiy
    t=<unix seconds>,v1=<hex>, bunda v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). HMAC ni xom tana boʻyicha tekshiring va ±5 daqiqadan eski t ni rad eting. 2xx boʻlmagan javoblarda qayta urinish 1 min, 5 min, 30 min, 2 h, 6 h va 24 h dan keyin boʻladi; barcha urinishlar muvaffaqiyatsiz boʻlsa, manzil keyingi muvaffaqiyatli yuborishgacha failing deb belgilanadi.

Soʻrov tanasi Event + object

  • id string majburiy
  • type EventType majburiy
  • created_at string (date-time) majburiy
  • env Environment majburiy
  • data object majburiy
    • applicant_id string majburiy
    • verification_id string majburiy
    • valid_until string (date-time) majburiy
    • stage string majburiy
      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"
    }
}

Javoblar

2XX Istalgan 2xx bilan tasdiqlang.
post applicant.reset

Arizachi qayta ochildi

Parametrlar

  • KYC-Signature string header majburiy
    t=<unix seconds>,v1=<hex>, bunda v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). HMAC ni xom tana boʻyicha tekshiring va ±5 daqiqadan eski t ni rad eting. 2xx boʻlmagan javoblarda qayta urinish 1 min, 5 min, 30 min, 2 h, 6 h va 24 h dan keyin boʻladi; barcha urinishlar muvaffaqiyatsiz boʻlsa, manzil keyingi muvaffaqiyatli yuborishgacha failing deb belgilanadi.

Soʻrov tanasi Event + object

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

Javoblar

2XX Istalgan 2xx bilan tasdiqlang.
post applicant.deleted

Arizachi oʻchirildi

data.external_id — asl qiymat (anonimlashtirishdan oldingi).

Parametrlar

  • KYC-Signature string header majburiy
    t=<unix seconds>,v1=<hex>, bunda v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). HMAC ni xom tana boʻyicha tekshiring va ±5 daqiqadan eski t ni rad eting. 2xx boʻlmagan javoblarda qayta urinish 1 min, 5 min, 30 min, 2 h, 6 h va 24 h dan keyin boʻladi; barcha urinishlar muvaffaqiyatsiz boʻlsa, manzil keyingi muvaffaqiyatli yuborishgacha failing deb belgilanadi.

Soʻrov tanasi Event + object

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

Javoblar

2XX Istalgan 2xx bilan tasdiqlang.
post aml.match

Doimiy monitoringda moslik topildi

Doimiy AML monitoringi uchun ajratilgan (hozircha yuborilmaydi).

Parametrlar

  • KYC-Signature string header majburiy
    t=<unix seconds>,v1=<hex>, bunda v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). HMAC ni xom tana boʻyicha tekshiring va ±5 daqiqadan eski t ni rad eting. 2xx boʻlmagan javoblarda qayta urinish 1 min, 5 min, 30 min, 2 h, 6 h va 24 h dan keyin boʻladi; barcha urinishlar muvaffaqiyatsiz boʻlsa, manzil keyingi muvaffaqiyatli yuborishgacha failing deb belgilanadi.

Soʻrov tanasi Event + object

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

Javoblar

2XX Istalgan 2xx bilan tasdiqlang.
post webhook.test

Sinov hodisasi

POST /webhooks/{id}/test orqali yuboriladi.

Parametrlar

  • KYC-Signature string header majburiy
    t=<unix seconds>,v1=<hex>, bunda v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). HMAC ni xom tana boʻyicha tekshiring va ±5 daqiqadan eski t ni rad eting. 2xx boʻlmagan javoblarda qayta urinish 1 min, 5 min, 30 min, 2 h, 6 h va 24 h dan keyin boʻladi; barcha urinishlar muvaffaqiyatsiz boʻlsa, manzil keyingi muvaffaqiyatli yuborishgacha failing deb belgilanadi.

Soʻrov tanasi Event + object

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

Javoblar

2XX Istalgan 2xx bilan tasdiqlang.

Modellar

Error

object
  • error object majburiy
    • code ErrorCode majburiy
      400 bad_request, validation_failed · 401 unauthenticated · 403 forbidden · 404 not_found · 409 conflict, idempotency_conflict · 413 file_too_large (soʻrov tanasi server limitidan katta) · 422 unprocessable · 429 rate_limited, plan_limit_reached · 5xx internal_error, aml_unavailable.
    • message string majburiy
    • fields object
      Maydon → xabarlar roʻyxati (faqat tekshiruv xatolarida).
    • request_id string majburiy

ErrorCode

string

400 bad_request, validation_failed · 401 unauthenticated · 403 forbidden · 404 not_found · 409 conflict, idempotency_conflict · 413 file_too_large (soʻrov tanasi server limitidan katta) · 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 — yangi, reset dan keyin yoki RED retry dan keyin; pending ajratilgan va hozircha hech qachon qoʻyilmaydi.

init pending on_hold completed

Decision

string
GREEN RED ON_HOLD

DecisionType

string | null

RED uchun — retry (arizachi reset dan keyin qayta urinishi mumkin) yoki final.

final retry

RejectLabel

string

Sabab kodi (rad etish belgilari jadvaliga qarang). DOC_RECAPTURE (RED retry) faqat operator uni yoqqanda. AGE_UNKNOWN (koʻrib chiqish → ON_HOLD) faqat yoshni tekshiradigan senariylarda (checks.age_only). PERSONAL_NUMBER_INVALID va DOC_REVIEW_REQUIRED — koʻrib chiqish belgilari (→ ON_HOLD). Hujjat maʼlumotlarini oʻqish: MRZ_NOT_READABLE (retry) — maʼlumotlarni ishonchli oʻqib boʻlmadi, yangi surat soʻrang; MRZ_INVALID — yuborilgan hujjat maʼlumotlari yoki sanalari notoʻgʻri; MRZ_LOW_CONFIDENCE (→ ON_HOLD) — maʼlumotlar past ishonch bilan oʻqildi; DOC_DATA_MISMATCH — hujjat maʼlumotlari bir-biriga mos emas. Hujjatning elektron tekshiruvi (senariydagi documents.nfc, faqat mobil SDK): CHIP_HASH_MISMATCH, CHIP_SIGNATURE_INVALID, CHIP_MRZ_MISMATCH — final RED; CHIP_CHAIN_UNVERIFIED, CHIP_CLONE_SUSPECTED, CHIP_NOT_READ — koʻrib chiqish belgilari (→ ON_HOLD). Hujjat haqiqiyligini tekshirish (doc_fraud): DOC_SCREEN_RECAPTURE, DOC_PRINTED_COPY, DOC_PHOTO_TAMPERED, DOC_TEMPLATE_MISMATCH — hujjat rasmi haqiqiylik tekshiruvidan oʻtmadi; bular koʻrib chiqish belgilari (→ ON_HOLD). REVIEW_EXPIRED (RED retry) ni faqat tizim qoʻyadi — ON_HOLD tekshiruv review_deadline_at gacha koʻrib chiqilmagan boʻlsa; uni qoʻlda koʻrib chiqishda tanlab boʻlmaydi.

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 va visa 2026-11-08 da qoʻshildi; faqat eski turlarni (id_card, passport, ru_internal_passport) sanab, ular orasida id_card boʻlgan senariy residence_permit ni ham qabul qiladi (avval id_card deb koʻrsatilardi). driving_licence ajratilgan (hozircha avtomatik oʻqilmaydi).

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 majburiy
  • version integer | null majburiy
  • status string majburiy
    current superseded revoked invalid_signature unknown
  • signature_valid boolean majburiy
  • valid boolean majburiy
    joriy + GREEN + muddati oʻtmagan
  • decision string | null majburiy
    GREEN RED
  • outcome string | null
  • issued_at string (date-time) | null majburiy
  • valid_until string (date-time) | null majburiy
  • expired boolean majburiy
  • superseded_by string | null majburiy
  • verify_url string (uri) | null majburiy

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 majburiy
    Sizdagi foydalanuvchi ID si; bosma ASCII, har bir muhitda yagona.
  • flow string
  • locale Locale
  • purpose string | null
    Shu arizachi sessiyalari uchun tekshiruvning sukut boʻyicha maqsadi.
  • metadata object
    Shaxsiy maʼlumot boʻlmagan kalit/qiymat satrlari, JSON koʻrinishida ≤ 2 KB.
  • email —
    Hozircha rad etiladi: boʻsh boʻlmagan qiymat → 400 validation_failed (fields.email). Saqlanmaydi va qaytarilmaydi (aloqa maʼlumotlarini shifrlab saqlash keyingi bosqichda).
  • phone —
    Hozircha rad etiladi: boʻsh boʻlmagan qiymat → 400 validation_failed (fields.phone). Saqlanmaydi va qaytarilmaydi.

Applicant

object
  • id string majburiy
  • external_id string majburiy
  • flow string majburiy
  • locale Locale majburiy
  • status ApplicantStatus majburiy
    init — yangi, reset dan keyin yoki RED retry dan keyin; pending ajratilgan va hozircha hech qachon qoʻyilmaydi.
  • decision Decision | null majburiy
  • risk_score number | null majburiy
  • last_verification_id string | null majburiy
  • metadata object majburiy
  • purpose string | null
  • valid_until string (date-time) | null
    Oxirgi tekshiruvning amal qilish muddati (faqat GREEN, qaror + 2 yil).
  • created_at string (date-time) majburiy
  • updated_at string (date-time) majburiy
  • identity object | null
    Faqat ?include=identity bilan. Arizachida GREEN tekshiruv boʻlmasa null.
    • verification_id string majburiy
    • verified_at string (date-time) majburiy
    • document object | null majburiy
      • type string majburiy
      • country string | null majburiy
      • data DocumentData | null majburiy

Session

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

ContractBinding

object

Tekshiruvni mijoz bilan tuzgan shartnomangizga bogʻlaydi. Faqat xesh saqlanadi; u imzolangan dalolatnomaga kiritiladi.

  • reference string | null
    Shartnomangiz raqami.
  • sha256 string majburiy
    Shartnoma faylining SHA-256 qiymati (hex; kichik harflarda qaytariladi).

SignedCertificate

object
  • certificate object majburiy
    Imzolangan maydonlar (toʻliq misol API.md §3.3 da). Qiymatsiz kalitlar tushirib qoldiriladi, consent bundan mustasno.
    • schema "goxost-kyc/certificate@1" majburiy
    • id string majburiy
    • version integer majburiy
    • issued_at string (date-time) majburiy
    • verify_url string (uri) majburiy
    • issuer object majburiy
    • requester object majburiy
      • tenant_id string majburiy
      • name string majburiy
        Biznes profilidagi yuridik nom, u boʻlmasa kompaniya nomi.
      • project string
      • website string
    • purpose string
    • subject object majburiy
      applicant_id, external_id, full_name, birth_date va document {type, country, number_masked}.
    • verification object majburiy
    • checks object[] majburiy
    • images object[] majburiy
      • kind string
      • sha256 string
    • valid_until string (date-time)
    • contract ContractBinding
      Tekshiruvni mijoz bilan tuzgan shartnomangizga bogʻlaydi. Faqat xesh saqlanadi; u imzolangan dalolatnomaga kiritiladi.
    • consent object | null majburiy
      Rozilik dalili (sinov rejimida ham). Doim bor; rozilik yozib olinmagan boʻlsa null (eski tekshiruvlar). IP va user agent faqat dalolatnomada koʻrinadi — GET /verifications/{id}, webhooklar yoki ochiq /verify sahifasida hech qachon. Sxema goxost-kyc/certificate@1 boʻlib qoladi.
      • text_version string majburiy
      • given_at string (date-time) majburiy
      • biometric boolean majburiy
        Biometrik (yuz) maʼlumotlarini qayta ishlashga rozilik.
      • ip string | null majburiy
        Rozilik berilgan IPv4 yoki IPv6 manzil.
      • ip_country string | null majburiy
      • device string | null majburiy
        User agent ning qisqacha tavsifi.
      • user_agent string | null majburiy
  • signature object majburiy
    • kid string majburiy
    • value string majburiy
      certificate ning elektron imzosi. Uni faqat GOXOST KYC tekshiradi.
  • meta object majburiy
    Imzolanmagan.
    • status string
      current superseded
    • superseded_by string | null

Check

object
  • name string majburiy
  • status string majburiy
    pass warn fail error
  • score number | null majburiy
  • labels RejectLabel[] majburiy
  • details object
    Faqat baʼzi tekshiruvlarda bor (aml → lists va moslik topilsa matches; duplicate → applicant_ids, age → age_over). Shaxsiy maʼlumot yoʻq.
    • lists string[]
      Shu aml tekshiruvi amalda tekshirgan sanksiyalar roʻyxatlari. Ixtiyoriy roʻyxat (EU) yoʻq yoki eskirgan boʻlsa, u koʻrsatilmaydi.
    • matches AmlMatch[]
    • applicant_ids string[]
      Biznesingizdagi hujjat raqami bir xil boʻlgan boshqa arizachilar (eng eskisi birinchi). Sinov rejimida qaytarilmaydi.
    • age_over object
      Faqat yoshni tekshiradigan senariylar (checks.age_only). Tugʻilgan sananing oʻzi hech qachon qaytarilmaydi.
      • threshold integer majburiy
        Senariyning min_age qiymati.
      • result boolean | null majburiy
        true — kamida threshold yoshda, false — yoshroq (UNDERAGE), null — tugʻilgan sana nomaʼlum (AGE_UNKNOWN).

Verification

object
  • id string majburiy
  • applicant_id string majburiy
  • session_id string majburiy
  • decision Decision majburiy
  • decision_type DecisionType majburiy
    RED uchun — retry (arizachi reset dan keyin qayta urinishi mumkin) yoki final.
  • reject_labels RejectLabel[] majburiy
  • risk_score number | null majburiy
  • checks Check[] majburiy
  • document object | null majburiy
    • type string majburiy
      DocumentType yoki unknown.
    • country string | null majburiy
      ISO 3166-1 alpha-3.
    • data DocumentData | null majburiy
      Shifrdan ochilgan hujjat maydonlari (shaxsiy maʼlumot). Qachon mavjudligini amal tavsifidan koʻring. Faqat yoshni tekshiradigan senariylarda doim null.
  • summary object
    Tekshiruv ballarining shaxsiy maʼlumotsiz qisqa xulosasi. Tekshiruv bajarilmagan boʻlsa, uning kaliti null.
    • 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
    Faqat GREEN: qaror vaqti + 2 yil. Undan oldin qayta tekshiring (applicant.reverification_due).
  • purpose string | null
  • contract ContractBinding | null
  • review_deadline_at string (date-time) | null
    Faqat ON_HOLD: shu vaqtgacha koʻrib chiqing (ON_HOLD + 7 kun), aks holda tekshiruv bekor qilinadi (RED REVIEW_EXPIRED). Avtomatik qarorlarda null.
  • reviewed_by integer | null majburiy
    Tekshiruvchining paneldagi foydalanuvchi ID si; avtomatik qarorlar, API orqali koʻrib chiqish va tizim bekor qilganda null.
  • reviewed_at string (date-time) | null majburiy
  • created_at string (date-time) majburiy
  • completed_at string (date-time) | null majburiy
    ON_HOLD paytida null.

VaultReadReason

string

Shifrlangan ombordan oʻqishning auditga yoziladigan sababi (sukut boʻyicha api_request). Notanish qiymat → 400 validation_failed.

panel_view manual_review customer_request compliance_audit legal_request api_request

DocumentData

object

Hujjatdan oʻqilgan maydonlar (shaxsiy maʼlumot). Vaqt oʻtishi bilan faqat yangi kalitlar qoʻshiladi, hech qachon olib tashlanmaydi; oʻqilmagan maydon null. Shifrlangan ombordagi eski yozuvlarda yangi kalitlar null. Misol qiymatlar sintetik "Utopia" namuna hujjatidan olingan.

  • first_name string | null
  • last_name string | null
  • middle_name string | null
    Otasining ismi (RU ichki pasportida patronymic ham saqlanadi).
  • 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
    Hujjatda yozilgan hujjat turi kodi.
  • issuing_country string | null
  • number string | null
  • personal_number string | null
  • personal_number_type string | null
  • personal_number_valid boolean | null
    Milliy nazorat raqami algoritmi natijasi; tekshiruvchi boʻlmasa null.
  • issue_date string (date) | null
  • expiry_date string (date) | null
  • issuing_authority string | null
  • address string | null
    Hozircha hech qaysi hujjatdan oʻqilmaydi; fields.address.status ga qarang.
  • series string
    Faqat RU ichki pasporti.
  • division_code string
    Faqat RU ichki pasporti.
  • age integer | null
    Oʻqish paytida hisoblanadi (UTC boʻyicha bugun).
  • is_expired boolean | null
  • days_to_expiry integer | null
    Muddati oʻtgan boʻlsa manfiy.
  • names object | null
    • mrz object | null
      Hujjatdan oʻqilgan lotincha ismlar.
    • viz object | null
      Asosiy oʻqish imkoni boʻlmaganda zaxira oʻqishdan olingan ismlar.
    • native object | null
      Asl yozuvda (RU ichki pasporti — kirill).
  • fields object | null
    Har bir maydon uchun. Oʻqilgan har bir maydon, shuningdek middle_name, issue_date, place_of_birth, issuing_authority, address, native_name va personal_number — qiymati null boʻlsa ham (status bilan). Holat qarorga hech qachon taʼsir qilmaydi.

ReviewRequest

object
  • decision string majburiy
    GREEN RED
  • decision_type string
    RED uchun majburiy, GREEN uchun taqiqlangan. final retry
  • reject_labels RejectLabel[]
    RED uchun majburiy, GREEN uchun taqiqlangan.
  • comment string
    Saqlanmaydi.

MediaItem

object
  • kind string majburiy
    Rasmda nima tasvirlangani. document_front document_back document_face selfie_face liveness_frame
  • content_type string majburiy
  • bytes integer majburiy
  • sha256 string | null
    Rasm baytlarining SHA-256 qiymati (2026-11-08 dan oldin saqlangan obyektlar uchun null).
  • url string (uri) majburiy
  • expires_at string (date-time) majburiy
    Imzolangan URL shu vaqtda eskiradi.
  • stored_until string (date-time) | null
    Rasmning oʻzi shu vaqtda oʻchiriladi (qayta ishlangandan 7 kun keyin).

AmlMatch

object
  • list string majburiy
    OFAC_SDN UN UK EU
  • entry_id string majburiy
    Roʻyxat manbasi saytida yozuvni shu ID boʻyicha oching (roʻyxatdagi ism qaytarilmaydi).
  • score number majburiy
  • matched_on string[] majburiy

AmlScreenResult

object
  • result string majburiy
    possible qoʻlda koʻrib chiqishni talab qiladi; match = ism + aniq tugʻilgan sana. clear possible match
  • labels string[] majburiy
  • matches AmlMatch[] majburiy
  • lists object[] majburiy
    Shu qidiruvda ishlatilgan roʻyxatlar versiyalari (EU kabi ixtiyoriy roʻyxat yoʻq yoki eskirgan boʻlsa, koʻrsatilmaydi).
    • list string majburiy
    • version string majburiy
      Manba fayl sha256 qiymatining boshlangʻich qismi.
    • entries integer majburiy
    • updated_at string (date-time) majburiy

Flow

object
  • key string majburiy
  • name string majburiy
  • version integer majburiy
  • steps string[] majburiy
  • documents object majburiy
    • allowed_countries string[]
      Hujjatda yozilgan, hujjat bergan davlat kodlari (1–3 harf, masalan UZB, Germaniya = D) yoki ["*"] = istalgani.
    • types DocumentType[]
    • nfc string
      Mobil SDK da hujjatning elektron tekshiruvi (chip tekshiruvi). Veb senariyda mavjud emas. off optional required
    • nfc_fallback string
      required, lekin hujjatning elektron tekshiruvi oʻtkazilmadi (masalan, veb senariy): hold → CHIP_NOT_READ (ON_HOLD); block → topshirish 409 nfc_required bilan javob beradi. hold block
  • min_age integer majburiy
  • checks object majburiy
    • aml boolean
    • duplicate boolean
    • age_only boolean
      Faqat arizachi kamida min_age yoshda ekanini tasdiqlash (age tekshiruvi); hujjat maʼlumotlari qaytarilmaydi va saqlanmaydi. Hech qachon aml yoki duplicate bilan birga ishlatilmaydi.
  • retention object majburiy
    • mode string
      standard (yangi bizneslar uchun sukut boʻyicha) — rasmlar 7 kun + matn ttl muddatiga; none — matn saqlanmaydi, rasmlar faqat ON_HOLD uchun (7 kun). compact — eski qiymat, standard deb qabul qilinadi. standard none compact
    • ttl string | null
      standard/compact uchun matnli maʼlumotlar muddati (1y yoki 5y, sukut boʻyicha 5y; 24h/30d faqat eski), none uchun null. 24h 30d 1y 5y
  • max_attempts integer majburiy
    Faqat maʼlumot uchun — hozircha qoʻllanmaydi (MAX_ATTEMPTS hech qachon yuborilmaydi).

WebhookInput

object
  • url string (uri)
  • events EventType | "*"[]
  • is_active boolean
  • include_document_data boolean
    Ixtiyoriy: verification.completed ga hujjatdan olingan shaxsiy maʼlumotlarni qoʻshish. Sukut boʻyicha oʻchiq.

Webhook

object
  • id string majburiy
  • url string (uri) majburiy
  • events string[] majburiy
  • include_document_data boolean majburiy
  • is_active boolean majburiy
  • status string majburiy
    failing — oxirgi yuborish barcha qayta urinishlardan keyin ham muvaffaqiyatsiz boʻldi. ok failing
  • created_at string (date-time) majburiy

DeliveryStatus

string
pending delivered failed

WebhookDelivery

object
  • id string majburiy
  • event_id string majburiy
  • event EventType majburiy
  • status DeliveryStatus majburiy
  • attempt integer majburiy
  • status_code integer | null majburiy
    Manzilingiz qaytargan HTTP holati.
  • next_retry_at string (date-time) | null majburiy
  • delivered_at string (date-time) | null majburiy
  • created_at string (date-time) majburiy

Event

object

Webhook maʼlumotlari konverti. Shaxsiy maʼlumot yoʻq; tafsilotlarni API orqali oling.

  • id string majburiy
  • type EventType majburiy
  • created_at string (date-time) majburiy
  • env Environment majburiy
  • data object majburiy
    type ga bogʻliq: - applicant.created, applicant.reset, applicant.deleted — {applicant_id, external_id} (deleted uchun asl external_id; saqlangan maʼlumot yoʻq qilinishidan oldin yuboriladi). - 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}. Yuborish: birinchi urinish + 6 ta qayta urinish (1 min, 5 min, 30 min, 2 h, 6 h, 24 h), kutish vaqti 10 s.