Skip to content
API reference Get API keys

Integration · Chapter 7

Certificates

Every final check gets an electronically signed verification certificate. It shows who requested the check, why, and what the decision was — and anyone can confirm it is genuine at https://kyc.goxost.net/verify.

5 min read

What a certificate is

A certificate is issued for each verification with a final decision — GREEN or RED. An ON_HOLD case gets its certificate after your reviewer decides. It is ready about 5 minutes after the decision, and the certificate.issued webhook tells you when.

The certificate contains:

Section What it says
Requester Your company (legal name from the business profile), project, website
Purpose Why the check was done: the session purpose, otherwise the applicant's, otherwise the default purpose from your business profile
Person Full name, date of birth, document type, country and number
Decision Approved, rejected or cancelled (review deadline passed), date of the decision, reviewer when decided by hand
Checks performed Which checks were done (document, selfie match, presence, sanctions, …) in plain words
Validity For GREEN — valid until (2 years from the decision); RED has no validity date
Consent When the person gave consent, the consent text version, device and IP address
Contract Your contract reference and its SHA-256 if you passed contract when creating the session
Images SHA-256 fingerprints of the stored images used in the check

The PDF has a certificate number (crt_…) and a QR code that opens its check page. Scores, machine reason codes and the internal decision method are not printed.

Note

A certificate never changes. If a decision changes after a re-review, a new version is issued and the old one is marked as superseded. When the applicant is deleted, the stored certificate text is erased and the check page shows the certificate as withdrawn.

Certificates made in sandbox are marked "Test mode — this certificate has no legal force".

The certificate proves that the check took place and what it showed on that date. It is not an identity document and does not confirm your contract with the customer.

Download via API

GET /verifications/{id}/certificate returns the certificate of a final verification.

Query Values Default
format pdf — printable PDF (download as crt_….pdf); json — machine-readable content json
lang Language of the PDF: uz, ru, en uz
curl "https://kyc.goxost.net/api/v1/verifications/ver_01m6yyj5dztvhsx7kk9h8qwcnf/certificate?format=pdf&lang=en" \
  -H "Authorization: Bearer sk_live_…" \
  -o certificate.pdf
$client = new GuzzleHttp\Client(['base_uri' => 'https://kyc.goxost.net/api/v1/']);
$client->get('verifications/ver_01m6yyj5dztvhsx7kk9h8qwcnf/certificate', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('KYC_SECRET_KEY')],
    'query' => ['format' => 'pdf', 'lang' => 'en'],
    'sink' => __DIR__ . '/certificate.pdf',
]);
import { writeFile } from 'node:fs/promises';

const res = await fetch(
  'https://kyc.goxost.net/api/v1/verifications/ver_01m6yyj5dztvhsx7kk9h8qwcnf/certificate?format=pdf&lang=en',
  { headers: { Authorization: `Bearer ${process.env.KYC_SECRET_KEY}` } },
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
await writeFile('certificate.pdf', Buffer.from(await res.arrayBuffer()));
import os, requests

res = requests.get(
    "https://kyc.goxost.net/api/v1/verifications/ver_01m6yyj5dztvhsx7kk9h8qwcnf/certificate",
    headers={"Authorization": f"Bearer {os.environ['KYC_SECRET_KEY']}"},
    params={"format": "pdf", "lang": "en"},
)
res.raise_for_status()
open("certificate.pdf", "wb").write(res.content)

The JSON format carries the same content as the PDF in structured form (certificate.requester, certificate.purpose, certificate.subject, certificate.verification, certificate.valid_until, certificate.verify_url, …), plus its electronic signature and a meta block with status and superseded_by. Keep the PDF or JSON with your records if you need it later. To prove authenticity, use the check page or GET /certificates/{id} — the signature is checked only by GOXOST KYC.

Repeated requests return exactly the same document. Every download is written to your audit log.

Error When
409 conflict The verification is ON_HOLD (no final decision yet)
404 not_found Unknown verification, or the applicant was deleted
400 validation_failed Unsupported format or lang
503 certificate_unavailable Certificates are temporarily unavailable — try again later

In the panel, the applicant page has Download certificate for the same files.

How anyone checks a certificate

Give the certificate to anyone who needs proof — a bank, a partner, the person themselves. They do not need an account. The page https://kyc.goxost.net/verify offers three ways.

1. By number or QR code

Scan the QR code on the PDF, open the link https://kyc.goxost.net/verify/crt_…, or type the certificate number (or paste the link) into the search on https://kyc.goxost.net/verify. The page shows:

  • whether the certificate is genuine, invalid, superseded by a newer version, or withdrawn;
  • requester and purpose;
  • issue date, decision and validity date;
  • document type and the masked document number (first 2 and last 4 characters, e.g. L8•••02C3);
  • when the person gave consent.

The person's name, date of birth and other personal data are not shown here.

2. Upload the PDF

On the same page, upload the PDF file (up to 4 MB). It is compared byte by byte with the PDF GOXOST KYC issued — any change, even one character, fails the check. The file is not stored.

3. Enter the document number from the copy

If someone shows a printed copy or a scan, type the full document number printed on it. If the number matches the certificate, the page reveals the full name and document number to compare with the copy. A mismatch means the copy was changed or is fake. A certificate can be checked this way up to 20 times a day.

Tip

Put the check link next to the certificate wherever you share it, so the recipient can confirm it in one click.

Certificate status

To check one of your own certificates from code, call GET /certificates/{certificate_id} with the API key of the same environment. The answer has no personal data.

curl https://kyc.goxost.net/api/v1/certificates/crt_01m6yyj5eaqdmyg2ty0mheaj3h \
  -H "Authorization: Bearer sk_live_…"
{
  "certificate_id": "crt_01m6yyj5eaqdmyg2ty0mheaj3h",
  "version": 1,
  "status": "current",
  "signature_valid": true,
  "valid": true,
  "decision": "GREEN",
  "outcome": "approved",
  "issued_at": "2026-11-09T10:09:30Z",
  "valid_until": "2028-11-09T10:04:12Z",
  "expired": false,
  "superseded_by": null,
  "verify_url": "https://kyc.goxost.net/verify/crt_01m6yyj5eaqdmyg2ty0mheaj3h"
}
status Meaning
current The latest version of the certificate
superseded A re-review issued a newer version — see superseded_by
revoked The applicant was deleted; the certificate is withdrawn
invalid_signature The stored text does not match its signature — do not trust it

valid is the single answer to "is this person verified right now": it is true only when status is current, the decision is GREEN and valid_until has not passed.

Validity and re-verification

A GREEN result is valid for 2 years from the decision (valid_until in the verification, the applicant and the certificate). 30 days before it ends, and again when it ends, you receive applicant.reverification_due. To verify the person again, call POST /applicants/{id}/reset and create a new session — the new check gets its own certificate.