One REST API for KYC, AML & age.

Authentication

Authenticate every request with your secret API key in the Authorization header as a Bearer token. Create and manage keys in the dashboard under Settings → API keys.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx

Test vs live. test keys run against a sandbox and never touch real data or billing; live keys run real checks and consume your allowance/overage. On the Free plan only test keys are available. Keys are shown once at creation — store them securely and never expose a secret key in client-side code.

Base URL

https://app.gocirvex.com/api/v1

All endpoints below are relative to this base. Requests and responses use JSON; send Content-Type: application/json on requests with a body. Money and credit amounts are returned as decimal strings, not floats.

Verifications

POST/v1/verifications

Start a verification. Returns a hosted flow URL (on paid plans) you can redirect the user to, and reserves the credits the check will consume.

Field	Type	Description
type	string	Check type — KYC (identity). Required.
mode	string	auto (automated) or hybrid (specialist review). Defaults to auto.
aml	boolean	Also run AML screening (sanctions / PEP / adverse-media). Requires the Comply plan or above.
clientName	string	Optional label for the subject.
country	string	Optional subject country.

curl https://app.gocirvex.com/api/v1/verifications \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "type": "KYC", "mode": "auto", "aml": true, "clientName": "Jane Doe", "country": "DE" }'

201 Created

{
  "id": "clx...",
  "reference": "vf_a1b2c3",
  "status": "PENDING",
  "credits_reserved": 1.25,
  "hostedUrl": "https://alchemy.veriff.com/v/..."
}

Redirect the user to hostedUrl to complete the flow. The final decision arrives on your webhook (see below). If the operation isn't on your plan you get 403 operation_requires_plan; if the period's platform fee is unpaid, 402 period_unpaid.

GET/v1/verifications

List your most recent verifications.

{
  "data": [
    { "id": "clx...", "reference": "vf_a1b2c3", "type": "KYC",
      "status": "PASS", "clientName": "Jane Doe", "country": "DE", "createdAt": "2026-07-06T..." }
  ]
}

AML screenings Enterprise

POST/v1/screenings

Re-screen an existing profile against sanctions, PEP and adverse-media lists. Available on Enterprise plans; other plans receive 403 operation_requires_plan.

Field	Type	Description
profile	string	Your reference for the profile being re-screened. Required.
idempotencyKey	string	Optional — dedupes retries of the same screening.

curl https://app.gocirvex.com/api/v1/screenings \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "profile": "user_8842" }'

201 Created

{ "id": "…", "profile": "user_8842", "status": "clear", "credits_debited": 0.30, "is_overage": false }

Billing

GET/v1/billing/balance

Current period balance for your organisation.

{
  "period_start": "2026-07-01T00:00:00.000Z",
  "period_end":   "2026-08-01T00:00:00.000Z",
  "granted":      "2000.00",
  "used":         "1250.00",
  "reserved":     "1.25",
  "available":    "748.75",
  "overage_used": "0.00",
  "overage_price":"1.00"
}

GET/v1/billing/transactions

Paginated ledger. Query params: from, to (ISO dates), cursor, limit (1–200).

{
  "data": [
    { "id": "…", "amount": "-1.25", "type": "debit",
      "operation_type": null, "reference_type": "verification",
      "reference_id": "clx...", "is_overage": false, "created_at": "2026-07-06T..." }
  ],
  "next_cursor": "clx..."
}

Pass next_cursor back as cursor to page. When next_cursor is null, you've reached the end.

Webhooks

Add endpoints in the dashboard. When a verification reaches a decision we POST a JSON event to each active endpoint. Each delivery is signed with your endpoint's secret (HMAC-SHA256) — verify the signature before trusting the payload.

POST https://your-app.com/webhooks/cirvex
{
  "type": "verification.updated",
  "data": { "id": "clx...", "reference": "vf_a1b2c3", "type": "KYC", "status": "PASS" }
}

Respond 2xx to acknowledge. Deliveries are retried on failure; treat events as idempotent by reference.

Verification statuses

Status	Meaning
PENDING	Created; awaiting the subject / a decision.
PASS	The check passed (cleared / verified).
REVIEW	Borderline — needs a human decision.
FAIL	Did not pass (e.g. a sanctions hit or document mismatch).

Errors & rate limits

Errors return a JSON body with an error message and, where relevant, a machine-readable code.

Status	Code	Meaning
401	—	Invalid or missing API key.
402	period_unpaid / payment_past_due	The platform fee for this period is unpaid (past the grace window).
403	operation_requires_plan	The operation needs a higher plan; the response includes minimumPlan.
403	—	Account suspended or closed.
400	—	Invalid request body.
429	—	Rate limit exceeded — back off and retry.

Verifications are never blocked when you run over your included allowance — extra checks continue and are billed as overage. The only hard block is non-payment.