How do you integrate a KYC API?
Map what you have to check, set the sandbox up with real failure cases, then build the flow: create a session, capture document and selfie, and take results on webhooks that survive retries. Decide what each outcome does before launch, and watch four numbers after it — pass rate, drop-off, manual-review rate, and p95 time to verified.
This guide is for the developer or technical founder wiring KYC into an onboarding flow. By the end you'll have a verification flow in sandbox, webhooks that survive retries, and a decision matrix your compliance owner has signed off on.
Map what you actually have to check
Before you write a line of code, get three answers from whoever owns compliance. Integrations go sideways when engineering guesses at these.
| Question | Why it changes the build |
|---|---|
| Which jurisdictions are we onboarding from? | Determines document types, watchlist scope, and whether you need address or national ID checks |
| What does our CIP require? | US customer identification programs set the minimum: name, date of birth, address, identification number. Your API config must collect and verify exactly that, not roughly that |
| Do we screen for sanctions and PEPs at signup, ongoing, or both? | "Both" is the usual answer. It means a webhook consumer for ongoing alerts, not just a signup check |
Write the answers down. That document is your integration spec, and your auditor will ask for it later anyway.
Set up the sandbox properly
Every serious KYC API ships a sandbox with test documents and predictable outcomes. Spend an hour making it behave like production:
- Create separate API keys for sandbox and production, stored in your secrets manager, never in the repo
- Trigger every outcome on purpose: approved, rejected, needs-review, expired document, failed liveness. If you can't force an outcome in sandbox, you'll meet it for the first time in production
- Test the unhappy paths: user closes the tab mid-verification, uploads a photo of a photo, submits the same document twice
- Time the round trip. Document plus liveness typically returns in seconds; watchlist screening can be near-instant or queued. Know which yours is before you design the UI around it
Build the core flow
The shape is the same across vendors: create a verification session server-side, hand the user to a capture flow, receive the result by webhook.
- Create the session server-side. Your backend calls the API with the checks you need (document, selfie plus liveness, watchlist) and gets back a session ID and a client token. Never create sessions from the browser: the API key stays on your server.
- Hand off capture to the vendor's SDK or hosted flow. Resist building your own camera UI in week one. Capture quality drives pass rates, and the vendor's flow has been tuned on millions of attempts. Embed it, brand it, move on.
- Treat the redirect result as a hint, not an answer. The user coming back "complete" means capture finished, nothing more. The verdict arrives by webhook.
- Consume webhooks like they'll be replayed, because they will. Verify the signature, respond 200 fast, process async, and make handlers idempotent: the same event delivered twice must not approve an account twice or page your on-call twice.
- Store the audit trail. Verification ID, checks run, outcome, timestamps. Regulated customers get asked "prove this user was verified on this date"; that query should be one line, not an archaeology project.
Decide what each outcome does
The API returns evidence. Your system makes the decision, and that mapping deserves as much design as the plumbing:
| API outcome | Typical action |
|---|---|
| All checks passed | Auto-approve, provision account |
| Document valid, liveness failed | One retry with guidance ("remove the ID from its holder, find better light"), then manual review |
| Watchlist hit | Hold, route to compliance queue. Never auto-reject: most hits are name collisions, and a false rejection of a real customer costs more than the review |
| Document expired or unsupported | Reject with a specific reason and a path back |
| Abandoned mid-flow | Nudge once, then expire the session. Track this rate; it's your friction meter |
Put the matrix in front of your compliance owner before go-live. "Engineering decided the risk policy" is a sentence nobody wants to say in an audit.
Watch four numbers after launch
- Pass rate on first attempt. Healthy flows run high; a slide usually means a capture-quality problem or a new document type you don't support.
- Drop-off between session created and capture completed. This is where onboarding conversion dies quietly.
- Manual-review rate. Each review costs real minutes. If it creeps up, tune the retry guidance before hiring more reviewers.
- Time to verified. Measure the p95, not the average. The slowest verifications belong to your most patient, and soon least patient, customers.
Go-live checklist
- Production keys in secrets manager, sandbox keys revoked from production config
- Webhook endpoint verified: signature checked, idempotent, returns 200 in under a second
- Every decision-matrix row tested end to end in staging
- Manual-review queue has an owner and an SLA
- Audit-trail query tested: user ID in, verification history out
- Alerting on webhook failures and pass-rate drops
- Data retention configured to your policy, and image storage encrypted
Ship it behind a feature flag, run your own team through it with real documents, then open the gate.
For choosing the vendor in the first place, see how to choose KYC software. For what happens when a document is forged, see how to spot a fake ID. New to the regulatory side? Start with what KYC actually requires. Verifa's own KYC/AML API runs document, biometric, and watchlist checks through one integration, with every model in-house. For a shorter walkthrough with a code example, see adding identity verification to your app; for the fintech compliance context around it, KYC for fintech.