Skip to content
API reference Get API keys

Getting started · Chapter 2

Quickstart

Run your first verification in sandbox in five steps: get a key, create an applicant, open a session, receive the webhook and read the decision.

5 min read

1. Get a sandbox key

  1. Create an account at /register and sign in to the panel.
  2. Open API keys, choose Create key and select the Sandbox environment.
  3. Copy the key. It starts with sk_test_ and is shown only once — store it in your server's secrets, for example as the KYC_SECRET_KEY environment variable.

Sandbox works right after sign-up. It does not run real checks: you pick the result with the external_id (see Sandbox and live).

Important

The secret key is for your backend only. Never put it in a browser, a mobile app or a public repository.

2. Create an applicant

An applicant is the person you verify. Link it to your own user with external_id (unique per environment).

curl https://kyc.goxost.net/api/v1/applicants \
  -H "Authorization: Bearer $KYC_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "user-8812", "locale": "en"}'
<?php
// composer require guzzlehttp/guzzle
$kyc = new GuzzleHttp\Client([
    'base_uri' => 'https://kyc.goxost.net/api/v1/',
    'headers'  => ['Authorization' => 'Bearer ' . getenv('KYC_SECRET_KEY')],
]);

$applicant = json_decode($kyc->post('applicants', [
    'json' => ['external_id' => 'user-8812', 'locale' => 'en'],
])->getBody(), true);
const KYC = 'https://kyc.goxost.net/api/v1';
const headers = {
  Authorization: `Bearer ${process.env.KYC_SECRET_KEY}`,
  'Content-Type': 'application/json',
};

const applicant = await fetch(`${KYC}/applicants`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ external_id: 'user-8812', locale: 'en' }),
}).then((r) => r.json());
import os
import requests

KYC = "https://kyc.goxost.net/api/v1"
headers = {"Authorization": f"Bearer {os.environ['KYC_SECRET_KEY']}"}

applicant = requests.post(
    f"{KYC}/applicants",
    headers=headers,
    json={"external_id": "user-8812", "locale": "en"},
).json()

Response 201 Created:

{
  "id": "apl_01m6yyj5d7qnxppat520rwg0mb",
  "external_id": "user-8812",
  "flow": "basic-kyc",
  "locale": "en",
  "status": "init",
  "decision": null,
  "risk_score": null,
  "last_verification_id": null,
  "metadata": {},
  "purpose": null,
  "valid_until": null,
  "created_at": "2026-11-09T10:00:00Z",
  "updated_at": "2026-11-09T10:00:00Z"
}

Save id next to your user. flow defaults to basic-kyc, which every account has.

A session is one verification attempt. It returns a one-time url for the hosted flow and a token for the SDKs.

curl https://kyc.goxost.net/api/v1/applicants/apl_01m6yyj5d7qnxppat520rwg0mb/sessions \
  -H "Authorization: Bearer $KYC_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"redirect_url": "https://shop.example/kyc/done", "expires_in": 1800}'
$session = json_decode($kyc->post("applicants/{$applicant['id']}/sessions", [
    'json' => ['redirect_url' => 'https://shop.example/kyc/done', 'expires_in' => 1800],
])->getBody(), true);

header('Location: ' . $session['url']);
const session = await fetch(`${KYC}/applicants/${applicant.id}/sessions`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ redirect_url: 'https://shop.example/kyc/done', expires_in: 1800 }),
}).then((r) => r.json());

res.redirect(session.url);
session = requests.post(
    f"{KYC}/applicants/{applicant['id']}/sessions",
    headers=headers,
    json={"redirect_url": "https://shop.example/kyc/done", "expires_in": 1800},
).json()

# redirect the user to session["url"]

Response 201 Created:

{
  "id": "ses_01m6yyj5dpxvjjhwm4t3vtqqb7",
  "url": "https://kyc.goxost.net/v/Xk7mQ2pL9aR4wTb8",
  "token": "eyJ…",
  "expires_at": "2026-11-09T10:30:00Z"
}

Open url in a browser. On a phone the flow asks for consent, a photo of the document and a selfie; on a desktop it first offers a QR code to continue on the phone. In sandbox any image is accepted. When the result screen appears, the user can go back to your redirect_url.

To keep the user on your page or in your app, pass token to kyc.js or the Flutter SDK instead of redirecting.

4. Receive the webhook

In the panel open Webhooks and add an https:// endpoint (or call POST /webhooks). Subscribe at least to verification.completed, verification.on_hold and verification.reviewed. Copy the signing secret (whsec_…); it is shown only once.

When the decision is ready, GOXOST KYC sends:

{
  "id": "evt_01m6yyj5f3k8w2c9r4tq7vbn5d",
  "type": "verification.completed",
  "created_at": "2026-11-09T10:04:12Z",
  "env": "sandbox",
  "data": {
    "applicant_id": "apl_01m6yyj5d7qnxppat520rwg0mb",
    "external_id": "user-8812",
    "verification_id": "ver_01m6yyj5dztvhsx7kk9h8qwcnf",
    "decision": "GREEN",
    "decision_type": null,
    "reject_labels": []
  }
}

Check the KYC-Signature header (t=<unix time>,v1=<hex>): v1 is HMAC-SHA256 of "{t}.{raw body}" with your secret, and t must be within 5 minutes. Answer with any 2xx quickly; other answers are retried.

<?php
$body   = file_get_contents('php://input');
$header = $_SERVER['HTTP_KYC_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $header), $sig); // ['t' => …, 'v1' => …]

$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $body, getenv('KYC_WEBHOOK_SECRET'));
$fresh    = abs(time() - (int) ($sig['t'] ?? 0)) <= 300;

if (! isset($sig['v1']) || ! $fresh || ! hash_equals($expected, $sig['v1'])) {
    http_response_code(400);
    exit;
}

$event = json_decode($body, true);
// queue your own processing here, then answer fast
http_response_code(200);
import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/kyc/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = Object.fromEntries(
    (req.get('KYC-Signature') ?? '').split(',').map((part) => part.split('=', 2)),
  );
  const expected = crypto
    .createHmac('sha256', process.env.KYC_WEBHOOK_SECRET)
    .update(`${sig.t}.`)
    .update(req.body) // raw bytes, not re-serialised JSON
    .digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) <= 300;
  const valid = typeof sig.v1 === 'string' && sig.v1.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(sig.v1), Buffer.from(expected));

  if (!fresh || !valid) return res.sendStatus(400);

  const event = JSON.parse(req.body);
  // queue your own processing here, then answer fast
  res.sendStatus(200);
});
import hashlib, hmac, os, time
from flask import Flask, abort, request

app = Flask(__name__)

@app.post("/kyc/webhook")
def kyc_webhook():
    header = request.headers.get("KYC-Signature", "")
    sig = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
    t = sig.get("t", "")
    if not t.isdigit() or abs(time.time() - int(t)) > 300:
        abort(400)

    body = request.get_data()  # raw bytes
    expected = hmac.new(
        os.environ["KYC_WEBHOOK_SECRET"].encode(), f"{t}.".encode() + body, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(expected, sig.get("v1", "")):
        abort(400)

    event = request.get_json()
    # queue your own processing here, then answer fast
    return "", 200

The webhook has no personal data — only IDs and the decision. Events, retries and the delivery log are covered in Webhooks.

5. Read the decision

Fetch the full result with the verification_id from the webhook.

curl https://kyc.goxost.net/api/v1/verifications/ver_01m6yyj5dztvhsx7kk9h8qwcnf \
  -H "Authorization: Bearer $KYC_SECRET_KEY"
$verification = json_decode(
    $kyc->get("verifications/{$event['data']['verification_id']}")->getBody(), true
);
const verification = await fetch(
  `${KYC}/verifications/${event.data.verification_id}`,
  { headers },
).then((r) => r.json());
verification = requests.get(
    f"{KYC}/verifications/{event['data']['verification_id']}", headers=headers
).json()

Response 200 OK (shortened):

{
  "id": "ver_01m6yyj5dztvhsx7kk9h8qwcnf",
  "applicant_id": "apl_01m6yyj5d7qnxppat520rwg0mb",
  "session_id": "ses_01m6yyj5dpxvjjhwm4t3vtqqb7",
  "decision": "GREEN",
  "decision_type": null,
  "reject_labels": [],
  "risk_score": 0.05,
  "stale": false,
  "checks": [
    { "name": "document", "status": "pass", "score": 0.99, "labels": [] },
    { "name": "face_match", "status": "pass", "score": 0.99, "labels": [] },
    { "name": "liveness", "status": "pass", "score": 0.99, "labels": [] }
  ],
  "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"
    }
  },
  "valid_until": "2028-11-09T10:04:12Z",
  "review_deadline_at": null,
  "reviewed_by": null,
  "reviewed_at": null,
  "created_at": "2026-11-09T10:03:40Z",
  "completed_at": "2026-11-09T10:04:12Z"
}

In sandbox document.data is a synthetic specimen (Anna Maria Eriksson from a standard "Utopia" sample), not a real person. If decision is GREEN, mark your user as verified. The full field list is in the API reference.

Next steps

  • Try the other results: create applicants with external_id ending in -expired, -mismatch or -hold — see Sandbox and live.
  • Handle RED retries and ON_HOLD reviews — see Verification flow.
  • Add Idempotency-Key to write requests so network retries are safe — see Authentication.
  • Go live: complete business verification in the panel and switch to an sk_live_ key.