API conventions

Shared VOVE ID API behavior for environments, authentication, identifiers, responses, and retries.

Base URLs

Environment	Base URL	Purpose
Sandbox	https://api.voveid.net	Build and test with fictional data
Production	https://api.voveid.com	Process approved production traffic

KYC routes begin with /v2. KYB and AML routes are unversioned. Use the path shown on each endpoint page.

Authentication

Server-to-server requests use the x-api-key header:

x-api-key: vove_sandbox_replace_me
accept: application/json

API keys are private credentials. Store them in a server-side secret manager, never in browser code, mobile applications, URLs, analytics, screenshots, or logs.

Client SDKs use a public SDK key plus a short-lived session token created by your backend. Public keys are not substitutes for API keys.

Stable identifiers

Create and persist a stable refId before starting a KYC session, KYB case, or AML case. Use it to correlate your record with webhooks and result retrieval. Do not silently generate a different refId after a timeout; reconcile the original request first.

Request and response format

Unless an endpoint says otherwise:

• Send JSON with content-type: application/json.

• Treat documented enum values as case-sensitive.

• Tolerate additive response fields.

• Do not depend on undocumented fields.

• URL-encode all path and query values.

Errors and retries

Branch first on HTTP status, then on a documented machine-readable error code when present. Retry only when the operation is safe to repeat, using bounded exponential backoff with jitter.

For a timeout on a create operation, assume the result is unknown. Query by the stable identifier before attempting another create.

See Errors for recovery guidance.