I spend a lot of time helping companies evaluate KYB and AML vendors. The pattern is always the same: procurement runs a thorough commercial evaluation, compliance signs off on the regulatory requirements, and then three months later the engineering team is pulling their hair out trying to integrate with an API that was clearly designed by someone who has never written production code.
Here's the thing. Procurement teams are great at comparing feature lists and commercial terms. They are terrible at evaluating APIs. And since you are the one who has to live with their decision for the next three years, you need to know what questions they are not asking.
The demo trap
Vendor demos are optimised for non-technical buyers. They show polished UIs, talk about "seamless integrations" (sorry, had to use it ironically), and wave around Postman collections like they prove something meaningful about production readiness.
What they do not show you is what happens when their API returns a 500 error at 2 AM because they have not implemented proper circuit breakers. Or what it looks like to debug a failed KYC check when their error response is {"status": "error", "message": "Something went wrong"}.
I have seen procurement teams choose vendors based on feature completeness while completely ignoring API design quality. Then six months later, the engineering team is building elaborate retry mechanisms and error handling logic because the vendor's API is fundamentally unreliable.
Error handling: the canary in the coal mine
The fastest way to evaluate an API's maturity is to look at their error responses. Bad APIs return generic error messages. Good APIs return structured errors with codes, context, and actionable guidance.
Here's what a terrible KYC API error looks like:
{
"success": false,
"error": "Validation failed"
}
Here's what a well-designed error response looks like:
{
"error": {
"code": "DOCUMENT_QUALITY_INSUFFICIENT",
"message": "Document image quality does not meet minimum requirements",
"details": {
"field": "document_front",
"reason": "IMAGE_TOO_BLURRY",
"min_resolution": "300x300",
"received_resolution": "150x200"
},
"request_id": "req_1a2b3c4d"
}
}
The first response tells you nothing. The second tells you exactly what went wrong, which field caused the issue, what the requirements are, and gives you a request ID for debugging. Guess which one your users will thank you for.
Yet procurement teams rarely ask vendors to show them actual error responses. They assume error handling is a solved problem. It is not.
Webhook reliability: where most vendors fail
Webhooks are critical for KYC workflows. A customer uploads documents, the verification runs asynchronously, and you need to know when it is complete. Simple, right?
Except most KYC vendors treat webhooks as an afterthought. They do not implement proper retry logic. They do not handle SSL certificate rotation gracefully. They do not provide webhook signature verification. They do not respect HTTP status codes for delivery confirmation.
The questions your procurement team should ask:
- What happens if our webhook endpoint is down for maintenance?
- How many times do you retry failed webhook deliveries?
- What is your retry backoff strategy?
- Do you provide webhook signature verification?
- Can we replay missed webhooks from a specific timestamp?
These are not nice-to-have features. They are basic requirements for any production webhook implementation. But procurement teams do not know to ask, so vendors do not prioritise them.
Rate limits: the hidden operational cost
Here's a conversation I had with a developer last month:
"Our KYC provider has a rate limit of 10 requests per minute. We didn't know this during evaluation. Now we have to implement complex queueing logic just to onboard customers during business hours."
Rate limits are rarely discussed during procurement because they seem like a technical detail. But they directly impact your user experience and operational costs. A low rate limit means you need to build queueing infrastructure. A high rate limit with aggressive throttling means unpredictable response times.
The right questions:
- What are your rate limits per endpoint?
- How do you communicate rate limit status? (HTTP headers? API responses?)
- What happens when we exceed the limit? (Queued? Rejected? Throttled?)
- Can we purchase higher rate limits?
- Do rate limits reset per minute, hour, or day?
One vendor told a client their rate limit was "generous for most use cases". It turned out to be 100 requests per day. That is not generous. That is restrictive to the point of being unusable for any meaningful volume.
Sandbox environments: the integration litmus test
Most vendors provide sandbox environments. Few provide good ones.
A good sandbox should let you test every possible response scenario: successful verifications, document rejections, network timeouts, webhook failures, rate limit scenarios. It should have deterministic test data so you can write reliable integration tests.
A bad sandbox only supports happy path scenarios. You upload a test document, it always returns success, and you think your integration is bulletproof. Then you go to production and discover edge cases you never tested.
Ask vendors to demonstrate their sandbox capabilities. Can they show you how to simulate a document verification failure? A network timeout? A webhook delivery failure? If they cannot demonstrate these scenarios in their sandbox, how do they expect you to handle them in production?
The data structure consistency problem
KYC APIs return a lot of structured data: personal information, address details, document metadata, verification results. The quality of this data structure design varies wildly between vendors.
Bad APIs are inconsistent. They use different field names for similar concepts across endpoints. They nest data unpredictably. They mix strings and objects for similar data types.
Good APIs are consistent. They use the same field names everywhere. They have predictable nesting patterns. They use proper data types.
This might seem pedantic, but inconsistent data structures create bugs. And bugs in KYC systems mean compliance failures.
Documentation: actions speak louder than words
Every vendor claims to have "comprehensive API documentation". Most do not.
Good documentation includes:
- Complete request/response examples for every endpoint
- Error code reference with explanations
- Webhook payload examples
- SDK code samples in multiple languages
- Interactive API explorer
- Changelog with breaking change notifications
Bad documentation has incomplete examples, outdated information, and forces you to guess at field meanings.
Here's a simple test: ask the vendor to walk you through their documentation during the demo. Can they find the information you need quickly? Do the examples actually work? Are the error codes documented?
If they stumble through their own documentation, that tells you everything about the developer experience.
What you can do about it
Most procurement processes happen without engineering input until implementation starts. That is backwards. You should be involved in vendor evaluation, not just vendor integration.
When your procurement team is evaluating KYB or AML vendors, ask to see the technical evaluation criteria. If they do not have any, use this as a starting point:
- API error handling quality
- Webhook reliability and retry mechanisms
- Rate limiting policies and communication
- Sandbox environment completeness
- Data structure consistency
- Documentation quality and completeness
- SDK availability and maintenance
- Breaking change notification process
These are not theoretical concerns. They directly impact development time, operational stability, and user experience. A vendor with great features but terrible API design will cost you months of additional development work.
Our KYB/AML tender requirements template includes technical evaluation criteria that most procurement teams miss. But ultimately, the best way to evaluate an API is to actually use it.
Don't let procurement choose your integrations based on feature demos and commercial terms alone. The API quality will determine whether your integration project takes weeks or months, whether your system is reliable or brittle, and whether your users have a smooth experience or a frustrating one.
You are the one who has to live with their decision. Make sure you have input before they make it.
Top comments (0)