Skip to content
API reference Get API keys

Integration · Chapter 8

Direct API

Send images from your own server and get the check result back in the same response. For businesses that already have their own capture UI and only need the checks.

6 min read

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
Important

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:

  1. Your app captures the document (front, and back for ID cards) and a selfie, and uploads them to your server.
  2. Your server calls POST /checks/document with front and back. Read document.data (name, number, dates) and the checks statuses.
  3. Your server calls POST /checks/face-match with the document photo as image_a and the selfie as image_b.
  4. Optionally, POST /checks/liveness with the selfie for a basic presence check.
  5. Optionally, screen the name with POST /aml/screen.
  6. 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/liveness works on one image: an unclear result gives warn + LIVENESS_UNCERTAIN, never a hard fail by itself. If you need the full presence check, use the verification flow.
  • Document options. With country/type only those are accepted (others → DOC_NOT_SUPPORTED). For an ID card send type=id_card with back; when both sides are sent, they are checked for consistency (DOC_DATA_MISMATCH when the data disagrees, DOC_FACE_UNBOUND when the sides cannot be confirmed as one document).
  • Age only. age_only=true returns document.data = null and adds an age check with details.age_over. min_age is 18 by default, allowed 18–30.
  • Document authenticity. When the document check passes, each side also goes through the document authenticity check. If it raises doubts, you get warn with one of DOC_SCREEN_RECAPTURE, DOC_PRINTED_COPY, DOC_PHOTO_TAMPERED, DOC_TEMPLATE_MISMATCH.
  • Image size. Document images up to 52 MP, selfie image for /checks/liveness up 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 one direct_checks unit, 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 mock pass (score 0.99) and the synthetic sample document "ERIKSSON ANNA MARIA". Unlimited, but counted in GET /usage.
  • Idempotency-Key is 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).