KYC API for iGaming: Integration Checklist (2026)

A KYC API lets your platform send a player's identity data and documents to a verification provider and get back a decision plus the evidence behind it. The hard parts are the asynchronous plumbing and retention, because regulators such as the Alcohol and Gaming Commission of Ontario hold the operator, not the vendor, accountable.

In practice the plumbing means webhooks, retries, idempotent applicant creation and sandbox hygiene, and the same operator accountability applies under FINTRAC and the UK Gambling Commission.

This guide is for the engineering and compliance leads scoping that integration, with three tables you can paste into a ticket: the integration surface, a webhook resilience checklist with published vendor values, and a regulator-to-field mapping. Vendor selection is covered in our guide to KYC providers for iGaming operators; use this page to make sure the build behind whichever provider you pick survives an audit.

What a KYC API actually does for a casino or sportsbook

Know Your Customer (KYC) is the regulatory process of establishing who a customer is before you let them transact, and a KYC API is the machine interface to it: your registration flow calls the provider, the provider runs the checks – Jumio's KYC API page lists document, biometric, address, screening, AML and PEP – and the result comes back as structured data. Jumio, Trulioo, Sumsub and Onfido (Entrust) document comparable object models.

Applicant, check, result, evidence

Most provider APIs can be mapped to four building blocks. The applicant is the record you create for a player – name, date of birth, address and your own external reference. A check (or workflow run) verifies that applicant against a document, a selfie, a database or a sanctions list. The result is the decision – clear, consider, rejected, or a vendor-specific status – with reasons. The evidence is what the regulator will ask to see: extracted document fields, images, data-source hits and timestamps. Persist all four; a decision without evidence is worthless in an audit.

For the document flow, see our guide to KYC ID verification documents; for sanctions and PEP screening, see KYC screening for iGaming. This page stays on the API layer.

Where age verification fits

Age is a field, not a separate product: the date of birth from a document or database check is what proves a player is 19 or older in Ontario or 18 or older in most other markets. What matters at the API level is timing – the check must be validated before the account exists or before the player can gamble, depending on the regulator. Liveness detection on the selfie step helps detect a minor holding up a parent's ID.

Sync vs async: why the webhook is the real integration

Creating an applicant and uploading a document are synchronous calls. The verification is not: OCR, face matching, database lookups and any manual review happen on the provider's side over seconds to hours. Your integration has two halves – the calls you make and the callbacks you receive – and most incidents happen in the second.

Polling vs callbacks

Polling burns rate-limit budget and adds latency. A Webhook is an HTTP request the provider makes to your endpoint when something happens; Onfido (Entrust), for example, documents events such as workflow_run.completed. Webhooks are the primary channel; polling is the reconciliation fallback.

Idempotent applicant creation

Idempotency means repeating a request has the same effect as sending it once. If your registration service times out after creating an applicant but before storing the ID, a naive retry creates a second applicant and a second billable check. Key applicant creation on your own player reference so a retry finds the existing record.

Webhook resilience: signatures, retries, timeouts

Sumsub's webhook manager docs and the Onfido (Entrust) API reference (v3.6 at the time of writing) publish enough detail to design your endpoint properly; your provider's values will differ, the categories will not.

Verify the HMAC before you trust the payload

A webhook endpoint is a public URL, and anyone who finds it can post a fake "verified" result. The defence is an HMAC signature computed over the payload with a shared secret. Sumsub sends the digest in an x-payload-digest header and names the algorithm in X-Payload-Digest-Alg, with HMAC_SHA256_HEX as the default, SHA512 available and SHA1 deprecated. Recompute the digest over the raw body – not the parsed JSON – and reject anything that does not match.

Retry ladders and what to do on the sixth failure

Sumsub documents five retries after the first attempt – six attempts in total – at intervals of 1 minute, 5 minutes, 1 hour, 5 hours and 18 hours for standard webhooks, and a faster ladder of 30 seconds, 30 seconds, 1 minute, 5 minutes and 5 minutes for action webhooks. The endpoint must accept the connection within 1 second and respond within 10 seconds, and responses of 401, 403 or 404 stop retries altogether. So acknowledge quickly – queue the raw payload, return 200, then process – and alert on any 4xx your webhook route returns, because a misconfigured auth rule does not delay results, it silently ends them.

Replay protection and ordering

Retries mean duplicates: store each event ID and ignore repeats. Deliveries can arrive out of order, so decide state from the payload's own status and timestamp. Sumsub flags test deliveries with testMode: true.

SDK or raw API?

Camera control and liveness

Jumio states on its KYC APIs page that its SDK controls the camera during selfie capture to resist deepfakes and spoofing; other vendors make similar claims. The general point: if you accept an image uploaded through your own form, you cannot know whether it came from a live camera or a screenshot, and Liveness detection depends on controlling the capture moment.

Web vs native

A web SDK ships faster; a native SDK gets deeper camera control in a casino app. Either way, the SDK holds only a short-lived token scoped to one applicant – never your API key.

Rate limits, sandbox hygiene and go-live

Token-bucket limits and 429s

Rate limiting is the provider's protection against your traffic spikes. Onfido (Entrust) publishes its limits: 400 requests per minute on live (7 per second, burst of 14) and 120 per minute on sandbox (2 per second, burst of 4), enforced with a token bucket and a 429 response when exceeded. A registration surge can exceed 7 requests per second, so queue the KYC calls, back off on 429 with jitter, and let account creation degrade to "pending verification" rather than fail.

Never put real PII in sandbox

A Sandbox environment exists so you can test without consequences, and Onfido (Entrust) states that real personal data must never be uploaded to it. Use synthetic identities only; Onfido prefixes tokens api_sandbox. and api_live., so a startup check can refuse to boot production with a sandbox key. Onfido's OAuth 2.0 client-credentials tokens last 60 minutes, so build token refresh into your client.

Versioning and migration

APIs are versioned – Onfido's reference is at v3.6 – and old versions get deprecated. Pin the version and run contract tests against sandbox regularly.

Retention, deletion and audit logs the regulator will ask for

AGCO: validated before account creation, three-year logs

The Registrar's Standards for Internet Gaming published by the Alcohol and Gaming Commission of Ontario (updated May 14, 2026) set the Ontario baseline. Standard 3.01 makes individuals under 19 ineligible to play (those 18 and over may buy lottery tickets only). Standard 3.04 requires that name, date of birth, address, identification method, contact information and the information required under the Proceeds of Crime (Money Laundering) and Terrorist Financing Act be complete, accurate and validated before a player account is created. Standard 3.12 requires players to be authenticated before accessing their account, and Standard 1.09 requires compliance information, including logs, to be retained for a minimum of three years. Operators working with iGaming Ontario are held to these directly: account creation waits for the KYC result.

FINTRAC: five identity methods and what to record

FINTRAC's Guide 11 lists five methods to verify a person's identity – government-issued photo identification, a credit file, the dual-process method, the affiliate or member method, and reliance on another entity – and requires photo ID to be authentic, valid and current. The records to keep (name, verification date, document type, number, issuing jurisdiction) tell you exactly which report fields to persist. FINTRAC's record keeping requirements for casinos set the retention rule: at least five years, with client account and identification records kept five years from the date the account was closed, and producible to FINTRAC within 30 days.

UKGC: verify before permitted to gamble

The UK Gambling Commission's LCCP licence condition 17.1.1 requires remote licensees to obtain and verify the customer's name, address and date of birth before that customer is permitted to gamble; according to Experian's guide to age verification in gambling, this dates from the 2019 changes that removed the former 72-hour window. For the API, the "verified" webhook is a gate on the gambling permission, not a background flag.

That shapes the delete call. Onfido (Entrust) documents a deletion queue with a configurable delay – a recommended minimum of 30 days – during which an applicant can be restored. That is a safety net, not a policy: your deletion job must check the retention clock and any legal hold before it calls the vendor's delete endpoint.

Security: the OWASP API risks that hit KYC integrations

The OWASP API Security Top 10 (2023 edition) lists ten risk categories; three map directly onto a KYC integration.

• API1 – Broken Object Level Authorization. If your status endpoint accepts an applicant ID from the client without checking it belongs to the logged-in player, one player can read another's identity result. Bind every vendor ID to your player ID server-side.
• API6 – Unrestricted Access to Sensitive Business Flows. If KYC can be started, abandoned and restarted without limit, bonus abusers will spend your vendor budget finding the path that passes. Bound open checks per identity and device.
• API10 – Unsafe Consumption of APIs. The vendor is a third party: validate its webhook payloads and report JSON like user input – signature, schema, size – and never pass vendor-supplied URLs or file names to your own systems unchecked.

Integration checklist and next step: choosing the provider

Use this as the acceptance criteria for the integration ticket.

1. Applicant creation is idempotent on your player reference; the client holds only a short-lived, applicant-scoped SDK token.
2. The webhook endpoint verifies the HMAC on the raw body, deduplicates on event ID, returns 200 within the vendor's timeout; any 4xx from the route raises an alert.
3. Evidence is stored against the check ID before the account is marked verified, and the log proves the order of events required by AGCO 3.04 or LCCP 17.1.1.
4. The retention clock (AGCO three years for logs, FINTRAC five years from account closure for identification records) is enforced before any delete call.

With the build criteria fixed, the remaining question is which provider to put behind them; our KYC providers guide covers vendor categories, pricing, the RFP checklist and pilot design, including first-attempt pass rate, which your webhook data will now let you measure.

KYC and age checks exist to keep minors and self-excluded players out; nothing here should be read as advice on weakening or bypassing them. Players must be 19 or older in Ontario and 18 or older in most other regulated markets. If gambling is causing you harm, contact your local support service.

18+ only. Gambling can be addictive — please play responsibly and only bet what you can afford to lose. If gambling is affecting you or someone you know, contact a local support service. This content is informational and never a guarantee of winnings.

Written and reviewed by the iGaming Expert Hub editorial team. Facts checked against primary sources; see the reference above.

← All articles