Skip to content
API reference Get API keys

Getting started · Chapter 1

Overview

GOXOST KYC verifies that your user is a real person holding a genuine identity document, and tells your backend whether to let them in.

4 min read

What GOXOST KYC does

Your user photographs an identity document and takes a short selfie. GOXOST KYC then:

  • reads the document data and checks that the document is genuine, valid and not expired;
  • checks that a real person is taking part (presence check);
  • compares the selfie with the photo on the document (selfie-to-document match);
  • optionally screens the name against sanctions lists (OFAC SDN, UN, UK, EU) and looks for duplicate documents within your account.

Every verification ends with one decision:

Decision Meaning What you do
GREEN All checks passed Let the user in
RED A check failed. decision_type says whether the user may try again (retry) or not (final) Explain the reason, offer a retry if allowed
ON_HOLD The result is borderline and needs a person to decide Wait for manual review in the panel or decide via the API

RED and ON_HOLD always come with machine-readable reject_labels such as DOC_EXPIRED or FACE_MISMATCH. See Verification flow for the full list.

How an integration works

  1. Your backend creates an applicant — the person being verified, linked to your user ID (external_id).
  2. Your backend creates a session for that applicant and gets back a one-time url and a token.
  3. The user completes the flow — you send them to the url (hosted page), or start the web embed (kyc.js) or the Flutter SDK with the token.
  4. GOXOST KYC sends a webhook (verification.completed or verification.on_hold) to your backend.
  5. Your backend reads the decision with GET /verifications/{id} and updates your user.
Your backend ──POST /applicants──────────────▶ GOXOST KYC   → apl_…
Your backend ──POST /applicants/{id}/sessions▶ GOXOST KYC   → { url, token }
User         ──opens url / SDK with token────▶ hosted flow   (document + selfie)
GOXOST KYC   ──webhook verification.completed▶ Your backend
Your backend ──GET /verifications/{id}────────▶ GOXOST KYC   → decision, checks, document data
Important

The result shown in the browser or app is for the user experience only — a browser message can be faked. Always take the final decision on your backend, from the webhook or from GET /verifications/{id}.

The secret API key stays on your server. The browser or app only ever receives the short-lived session url or token.

Integration options

All options use the same backend API and the same webhooks; they differ in where the user goes through the flow.

Option Best for What you build Chapter
Hosted link The fastest start; links in email, SMS, chat or a QR code Only the backend calls. Redirect the user to url Verification flow
Web embed (kyc.js) Keeping the user on your website A container element and one script tag Web SDK
Flutter SDK Android and iOS apps; adds the electronic document check One KycFlow.start call Flutter
WordPress plugin WordPress sites Install and configure the plugin WordPress
Direct API Your own capture UI or server-side checks of images you already have Everything: capture, UX, decision logic Direct API

The Direct API is stateless: it checks the images you send and returns the result in the response. It does not create applicants, store anything or send webhooks.

Environments

Sandbox Live
API key sk_test_… sk_live_…
Checks Mocked — you choose the result Real document, selfie and presence checks
Monthly limit Not limited (still counted) Your plan limit
Available Right after sign-up After business verification

Both environments use the same base URL; the key decides the environment. Data never crosses between them: a sandbox key cannot see live applicants, and the same external_id in sandbox and live is two different applicants. See Sandbox and live.

Base URL and conventions

https://kyc.goxost.net/api/v1
  • JSON over HTTPS, UTF-8. Times are ISO 8601 in UTC (2026-11-09T10:00:00Z). Scores are numbers from 0 to 1.
  • Authenticate every request with Authorization: Bearer sk_test_… or sk_live_… — see Authentication.
  • IDs have a type prefix: apl_ applicant, ses_ session, ver_ verification, whk_ webhook, whd_ webhook delivery, evt_ event.
  • Every response has an X-Request-Id: req_… header. Include it when you contact support.
  1. Quickstart — your first verification in sandbox in five steps.
  2. Authentication — API keys, session tokens and idempotency.
  3. Verification flow — applicants, sessions, decisions and manual review.
  4. Webhooks — events, signatures and retries.
  5. Errors — error codes, rate limits and safe retries.
  6. API reference — every endpoint and field. The raw schema is at /docs/openapi.yaml and a Postman collection at /docs/postman.json.

Contents