OpenAPI Hygiene for Enrichment Endpoints Hiring Tools Depend On
OpenAPI hygiene for enrichment endpoints hiring tools depend on – document empties, errors, and credits so products and copilots stay honest.
Hiring tools – ATS modules, sheets bridges, recruiting copilots – depend on enrichment endpoints that behave as documented. OpenAPI hygiene is how you keep that contract honest: status codes, empty bodies, error shapes, and credit semantics written so integrators do not guess.
Invenitor is Connecting people; a lookup API, not a sales cloud. Soft mesh coverage varies – we do not publish hit-rate percentages. Specs live next to /docs; agents read /mcp.md.
Parent builders: Adding Contact Lookup to an ATS. REST: REST Enrichment Inside a Hiring Product. Sync: Webhook-Free Enrichment. Keys: Rate Limits and Keys.
What "hygiene" means for enrichment OpenAPI
| Area | Hygienic | Unhygienic |
|---|---|---|
| Empty find | Documented empty / not-found shape | 200 with invented email |
| Errors | Distinct 4xx/5xx + timeout notes | Silent 200 with null forever |
| Auth | Bearer/API key documented | Key in query string examples |
| Credits | Found-only spend described | Per-request implied without saying |
Honesty: Empty Means Not Found. Primary: One Primary Contact, Never Invented. Billing: Credits, Empty Results, and Timeouts. Primer: What Are API Credits. Pay-per-lookup: What Is Pay-Per-Lookup Pricing?.
Status codes integrators should expect
Document success-with-found, success-with-empty, auth failure, validation failure, rate limit (429), and upstream/timeout classes. ATS UIs need empty as a first-class state – not a spinner forever. Layer: Contact Lookup API vs CRM vs Sequencer. Hub: LinkedIn or GitHub Profile URL → Contact Lookup API. Definitions: What Is a LinkedIn Profile URL Lookup?, GitHub Profile URL Contact Lookup.
Examples that do not lie
cURL and Python samples should show an empty response without inventing a phone. Agent docs should twin the same shapes – Agent-Readable Docs, Building a Recruiting Copilot, Claude / Cursor Agents, MCP for Recruiting Agents, What Is an MCP Server?.
Versioning and breaking changes
Additive fields are kinder than renaming primary contact keys. Announce deprecations in /docs. Keep Credit B stable when packs change on /pricing. Trust: Trust Checklist.
Commercial still belongs in the narrative
Integrators buy INR packs – INR Credit Packs, 25 to 1,000 Credits, Razorpay, UPI, Cards, Wallets. Desks: Agency Desk Playbook, Partner Bench Sharing.
What should you do next?
Open /docs. Compare the OpenAPI (or equivalent) empty and error examples to your UI states. Wire agents only after /mcp.md matches. Buy a sample pack on /pricing once the contract is clear.
Spec one-liner
OpenAPI hygiene for enrichment = document found, empty, and error without inventing contacts – so hiring tools and copilots stay honest.
Reviewer checklist for enrichment OpenAPI
Empty example present. Error examples present. Auth not in query. 429 documented. Credit/found-only note present. Soft mesh disclaimer – no fake hit-rate %. Honesty: Empty Means Not Found. Billing: Credits, Empty Results, and Timeouts. Primer: What Are API Credits. Pay-per-lookup: What Is Pay-Per-Lookup Pricing?. Trust: Trust Checklist. Hub: LinkedIn or GitHub Profile URL → Contact Lookup API. Builders: Adding Contact Lookup to an ATS, REST Enrichment Inside a Hiring Product, Rate Limits and Keys. Agents: /mcp.md, Agent-Readable Docs, Building a Recruiting Copilot. Commercial: /pricing, 25 to 1,000 Credits. Desks: Partner Bench Sharing. /docs.
Breaking-change etiquette
Prefer additive fields. Deprecate in docs before removal. Keep Credit B wording stable when packs change. Category: What a Contact Lookup API Actually Does. Definitions: What Is a LinkedIn Profile URL Lookup?, GitHub Profile URL Contact Lookup. Primary: One Primary Contact, Never Invented. Layer: Contact Lookup API vs CRM vs Sequencer. Webhook-free: Webhook-Free Enrichment. MCP parent: MCP for Recruiting Agents, What Is an MCP Server?. Desks: Night-Shift Freelance Recruiters, Agency Desk Playbook. Commercial: INR Credit Packs.
Questions
Why does OpenAPI hygiene matter for enrichment?
ATS and agents integrate against the contract. Undocumented empties and errors cause invented fills and broken UX.
How should empty finds appear in the spec?
As an explicit success-with-empty or not-found shape – never as a fake email to keep 200 looking 'complete'.
Should credits be mentioned in API docs?
Yes at a high level: found-only spend, empty completed finds free, timeouts/errors do not spend.
Where do agents get the contract?
/mcp.md should twin REST semantics; /docs remains the human/API twin.
What about rate limits in OpenAPI?
Document 429 and recommended backoff – see Rate Limits and Keys.
Is webhook required in the spec?
Not on day one – webhook-free sync patterns exist for small ATS startups.
Where do I start as a builder?
/docs, then ATS architecture and REST enrichment posts; /pricing when you sample packs.
More in this cluster
Error Codes Buyers Should Expect from a Lookup API
Error codes buyers should expect from a lookup API – auth failures, rate limits, validation, and server faults – with honest empty vs error billing semantics.
Read
Rate Limits and Keys: Operating a Contact Lookup API in Production
Rate limits and keys: operating a contact lookup API in production – key hygiene, 429 backoff, and found-only credits when enrichment is live.
Read
Webhook-Free Enrichment: Sync Patterns for Small ATS Startups
Webhook-free enrichment: sync patterns for small ATS startups – synchronous find, job queues without bolting on webhooks first.
Read