When to use it
Most integrations should use the verification flow: the hosted page, kyc.js or the Flutter SDK take the photos, run the full presence check, store the result, send webhooks and issue a certificate. Use the Direct API only when you already capture images yourself and need individual checks.
| Verification flow | Direct API | |
|---|---|---|
| Who takes the photos | GOXOST KYC page or SDK | Your app or website |
| Presence check | Full, during the selfie step | Basic, one image |
| Applicant, verification, history | Yes | No — nothing is created |
| Data stored | By your retention settings | Nothing; data is only in the response |
| Webhooks, review queue, certificate | Yes | No |
| Sanctions screening | Flow option | Separate call: POST /aml/screen |
Direct API calls use your secret key. Call them only from your server — never from a browser or a mobile app. Your app sends images to your server; your server calls the Direct API.
Base URL and authentication
Direct API requests go to the checking service directly, not to /api/v1. Read its address from core_url in GET /usage and keep it in your configuration:
curl https://kyc.goxost.net/api/v1/usage -H "Authorization: Bearer sk_test_…"
{ "period": "2026-11", "plan": "free", "limit": 100,
"live": { "verifications": 124, "aml_checks": 124, "direct_checks": 40 },
"sandbox": { "verifications": 51, "aml_checks": 12, "direct_checks": 7 },
"core_url": "https://kyc-core.9k.uz/v1" }
Authenticate with the same header: Authorization: Bearer sk_test_… or sk_live_…. Requests are multipart/form-data.
Endpoints
| Endpoint | Fields | Returns |
|---|---|---|
POST {core_url}/checks/document |
front (file), back (file, optional), country (ISO alpha-3, optional), type (id_card, passport, residence_permit, ru_internal_passport, visa; optional), age_only (bool, optional), min_age (integer, optional) |
document (type, country, data) or null, and checks |
POST {core_url}/checks/face-match |
image_a, image_b (files) |
score, status, labels |
POST {core_url}/checks/liveness |
image (file) |
score, status, labels |
Files: JPEG, PNG or WebP (detected by content; HEIC is not accepted), up to 15 MB each, the whole request up to 32 MB.
Flow of calls
A typical check of a person with your own UI:
- Your app captures the document (front, and back for ID cards) and a selfie, and uploads them to your server.
- Your server calls
POST /checks/documentwithfrontandback. Readdocument.data(name, number, dates) and thechecksstatuses. - Your server calls
POST /checks/face-matchwith the document photo asimage_aand the selfie asimage_b. - Optionally,
POST /checks/livenesswith the selfie for a basic presence check. - Optionally, screen the name with
POST /aml/screen. - Your server combines the statuses into its own decision and stores what it needs — GOXOST KYC keeps nothing.
curl https://kyc-core.9k.uz/v1/checks/document \
-H "Authorization: Bearer sk_test_…" \
-F front=@passport.jpg \
-F type=passport
curl https://kyc-core.9k.uz/v1/checks/face-match \
-H "Authorization: Bearer sk_test_…" \
-F image_a=@passport.jpg \
-F image_b=@selfie.jpg
$coreUrl = getenv('KYC_CORE_URL'); // core_url from GET /usage
$client = new GuzzleHttp\Client();
$auth = ['Authorization' => 'Bearer ' . getenv('KYC_SECRET_KEY')];
$document = json_decode((string) $client->post("$coreUrl/checks/document", [
'headers' => $auth,
'multipart' => [
['name' => 'front', 'contents' => fopen('passport.jpg', 'r')],
['name' => 'type', 'contents' => 'passport'],
],
])->getBody(), true);
$face = json_decode((string) $client->post("$coreUrl/checks/face-match", [
'headers' => $auth,
'multipart' => [
['name' => 'image_a', 'contents' => fopen('passport.jpg', 'r')],
['name' => 'image_b', 'contents' => fopen('selfie.jpg', 'r')],
],
])->getBody(), true);
// Node.js 20+
import { openAsBlob } from 'node:fs';
const coreUrl = process.env.KYC_CORE_URL; // core_url from GET /usage
const auth = { Authorization: `Bearer ${process.env.KYC_SECRET_KEY}` };
const docForm = new FormData();
docForm.append('front', await openAsBlob('passport.jpg'), 'passport.jpg');
docForm.append('type', 'passport');
const document = await (await fetch(`${coreUrl}/checks/document`, { method: 'POST', headers: auth, body: docForm })).json();
const faceForm = new FormData();
faceForm.append('image_a', await openAsBlob('passport.jpg'), 'passport.jpg');
faceForm.append('image_b', await openAsBlob('selfie.jpg'), 'selfie.jpg');
const face = await (await fetch(`${coreUrl}/checks/face-match`, { method: 'POST', headers: auth, body: faceForm })).json();
import os, requests
core_url = os.environ["KYC_CORE_URL"] # core_url from GET /usage
auth = {"Authorization": f"Bearer {os.environ['KYC_SECRET_KEY']}"}
with open("passport.jpg", "rb") as front:
document = requests.post(f"{core_url}/checks/document", headers=auth,
files={"front": front}, data={"type": "passport"}).json()
with open("passport.jpg", "rb") as a, open("selfie.jpg", "rb") as b:
face = requests.post(f"{core_url}/checks/face-match", headers=auth,
files={"image_a": a, "image_b": b}).json()
Response of /checks/document:
{
"document": {
"type": "passport",
"country": "UTO",
"data": {
"first_name": "ANNA MARIA",
"last_name": "ERIKSSON",
"full_name": "ERIKSSON ANNA MARIA",
"birth_date": "1992-08-12",
"number": "L898902C3",
"expiry_date": "2032-04-15",
"age": 34,
"is_expired": false,
"fields": { "…": "…" },
"mrz": { "…": "…" }
}
},
"checks": [
{ "name": "document", "status": "pass", "score": 1.0, "labels": [], "ms": 410 }
]
}
Response of /checks/face-match and /checks/liveness:
{ "score": 0.93, "status": "pass", "labels": [] }
document.data has the same full schema as in GET /verifications/{id}. status is pass, warn or fail; labels are the reason codes from the errors and labels chapter, for example FACE_MATCH_UNCERTAIN, FACE_MISMATCH, FACE_NOT_FOUND, LIVENESS_UNCERTAIN, DOC_EXPIRED.
Rules and limits
- Basic presence check only. The full presence check needs the selfie step of the hosted flow or SDK.
/checks/livenessworks on one image: an unclear result giveswarn+LIVENESS_UNCERTAIN, never a hardfailby itself. If you need the full presence check, use the verification flow. - Document options. With
country/typeonly those are accepted (others →DOC_NOT_SUPPORTED). For an ID card sendtype=id_cardwithback; when both sides are sent, they are checked for consistency (DOC_DATA_MISMATCHwhen the data disagrees,DOC_FACE_UNBOUNDwhen the sides cannot be confirmed as one document). - Age only.
age_only=truereturnsdocument.data = nulland adds anagecheck withdetails.age_over.min_ageis 18 by default, allowed 18–30. - Document authenticity. When the
documentcheck passes, each side also goes through the document authenticity check. If it raises doubts, you getwarnwith one ofDOC_SCREEN_RECAPTURE,DOC_PRINTED_COPY,DOC_PHOTO_TAMPERED,DOC_TEMPLATE_MISMATCH. - Image size. Document images up to 52 MP, selfie image for
/checks/livenessup to 13 MP, any side up to 12 000 px, long side at most 10× the short one (422 image_too_large). - Rate limits. 120 requests per minute per IP and 60 per minute per key environment (
429 rate_limited). - Usage. Each successful (
200) call counts as onedirect_checksunit, separately from verifications. In live, after the monthly limit →429 plan_limit_reached. Errors are not counted. - Sandbox (
sk_test_…): no real checks; every call returns a mockpass(score 0.99) and the synthetic sample document "ERIKSSON ANNA MARIA". Unlimited, but counted inGET /usage. Idempotency-Keyis not used — the calls have no state.
Errors
Errors use the envelope { "error": { "code": "…", "message": "…" } }.
| HTTP | code |
What to do |
|---|---|---|
| 400 | validation_failed |
A field is missing or wrong (for example min_age out of range) |
| 400 | invalid_file |
Not a JPEG, PNG or WebP image |
| 401 | unauthenticated |
Missing or invalid key |
| 403 | forbidden |
The account is blocked |
| 413 | file_too_large |
The request is larger than 32 MB |
| 422 | image_too_large |
Image resolution or aspect ratio over the limits — resize before sending |
| 429 | rate_limited |
Too many requests — slow down and retry later |
| 429 | plan_limit_reached |
Monthly live limit reached |
| 503 | auth_unavailable |
The key could not be checked right now — retry with backoff |
| 503 | core_unavailable |
The checking service is temporarily unavailable — retry with backoff |
A revoked key or a blocked account stops working within about a minute (10 seconds for live keys).