1. Get a sandbox key
- Create an account at /register and sign in to the panel.
- Open API keys, choose Create key and select the Sandbox environment.
- Copy the key. It starts with
sk_test_and is shown only once — store it in your server's secrets, for example as theKYC_SECRET_KEYenvironment 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).
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.
3. Create a session and open the link
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_idending in-expired,-mismatchor-hold— see Sandbox and live. - Handle
REDretries andON_HOLDreviews — see Verification flow. - Add
Idempotency-Keyto write requests so network retries are safe — see Authentication. - Go live: complete business verification in the panel and switch to an
sk_live_key.