Designing an enrichment API for Indian companies
Lookup endpoints, bulk endpoints, provenance per field. The design decisions behind the Kestrel API.
The hardest design call in an enrichment API for India is the identifier model. A request comes in. The customer has a GSTIN, or a CIN, or a name, or a website, or some combination. The API has to resolve the request to a single canonical company and return the merged record.
Kestrel's lookup endpoint accepts any of CIN, GSTIN, IEC, Udyam, PAN, name, or website. If multiple identifiers are supplied, they are used to disambiguate. If only a name or website is supplied, the resolver uses trigram-and-embedding similarity over the graph to pick the best candidate, and returns a confidence score alongside the record. Below a threshold the response is "ambiguous, try with more identifiers", with the top three candidates listed.
The bulk endpoint takes up to 5,000 identifiers per call, returns one record per identifier, and credits are charged only for resolved records. Unresolved requests are surfaced as { "resolved": false, "candidates": [...] } and do not consume credits beyond the lookup attempt fee.
Every record returned carries _provenance, a per-field object mapping each populated field to its source, legal_basis, captured_at, and last_verified_at. This is the API design decision that separates an "enrichment vendor" from an auditable data fiduciary.
Rate limiting is per-API-key sliding-window 60-second buckets, Redis-backed. 429 responses include a Retry-After header. The Free key gets 10 req/min, Growth gets 60, Scale gets 600. Bursts above the rate are silently shed (not queued), so noisy callers do not delay the responses for well-behaved ones.
OpenAPI 3.1 spec is the source of truth. SDKs (Node, Python, Go) are generated from it. Documentation at /docs/api is rendered from the same spec so it cannot drift.
Kestrel is the India-first GTM data engine. Search 1.89 million active companies, track 15 buying-signal types, and call the public enrichment API.
Try Kestrel free