Identity Verification API Integration Guide

Developer patterns for integrating a KYC / identity verification API into your product: hosted verification sessions, webhook handling, QR hand-off from desktop to mobile, API key security, and a go-live checklist.

The guides are written around FinAuth's API model — create a session, send the user through a hosted flow, receive the decision by webhook — but the patterns apply to most modern verification providers. Exact endpoint shapes and parameters live in the FinAuth documentation; this repo covers the architecture around them.

Guides

1. Hosted Verification Sessions — the create-session → redirect → webhook pattern, and why hosted flows beat DIY capture
2. Webhooks — signature verification, idempotency, retries, and not trusting redirects
3. QR Code Mobile Hand-off — moving desktop users to their phone camera without losing the session
4. API Key Security — server-side-only keys, rotation, and least-privilege team access
5. Go-Live Checklist — everything to verify before real users hit your verification flow

The core integration in one diagram

Your backend                    FinAuth                      End user
    |  POST create session         |                             |
    |----------------------------->|                             |
    |  session id + session URL    |                             |
    |<-----------------------------|                             |
    |  present URL (link/QR/redirect) ---------------------------|
    |                              |   hosted flow:              |
    |                              |   document + selfie capture |
    |                              |<----------------------------|
    |  signed webhook: decision    |                             |
    |<-----------------------------|                             |
    |  update account status       |                             |

Three properties make this pattern robust:

• No sensitive capture in your codebase — document images and selfies flow through the provider's hosted UI, shrinking your compliance surface.
• The webhook is the source of truth — never grant access based on the user returning to a success URL (users can navigate there manually; decisions can arrive after review).
• Sessions are addressable — a session URL can be delivered as a redirect, an email link, or a QR code, which enables the mobile hand-off.

Related resources

• KYC Compliance Handbook — the domain knowledge behind the endpoints
• FinAuth Use Cases — industry-specific flows
• Digital Onboarding Best Practices — conversion-side design
• Awesome Identity Verification — the wider tool landscape

---

Maintained by FinAuth — developer-first identity verification API with a free tier. Get started · Docs