The vast majority of engineering teams treat an API integration with a document verification service like any other third-party API, i.e., they read the documentation, take the SDK, and process the response.
After three weeks, they are handling the issue of timeouts, storms, flaky pass rates, and a compliance department that wonders why users in Southeast Asia are failing at 4 times the rate of users in Europe. The superficial integration is easy. The version that is used in production is not. These are the engineering issues that fail to make it into the documentation and how to deal with them.
1. Synchronous vs. Asynchronous: You Probably Chose Wrong
The first decision most teams get wrong is treating document verification as a synchronous call in a user-facing flow.
Document analysis, especially when it involves liveness checks, document forgery detection, and cross-referencing against global watchlists, does not complete in 200 ms. Depending on document complexity and server load, you’re looking at anywhere from 3 to 45 seconds. Blocking your onboarding UI on that response will destroy conversion.
The correct architecture is an async webhook-based flow:
- Submit the document and receive a reference ID
- Return the user to a “pending” state
- Listen for the webhook callback
- Update the user’s onboarding status based on the result
The complication: webhooks fail. Your endpoint can be down. The verification provider can retry on a delay. Your system needs to be idempotent — processing the same webhook event twice should not create duplicate records or trigger duplicate downstream actions.
Build a webhook event log. Store every incoming payload with its event ID before processing. Check for duplicates before acting. This single decision prevents an entire category of production incidents.
2. Image Quality Is Your Responsibility, Not the API’s
A document verification service is only as good as the image it receives. Most teams discover this late, when their rejection rates are high, and support tickets are piling up.
The API will return an error code. It will not tell your user that their passport photo was taken in a dim room at an angle or that the glare from their phone’s torch washed out the MRZ line at the bottom.
You need client-side pre-validation before the image ever leaves the device:
- Resolution check: Minimum 1000×700px for most document types
- Blur detection: Run a Laplacian variance check; reject images below a threshold
- Glare detection: Check for overexposed pixel clusters in the document region
- Crop guidance: Use edge detection or a document bounding box overlay to ensure the full document is captured
Libraries like OpenCV (server-side) or browser-native APIs like OffscreenCanvas (client-side) can handle this before submission. A well-implemented pre-check layer reduces rejection rates by 30–50% in production, with no changes to the API integration itself.
3. Document Type Coverage Is Not Uniform
Every major document verification process provider will tell you they support 10,000+ document types across 200+ countries. That number is technically accurate and practically misleading.
Coverage depth varies dramatically. A UK driving license issued in 2023 is handled with high confidence. A provincial ID card from a secondary city in Indonesia, issued in 2017, with a regional font variant that’s where accuracy degrades, and manual review rates spike.
If your user base is global, you need to:
- Test with real document samples from your top 15 target markets before going live
- Segment your pass/fail metrics by document type and country, not just overall
- Implement a document checker fallback at the UX layer — if a document type fails twice, offer an alternative document path (e.g., “Can’t verify your national ID? Upload your passport instead”)
Don’t assume uniform accuracy. Measure it by segment and design your fallback logic accordingly.
4. Rate Limits Will Hit You at the Worst Possible Time
Verification APIs impose rate limits. This is expected. What engineers underestimate is when those limits matter most during peak onboarding events.
A product launch, a seasonal promotion, or a press mention can send onboarding volume 10× above baseline within an hour. If your integration submits verifications synchronously per user request, you’ll hit rate limits mid-surge, return errors, and lose users who won’t retry.
The solution is a verification queue:
- All verification requests go into a queue (Redis, SQS, or equivalent)
- A worker pool pulls from the queue and submits to the API at a controlled rate
- Users receive a “verification in progress” status immediately
- Results are delivered asynchronously via the webhook pipeline you’ve already built
This architecture also gives you retry logic for transient API failures. A request that fails with a 503 goes back into the queue with exponential backoff, rather than surfacing as an error to the user.
RELATED POST: Planning a Trip to Poland
5. Data Residency Will Break Your Architecture Assumptions
This one arrives late in the project and hits hard.
Depending on where your users are located, you may be legally required to keep their identity documents and the verification results within a specific geographic boundary. GDPR in Europe, PDPA in Thailand, LGPD in Brazil, and similar frameworks all impose constraints on cross-border data transfer.
Most verification API providers offer regional endpoints. Few engineering teams configure them correctly, because the default endpoint is always the lowest-latency one from their testing environment.
Before production:
- Map your user geography to the relevant data residency requirements
- Confirm which regional endpoints your provider supports
- Route API calls by user region, not by a single global default
- Ensure verification results stored on your side are also region-scoped in your database
Missing this is not a performance bug; it’s a compliance violation that your legal team will eventually discover.
6. Verify documents Failures Need to Be Instrumented, Not Just Logged
When a user fails to verify documents, most teams log the API error code and move on. That’s not enough.
Error codes from verification APIs are coarse. “DOCUMENT_UNREADABLE” could mean blur, glare, wrong document type, partial capture, or actual document forgery, each of which requires a different response from your system.
Build an instrumentation layer that captures:
- The specific error code and any sub-codes
- The document type attempted
- The user’s device and camera (mobile vs. desktop, OS)
- The attempt number (first try vs. retry)
- Time of day and geographic region
Aggregate this data. You will discover patterns: a specific Android device model that consistently produces glare issues, a document type with a 60% failure rate on first attempt that drops to 8% on retry, and a regional ISP where image upload is degrading before it reaches the API.
These are engineering problems. They’re solvable. But only if you’ve built the instrumentation to see them.
The Integration Is the Easy Part
To retrieve a response in your sandbox, it is easy to get a document verification API. The real work is to create a production system that supports the correct operation of async flows, gracefully scales with load, routes data correctly, and provides actionable diagnostics on failure.
The API integration is a checkbox item in teams that find these challenges in production, when they are under pressure. Designing teams that design on their behalf ship more quickly and have higher pass rates at scale. The provider deals with the verification logic itself. All that surrounds it is under your care.
