// CONTACT ENRICHMENT API
Contact enrichment API: send a LinkedIn URL, get the email and phone
Updated November 20, 2026
A contact enrichment API takes something you know about a person, such as a LinkedIn URL, and returns how to reach them. Descovo's returns a work email, personal email and direct phone over REST or MCP. You are charged per field found: 2 credits for an email, 3 for a phone, nothing when nothing is found.
One request reveals one person
Send the profile URL and say which fields you want. The base URL is https://api.descovo.com/v1 and the only header you need is Authorization: Bearer <key>.
curl -X POST https://api.descovo.com/v1/contacts/reveal \
-H "Authorization: Bearer $DESCOVO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"linkedinUrl":"https://www.linkedin.com/in/satyanadella","enrichmentType":{"getWorkEmails":true,"getPersonalEmails":false,"getPhoneNumbers":true}}'Every response reports what it cost in credits.charged and your balance in credits.available, so a pipeline can stop itself before it overspends. The full route list is in the REST API reference, and there are step-by-step guides for Python and Node.js.
What each enrichment costs
There are three depths. Standard and Turbo check several data sources in sequence for the same person, an approach usually called waterfall enrichment; Lite is a shallower, cheaper lookup.
| Mode | Work email | Direct phone | Both | Use it when |
|---|---|---|---|---|
| Lite | 1 | 1 | 2 | Cost matters more than coverage |
| Standard | 2 | 3 | 5 | The default |
| Turbo | 3 | 5 | 8 | Speed matters, or Standard found nothing |
A reveal is charged only for the fields it finds: 2 credits for a work email, 3 for a direct phone, nothing when nothing is found.
Ask for both and you pay for both: 5 credits when a work email and direct phone come back together.
Lite uses a lower-yield lookup. Standard balances speed and coverage. Turbo prioritizes speed and uses a premium enrichment stack at a higher cost.
Enrich a list of up to 2,000 people in one call
Send a plain list of profile URLs in linkedinUrls. You get a taskId straight away and the work runs in the background. Credits are taken when you submit, once per unique person; repeats in your list are dropped and not charged, and anything not found is refunded when the task finishes.
curl -X POST https://api.descovo.com/v1/contacts/reveal/batch \
-H "Authorization: Bearer $DESCOVO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"linkedinUrls":["https://www.linkedin.com/in/janedoe","https://www.linkedin.com/in/johnroe"],"enrichmentTypes":{"getWorkEmails":true,"getPersonalEmails":false,"getPhoneNumbers":false}}'Poll until done is true. People come back as they finish, so a long list can be read page by page with nextCursor while the rest is still running. Polling is free. The bulk email finder page has a complete Python script.
No LinkedIn URL? Start from what you have
| You have | Route | Cost |
|---|---|---|
| A name and a company | /people/match | 2 credits per record |
| An email address | /lookup/email | 2 credits (lite: 1) |
| A phone number | /lookup/phone | 3 credits when found |
| Only a description of who you want | /people/search or /people/ask, see the people search API | 1 credit per result |
The same API is an MCP server for AI agents
The key that calls the REST API also works on the hosted MCP server at https://mcp.descovo.com/mcp. An agent in Claude Code or Cursor can search, narrow and reveal in one conversation, spending the same credits. Connect it in one command.
What a contact enrichment API will not do
- It will not find everyone. Some people have no email or phone that can be found, and you are not charged for them.
- It will not promise every address delivers. A single reveal can return an email with a status, and valid means it passed a deliverability check. Bulk results include only the emails that passed.
- It will not return people who have asked to be removed. Those requests are not charged.
- It will not send the email for you. Descovo returns data; outreach stays in your own tools.
Frequently asked questions
- What is a contact enrichment API?
- An API that takes a partial identifier for a person, such as a LinkedIn URL, an email address or a name and company, and returns fuller contact details: typically a work email and a direct phone number.
- How much does contact enrichment cost with Descovo?
- On Standard reveal, 2 credits for a work email and 3 for a direct phone, charged only when found. Plans start free with 500 credits, then $99 a month for 5,000 credits.
- Do I pay when no contact data is found?
- No. A reveal that finds nothing costs nothing, and in a bulk request anything not found is refunded when the task finishes.
- Is there a bulk contact enrichment endpoint?
- Yes. POST /contacts/reveal/batch accepts up to 2,000 LinkedIn URLs per request and returns a task ID; you collect results from the poll endpoint as people finish.
- What is waterfall enrichment, and does Descovo do it?
- Waterfall enrichment means checking several data sources in sequence for the same person instead of relying on one. Descovo's Standard and Turbo reveals work this way; Lite is a shallower, cheaper lookup.
- Can I use it from Python or Node?
- Yes. It is a JSON REST API with bearer-key auth, and the examples on this page run as written. An OpenAPI document is published at https://api.descovo.com/v1/openapi.json.
TRY IT
Make your first reveal in a minute.
A new account starts with 500 credits and no card. That is enough to find 250 work emails.