Bulk Enrich API: The Match Rate Bug
By Kooperativa Engineering
Here is a bug pattern that shows up in more bulk enrichment implementations than it should: run the exact same batch of 500 identifiers twice in a row, and get 480 matches the first time and 495 the second. Nothing about the underlying data changed between runs. The identifiers are identical. Yet the reported match count moved by 15.
The cause is almost always the same thing: a transient upstream failure, a timeout, a momentary rate limit, got counted as "not found" instead of "failed to check." Those are not the same outcome, and treating them as one produces exactly this kind of flaky, untrustworthy number.
Why the distinction is not just pedantic
A record reported as not_found has been checked, and genuinely does not exist in the dataset. Retrying it wastes a call. A record reported as failed was never successfully checked at all, it might exist, it might not, the lookup simply did not complete. Retrying it is the correct move, and often succeeds immediately since most causes of failure are transient.
A caller that cannot tell these apart has two bad options: retry everything (wasteful, and pointless for genuine misses) or retry nothing (silently drops real matches that just had a bad first attempt).
What a batch response should actually report
A response that separates these outcomes explicitly removes the ambiguity entirely:
- matched: identifiers that resolved to a real record, returned in full.
- not_found: identifiers genuinely checked and confirmed absent from the dataset.
- failed: identifiers that could not be checked due to a transient error, safe and worthwhile to retry.
async function bulkEnrich(identifiers) {
const out = [];
for (let i = 0; i < identifiers.length; i += 100) {
const res = await fetch("https://kooperativa.io/api/v1/people/bulk-enrich", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KOOPERATIVA_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ profiles: identifiers.slice(i, i + 100) }),
});
const data = await res.json();
out.push(...data.profiles);
}
return out;
}A concrete check to run before trusting a vendor's match rate
Run the same batch of known-good identifiers through a bulk endpoint three times in a row. If the match count is not identical across all three runs, the provider is very likely conflating not-found with failed, and every match rate they have advertised on a marketing page should be treated as an upper bound, not a real number.
Get started
Try Kooperativa
One API key. Person and company enrichment, structured search, and monitors under one flat license.