When building onboarding flows, identity verification often requires checking a single user identifier against multiple platforms. Whether you are validating a phone number against WhatsApp, Telegram, and VK, or checking email presence, the architectural choice between individual service calls and consolidated requests significantly impacts your application's state management.
The Integration Landscape
Developers typically face three paths for identity verification:
- Individual Service Calls (Per-call API): Best for granular control where each check is triggered by a specific user action or requires unique retry logic.
- Combo Check API: Ideal for consolidating multiple checks into a single synchronous request, reducing the number of round-trips between your server and the provider.
- Unified Score API: Useful when you need a single risk-based output (0–1000 PTS) rather than raw registration signals for every individual platform.
When to Use the Combo Check API
If your application requires simultaneous verification across a defined set of services, the POST /v1/check/combo/phone or POST /v1/check/combo/email endpoints are the most efficient architectural choice.
Key Advantages
- Simplified State Management: Instead of tracking three or four independent HTTP promises, your backend manages a single response object.
-
Parallel Execution: The service runs checks in parallel, consolidating the results into one object keyed by
service_type. -
Flexible Configuration: You can define a default combo in your dashboard or override it per request using the
service_typesarray, allowing for dynamic verification logic based on user tier or region.
Handling Partial Results
Integration design must account for the reality of distributed systems. In a Combo Check operation, individual services may occasionally return a timeout error while others complete successfully.
// Example of a partial success response structure
{
"data": {
"results": {
"ws": { "registered": true },
"vk": { "registered": null, "error": "timeout" }
}
}
}
Because the API returns completed services even if others fail, your application logic should treat registered: null as an indeterminate state. You can then selectively retry only the failed service using the standard /v1/check endpoint, rather than re-running the entire combo.
Decision Checklist: Which approach fits your needs?
| Requirement | Recommended Approach |
|---|---|
| Need a single risk score | Unified Score API |
| Need raw registration signals for multiple platforms | Combo Check API |
| Need to isolate specific service retry logic | Per-call API |
| Need the lowest possible number of outbound requests | Combo Check API |
Conclusion
For most onboarding workflows, the Combo Check approach provides the cleanest balance between simplicity and control. By moving to a consolidated request model, you reduce the complexity of your integration layer while maintaining the ability to handle individual service failures gracefully.
Always ensure your client-side timeout is configured to accommodate the expected response window (at least 15s) to properly handle the parallel processing nature of these requests. For more details on implementation, refer to the official documentation.
This article was drafted with AI assistance and reviewed before publishing.
Top comments (1)
Returning
registered: nullfor a VK timeout preserves a distinction the onboarding flow needs to carry through: unknown isn't unregistered. Selective retries through/v1/checkavoid repeating successful checks, but the suggested client timeout of at least 15 seconds makes the user's waiting state part of the architecture too. I'd set a retry budget and offer another verification path when it's exhausted, so a provider outage doesn't quietly become a reason to reject an applicant.