Most identity verification API documentation focuses on the technical integration: how to initiate a session, what parameters to pass, how to handle webhooks, what the response payload looks like. That is the plumbing. It is necessary but not sufficient for a compliant, production-ready integration.
The compliance architecture layer sits on top of the technical integration and determines whether the verified identity data you collect is handled in a way that satisfies your regulatory obligations, does not create unnecessary legal exposure, and supports the audit trail requirements your compliance team or your regulators will eventually want to examine. Getting the technical integration right while getting the compliance architecture wrong is how teams end up with a working product and a compliance problem six months later.
This is a practitioner's guide to both layers, written for engineering teams building onboarding flows in regulated environments.
The Technical Integration Layer
Session Initiation and Token Handling
Most modern IDV APIs use a session-based model: your backend initiates a verification session by calling the vendor's session creation endpoint with the applicant's metadata, and the vendor returns a short-lived session token that is then passed to the client-side SDK or hosted flow. The user completes the verification in the session, and the result is delivered to your backend via webhook or via a result retrieval endpoint polled against the session ID.
A common integration mistake at this layer is passing session tokens through the frontend in a way that allows them to be harvested and replayed. The session token should be passed from your backend to your frontend on a per-request basis for the current user's session, not stored in localStorage or any persistent client-side store. A harvested session token that remains valid allows an adversary to initiate a fresh verification attempt under your account.
Token expiry windows matter. Short-lived tokens (5-15 minutes) are the right default for verification sessions. If your onboarding flow has significant steps before the user reaches the identity verification step, do not initiate the session at the beginning of the flow and pass the token forward. Initiate it at the point where the user is about to begin verification, with a fresh token.
Webhook Handling and Idempotency
IDV results are typically delivered via webhook. Webhook handling requires a few specific protections that are often missed in initial integrations.
Webhook signature validation is mandatory. Every reputable IDV vendor signs their webhook payloads. Your endpoint should validate the signature on every incoming webhook before processing the payload. An unsigned or invalidly signed webhook should be rejected with a 400, not processed. This is not a paranoid measure: it is the basic security control that prevents an adversary from spoofing a verification approval by posting a crafted payload to your webhook endpoint.
Idempotency is required because webhook delivery is at-least-once, not exactly-once. A verification result may be delivered multiple times if your endpoint returns a 5xx or times out on the first delivery. Your handler must be idempotent: processing the same event ID twice should produce the same outcome as processing it once, without creating duplicate records or triggering duplicate downstream actions (like sending an approval email twice or crediting an account twice).
Store the incoming event ID alongside the processing record and check for duplicates before acting on a new webhook payload. The check-then-act sequence should be within a database transaction if downstream actions are transactional.
Data Storage and the Minimum-Retention Principle
This is where the technical layer begins to intersect with the compliance architecture, and where many teams make decisions that create problems later. The most common mistake is storing the full verification result payload, including the biometric data fields (face image, document images), in the application database because it is convenient.
Biometric data is subject to heightened legal requirements in multiple jurisdictions. The Illinois Biometric Information Privacy Act (BIPA), Texas and Washington state biometric laws, and GDPR Article 9 (special categories of personal data) all create specific obligations around the collection, storage, and retention of biometric information. Storing biometric data in your application database when you do not have a specific operational need for it creates legal exposure without a corresponding benefit.
The right default is to store only the verification decision and the non-biometric metadata from the result: the verification session ID (so you can retrieve the full result from the vendor if needed), the decision outcome, the document type detected, the extracted name and date of birth (if those are data fields you need for your product logic), and any fraud signals. Store a reference to the vendor's record, not the biometric data itself. Vendors maintain the underlying document images and biometric data on their end per their own retention policies, and you can retrieve them under a documented legal process if needed. You do not need to store them independently in your system.
The Compliance Architecture Layer
The Verification Decision Record
Your database schema for storing verification results should include not just the decision outcome but the decision context. The decision context is what your compliance team and your regulators will ask for when reviewing a specific verification decision: what checks were run, what signals contributed to the decision, and what manual review occurred if applicable.
At minimum, store: the session ID linking to the vendor's record, the timestamp of the verification decision, which verification checks were executed in the session (document verification, liveness check, address check, watchlist screening), the outcome of each individual check, the overall decision, who or what made the decision (automated or manual review), and the agent or reviewer ID if manual review was involved. This is the audit trail, and it needs to be retrievable per session for any user whose verification you made a decision on.
Adverse Action Compliance
If you decline to open an account or provide a service based in whole or in part on an identity verification result, you may have adverse action notification obligations under the Fair Credit Reporting Act (FCRA) or state law equivalents. Whether FCRA applies depends on whether the IDV vendor you are using is a consumer reporting agency under the statutory definition, which is a legal question rather than a technical one. Many IDV vendors take a position on this; that position should be documented and reviewed by your legal team before you build your adverse action process around it.
Regardless of FCRA applicability, users who are declined at verification typically receive generic error messages that tell them "we couldn't verify your identity" without providing meaningful information about why. Building an adverse action notice capability, even if simplified, is both better practice from a user experience standpoint and a compliance position you want to be able to document. The notice should tell the user enough that they can understand the basis for the decision and seek to correct it if it was based on incorrect information.
Watchlist Screening Timing and Records
If your verification flow includes OFAC SDN screening or PEP (Politically Exposed Persons) screening, the timing and record-keeping requirements deserve specific attention. OFAC screening is not a one-time event at account opening. OFAC continuously updates the SDN list, and your obligation to not facilitate transactions with SDN-listed persons is ongoing. New designations can add individuals to the list who were not on it when they opened their account with you.
Your integration should include a mechanism for re-screening your user population against updated watchlists on a scheduled basis. The frequency of re-screening is a compliance program design decision that depends on your product type and regulatory guidance applicable to your business. But the capability needs to be in the integration architecture from the start, because retrofitting batch watchlist re-screening into an application that was not designed for it is significantly more complex than building it in initially.
Records of each screening run, the list version used, and the result should be stored and retrievable. If a match is found on a re-screen, the workflow for review and action needs to be defined before it happens, not improvised when it does.
Vendor Lock-In and Architecture Independence
One architectural decision worth making explicitly at integration time is how tightly coupled your application logic is to the specific IDV vendor's data model. Vendor lock-in in the IDV space is a real operational risk: if the vendor changes their API, raises prices, gets acquired, or has a service reliability issue, your ability to switch to an alternative without significant re-engineering depends on how abstracted your application code is from vendor-specific implementation details.
A practical mitigation is to build a normalization layer between your application logic and the vendor API. Your application code calls your own internal verification service, which maps between your data model and the vendor's data model. When you need to switch vendors or add a second vendor for fallback, the change is contained within the normalization layer. Application code that directly calls vendor endpoints and directly processes vendor response schemas creates a surface area of change that scales with the vendor's API complexity.
We're not saying building an abstraction layer is always worth the initial overhead. For an early-stage product with a single vendor and no near-term plans to switch, a direct integration may be the right tradeoff. The point is to make the tradeoff consciously, understanding that direct integration debt accumulates and becomes more expensive to pay down as the application grows. Designing for vendor portability from the start costs less than refactoring it in later.
Error Handling That Doesn't Strand Users
Identity verification flows have a category of errors that are different from standard API errors: they are user-facing failures where the right response is to provide the user a path forward rather than an error screen. Document capture failures, liveness check failures, and network timeouts during verification all require handling that preserves the user's ability to retry or seek support, not just logging the error and showing a generic failure page.
Build explicit retry paths for recoverable failures. A document image that the classifier rejects due to image quality is a different case from a document that the classifier positively identifies as a fraudulent document. One should offer a retake; the other should route to a review state. Your error handling logic needs to distinguish between these cases using the error codes from the vendor's response, which means reading the vendor's error taxonomy carefully and mapping it explicitly in your error handling code.
Timeouts and service unavailability are also cases that need explicit handling. If the IDV vendor's service is unavailable during a verification attempt, the user should be placed in a pending state and routed back into the verification flow when service is restored, not permanently failed. Building the pending/resume state into your onboarding flow from the start saves significant user experience problems when vendor service incidents occur.