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
- Your backend creates an applicant — the person being verified, linked to your user ID (
external_id). - Your backend creates a session for that applicant and gets back a one-time
urland atoken. - 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 thetoken. - GOXOST KYC sends a webhook (
verification.completedorverification.on_hold) to your backend. - 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
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 from0to1. - Authenticate every request with
Authorization: Bearer sk_test_…orsk_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.
What to read next
- Quickstart — your first verification in sandbox in five steps.
- Authentication — API keys, session tokens and idempotency.
- Verification flow — applicants, sessions, decisions and manual review.
- Webhooks — events, signatures and retries.
- Errors — error codes, rate limits and safe retries.
- API reference — every endpoint and field. The raw schema is at /docs/openapi.yaml and a Postman collection at /docs/postman.json.