Adding Contact Lookup to an ATS: Architecture Notes for Builders
Architecture notes for builders: add contact lookup to an ATS as an optional module – profile URL in, contacts out when found, empty UI that stays honest.
Builders adding contact enrichment to an ATS should treat lookup as an optional module, not a CRM bolt-on. Invenitor is a contact lookup API: LinkedIn or GitHub profile URL in, email/phone/links out when found, empty means not found. Credits are prepaid (INR packs ~₹2, Razorpay/UPI). Connecting people – a lookup API, not a sales cloud.
This post is architecture notes for product and platform teams. Category lock: What a Contact Lookup API Actually Does. Request shape hub: LinkedIn or GitHub Profile URL → Contact Lookup API.
What belongs inside the ATS vs outside it?
Inside the ATS: candidate identity, stages, notes, permissions, audit, and UI for “contact fields.” Outside (or via API): resolving those contact fields from a profile URL when the desk asks.
Do not merge sequencer logic, mailbox verification theater, or invent-on-empty into the lookup client. Honesty: Empty Means Not Found – Why Guessed Emails Break Hiring.
Recommended integration shape
- Trigger: recruiter clicks “Look up contacts” on a candidate that already has a LinkedIn/GitHub URL.
- Call:
POST /api/v1/findwith Bearer auth (see /docs). - Persist: store returned email/phone/links with provenance (“Invenitor find”, timestamp).
- Empty path: set status
not_found; do not invent; disable auto-email. - Error path: surface retryable error; do not write fake contacts; timeouts do not spend credits under Credit B.
Agents: same contract via MCP – MCP for Recruiting Agents and /mcp.md. Definition for PMs: What Is an MCP Server? (For Hiring Product Teams).
Sync patterns that stay sane
| Pattern | When to use | Risk if abused |
|---|---|---|
| On-demand button | Most ATS desks | None if empty UI is honest |
| Batch job on new candidates | High-volume agency import | Over-lookup without shortlist quality |
| Agent-assisted fill | MCP/REST from internal agents | Hallucinated fill if empty ignored |
| Nightly re-enrich | Rarely | Waste; coverage does not flip on a clock |
Soft mesh: coverage varies. We do not publish hit-rate percentages. Design SLAs around honesty and latency, not invented accuracy.
Credits, tenancy, and product packaging
Map Invenitor credits to a workspace or tenant pool – not one forced seat per recruiter for lookup alone. 1 credit only when we return an email, a phone, or both. Empty completed finds are free. Timeouts and errors do not spend. Product packaging tip: sell “lookup module” as usage-based, and keep ATS seats for workflow. Cost model: Seat Subscriptions vs Pay-Per-Lookup Credits – A Cost Model. India packs: INR Credit Packs for Contact Lookup. Live tiles: /pricing.
UI contract for empty and primary contacts
Show one primary email and one primary phone when returned. Never invent a second “likely” mailbox. If empty, show not found. Deeper product language: One Primary Contact, Never Invented. Recruiter plain English for support docs: Contact Enrichment Explained for Recruiters.
Security and ops checklist (high level)
- Store API keys in secrets, not in frontend bundles.
- Log find requests with candidate id + outcome class (found / empty / error) without shipping PII to analytics dumpsters.
- Rate-limit UI clicks; soft ~1 find/min language in docs is guidance, not a fake SLA – see /docs.
- Respect your ATS permission model: only roles that may see contacts can trigger lookup.
What not to build
- A LinkedIn scraper “fallback.”
- Auto-guessed emails from name + domain.
- Hit-rate dashboards that invent percentages for marketing.
- Bundling cold-email sequencing as if it were enrichment.
India desk reality check for your customers: India Boutique IT Staffing and Agency Desk Playbook: Bulk Candidate Sheets + API Lookups in India.
What should you do next?
Prototype the on-demand button against /docs, wire empty UI first, buy a small pack on /pricing, and only then discuss batch jobs. If agents are in scope, read /mcp.md. Keep the module optional. Keep empty empty.
How should ATS analytics treat lookup outcomes?
Count found, empty, and error as three different outcomes. Do not fold empty into “failed enrichment” if the API completed honestly. Do not publish customer-facing hit-rate % from soft mesh data. Finance can attribute credit spend to found outcomes only under Credit B. That keeps product analytics aligned with billing and with hiring trust.
Cross-rail note for India and global ATS buyers
India buyers often need Razorpay/UPI; global builders often need PAYG without annual seats. Same API. See Pay-As-You-Go Contact APIs and UPI to API Key. Link /docs and /pricing from your design doc.
Data model and rollout
Store profile URLs, email, phone, outcome (found | empty | error), and lookup timestamp. Never invent on merge. Primary fields: One Primary Contact, Never Invented. Make double-clicks idempotent in UX. Credit B: 1 credit only when we return an email, a phone, or both. Empty completed finds are free. Timeouts and errors do not spend. Rollout: empty UI → admin button → all recruiters → capped batch → MCP (What Is an MCP Server?, /mcp.md). Sheets path: Agency Desk Playbook. /pricing · LinkedIn or GitHub Profile URL → Contact Lookup API · Empty Means Not Found.
Questions
Should contact lookup live inside the ATS core or as a module?
Prefer an optional module triggered when a candidate already has a profile URL – not a mandatory CRM-style enrichment suite.
How should empty responses render in the ATS?
Show not found, disable auto-email, and never invent a mailbox. Soft mesh coverage varies.
When do credits spend for ATS lookups?
1 credit only when we return an email, a phone, or both. Empty completed finds are free. Timeouts and errors do not spend.
Can agents call the same lookup the ATS uses?
Yes via MCP or REST. Same honesty rules. See /mcp.md and /docs.
Should we nightly re-enrich every candidate?
Usually no. Prefer on-demand or import-time batch with shortlist quality gates.
Where is the API reference?
/docs for POST /api/v1/find. Pricing packs on /pricing.
Is Invenitor a sequencer?
No. It is a contact lookup API for hiring – not a sales cloud.
More in this cluster
LinkedIn or GitHub Profile URL → Contact Lookup API
HowTo: buy credits, POST a LinkedIn or GitHub profile URL to the contact lookup API, and use email/phone only when returned – empty means not found.
Read
What a Contact Lookup API Actually Does
A contact lookup API takes a LinkedIn or GitHub profile URL and returns email, phone, or links when found – empty means not found, never a guess.
Read
Freelance Recruiter Workflow: From LinkedIn Shortlist to Contact Fields
Freelance recruiter workflow: turn a LinkedIn shortlist into contact fields with a lookup API – empty means not found, INR credits, no sales cloud required.
Read