Skip to content
API reference Get API keys

Getting started · Chapter 3

Sandbox and live

Build and test your whole integration in sandbox with mocked results, then switch to a live key once your business is verified.

4 min read

Sandbox vs live

Sandbox Live
API key prefix sk_test_ sk_live_
Checks No real checks. The result is chosen by the external_id suffix Real document checks, presence check, selfie-to-document match and optional AML
Images Any image is accepted A real document and the real person are needed
Document data Synthetic specimen, nothing is read from storage The document data of the person
Webhooks Sent exactly as in live, with "env": "sandbox" "env": "live"
Monthly limit Not limited, but counted in GET /usage → sandbox Your plan limit
When available Right after sign-up After business verification

The base URL is the same for both: https://kyc.goxost.net/api/v1. The key decides the environment, and each key sees only its own environment. Applicants, sessions, webhook endpoints and verifications in sandbox are separate from live; an ID from one environment returns 404 not_found in the other.

Choose the result in sandbox

With an sk_test_ key the decision depends on how the applicant's external_id ends. The suffix is read when you create the session.

external_id ends with Decision decision_type reject_labels
anything else (e.g. -green) GREEN null []
-expired RED retry DOC_EXPIRED
-mismatch RED final FACE_MISMATCH
-hold ON_HOLD null PEP_MATCH
-sanctions RED final SANCTIONS_MATCH
-duplicate RED final DUPLICATE
-underage RED final UNDERAGE
-age-unknown ON_HOLD null AGE_UNKNOWN
-recapture ON_HOLD null DOC_SCREEN_RECAPTURE
{ "external_id": "user-8812-hold" }

Notes:

  • -age-unknown works only in an age-only flow (Settings → Checks in the panel); in other flows it gives GREEN. In an age-only flow every result also has an age check, and -sanctions and -duplicate give GREEN because AML and duplicate checks do not run there.
  • -duplicate returns no other applicant IDs in sandbox.
  • -recapture simulates a document image that did not pass the authenticity check: it adds a doc_fraud check with status warn; other sandbox results have no such check.

Sandbox document data

GET /verifications/{id} in sandbox returns a synthetic specimen in document.data: "ERIKSSON ANNA MARIA", passport L898902C3, country UTO. Dates are relative to the verification time. With -expired the document is expired (is_expired: true); with -underage the age is 16. In age-only flows document.data is null, as in live.

Use sandbox to test every branch of your code: GREEN, RED with retry, RED with final, and ON_HOLD followed by a review. You can decide a sandbox ON_HOLD with POST /verifications/{id}/review or in the panel and receive verification.reviewed.

Tip

Direct API in sandbox

With an sk_test_ key the Direct API does not run real checks: every check returns a mocked pass with score 0.99, and the document check returns the same synthetic specimen. Calls are not limited, but they are counted.

Going live

Sandbox is open as soon as you register. Live mode — creating sk_live_ keys, the live API and the live environment in the panel — opens after two steps in the panel:

  1. Business profile. Business type (company, entrepreneur or individual), legal name, registration number (optional for individuals), country, website, project name and description, use case, and the default verification purpose. Certificates and the public verification page show which business and project ran the check, and why, from this profile.
  2. Owner identity. The account owner passes a normal KYC verification. GREEN verifies the account; ON_HOLD is reviewed by GOXOST staff; after RED you can try again (3 attempts in total).

Until both steps are done, any request with an sk_live_ key returns:

{
  "error": {
    "code": "tenant_not_verified",
    "message": "Live mode opens after your business profile and owner identity are verified.",
    "request_id": "req_01m6yyj5gq0x3c7d2n8v5kp4rt"
  }
}

with HTTP status 403. If you later change the legal name, registration number or business type, live keeps working but the profile is marked for re-review.

Limits and the free plan

The free plan includes 100 live verifications per month. A unit is reserved when a session is created and given back if the session expires unused, is replaced by a new session, or the applicant is reset or deleted before submitting. Standalone AML screening and Direct API calls have their own monthly counters with the same limit. When a live limit is reached the API returns 429 plan_limit_reached.

Check your counters with GET /usage:

{
  "period": "2026-11",
  "plan": "free",
  "limit": 100,
  "live": { "verifications": 12, "aml_checks": 0, "direct_checks": 0 },
  "sandbox": { "verifications": 51, "aml_checks": 0, "direct_checks": 7 },
  "core_url": "https://…/v1"
}

core_url is the base URL for Direct API calls.