Keys, limits and conventions

How requests are authenticated, which mode they act in, and the conventions every endpoint shares: versions, request ids, rate limits, safe retries, paging and metadata.

API keys

Every request carries a secret key in the Authorization header. Create keys in the Developers console.

Authenticating

curl https://api.vindexgrid.com/v1/me \
  -H "Authorization: Bearer vdx_test_..."

# or, with curl's -u (the key as the user name, no password)
curl https://api.vindexgrid.com/v1/me -u vdx_test_...:

What a key looks like

vdx_test_ or vdx_live_, then 38 letters and digits. The last six are a checksum, so a mistyped key is refused straight away and secret scanners can recognise a leaked one.

Shown once

A key is shown in full only when it is created. Afterwards the console shows its start and last four characters. Keep it in your secrets store, never in code or chat.

Permissions

A key can do everything, or be limited: verifications only, screenings only, read only, or a custom set of verifications:read, verifications:write, screenings:read, screenings:write, events:read and balance:read. A call outside the key's permissions returns 403 insufficient_scope.

Address allowlist

Optional. List the IP addresses or CIDR ranges your servers call from; anything else gets 403 ip_not_allowed.

Rolling and revoking

Roll a key to replace it: the new key works at once and the old one keeps working for the overlap you choose (none to 7 days), so you can deploy without downtime. Revoke stops a key immediately. Keys can also expire on a date you set.

Never use a key in a browser or app

Keys are secrets for your server. A request that comes from a web page on another site is refused with 403 secret_key_in_browser, and Vindex never sends browsers CORS permission to call the API. If a key leaks, revoke it in the console.

Test and live mode

The key decides the mode: a test key acts in test mode, a live key in live mode. The two never mix.

Test mode

Free and simulated. Verifications never reach Vindex's reviewers and screenings never reach World-Check. Test credits refill themselves. See Test mode.

Live mode

Real verifications and screenings, paid with credits. Available once Vindex approves your account; until then a live key gets 403 live_mode_not_enabled.

Kept apart

Each mode has its own objects, events, webhook endpoints, signing secrets, request log and credits. Every object and event has livemode so you can tell them apart.

Versions and request ids

The API is /v1. Every response carries Vindex-Version: 2026-11-05, the date of the version that answered. Vindex adds fields and endpoints without warning, so ignore fields you don't know. Anything that would break an integration ships as a new dated version, announced in advance.

Every response also carries a Request-Id (req_…). Error bodies repeat it as request_id. Log it, and quote it to Vindex support: it finds the exact request in your request log. Responses are sent with Cache-Control: no-store because they can contain customer data.

Rate limits

Limits are per minute, per account and mode, shared by all your keys.

Requests	Live, per minute	Test, per minute
ReadGET requests	600	300
WritePOST requests, except screenings	120	60
ScreeningPOST /screenings and /screening_batches	60	60

Every response says where you stand, in the IETF RateLimit header fields. Over the limit you get 429 rate_limited with Retry-After: wait that many seconds, then retry. Need more? Ask Vindex.

Headers

RateLimit-Policy: "write";q=120;w=60
RateLimit: "write";r=97;t=23

HTTP/1.1 429 Too Many Requests
Retry-After: 23

Idempotent retries

Networks fail. Send an Idempotency-Key header on every POST (a UUID is ideal) and you can retry safely: Vindex does the work once and charges once.

Same key, same body

Within 24 hours, Vindex returns the first response again, with Idempotent-Replayed: true.

Same key, different body

Refused with 422 idempotency_key_reused. Use a new key for a new request.

First request still running

409 idempotency_key_in_use with Retry-After: 1. Wait a second and retry.

Failed requests

Only successful responses are remembered. If a request fails (for example 402), fix the cause and retry with the same key.

Scope

Keys are remembered per account and mode, up to 255 characters.

Lists and pagination

Lists come newest first, as { "object": "list", "data": [...], "has_more": true }. Ask for up to 100 at a time with limit (default 10). For the next page, send starting_after with the id of the last item you received, while has_more is true.

The next page

curl -G https://api.vindexgrid.com/v1/verifications \
  -H "Authorization: Bearer $VINDEX_API_KEY" \
  -d limit=100 \
  -d starting_after=ver_0vZ3kq9XfJ1mB7c2Lr8sTy

Verifications can also be filtered by status, external_reference, created_gte and created_lt; events by type (a group works too, such as verification.*) and object_id.

Metadata

Verifications, screenings and batches take metadata: up to 50 keys of your own, each key up to 40 characters (no [ or ]) and each value a string of up to 500. Vindex stores it and returns it, nothing more. Use external_reference (up to 255 characters, searchable) for your own id.

No personal data in metadata

Metadata and references appear in logs, events and the console. Put ids there, never names, emails, dates of birth or document numbers.

API referenceEvery endpoint, field, error and webhook event, with code in curl, Node and Python.ErrorsThe error format, validation errors, and every error code with what to do about it.

Something missing or unclear? Signed-in users can tell us from Feedback in the app.