Descovo

// REST API

REST API reference

Everything the hosted MCP server does, as plain HTTPS and JSON for pipelines, backends and scripts. Same API key, same credits. Agents can keep using https://mcp.descovo.com/mcp.

Basics

Base URL
https://api.descovo.com/v1
Auth
Authorization: Bearer <key> (or an x-api-key header). Create keys on the API Keys page.
Format
JSON request bodies on POST; every response is JSON.
Billing
Each response says what it charged in credits.charged (and the balance in credits.available when reported). Counts and the balance are free.
first request
curl -X POST https://api.descovo.com/v1/people/search \
  -H "Authorization: Bearer $DESCOVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"searchParams":{"jobTitleV3":{"anyOf":[{"type":"plain","term":"Account Executive"}]}},"currentCompanies":[{"domain":"ramp.com"}],"pageSize":10}'
200 response
{
  "data": { ... },
  "credits": { "charged": 10, "available": 4990 }
}
error response
{
  "error": {
    "code": "unauthorized",
    "message": "Send your API key in the x-api-key header (or Authorization: Bearer <key>). Create one at https://descovo.com/app/keys."
  }
}
  • 400invalid_request / invalid_jsonThe body doesn’t match the route. fields lists each problem.
  • 401unauthorizedNo key, or a key that was revoked.
  • 402insufficient_creditsOut of credits. Top up or change plan on the Billing page.
  • 404not_foundNo such route. GET /v1 lists them all.
  • 429rate_limitedToo fast. Read x-ratelimit-reset and retry after it.

Search

POST/v1/people/countCount people

How many people match the same filters, without loading anyone.

Cost: Free

POST/v1/companies/countCount companies

Matches for company filters.

Cost: Free

POST/v1/people/askAsk in plain English (people)

Describe who you want; Descovo turns it into filters and runs the search.

Cost: 2 credits + 1 per result

POST /v1/people/ask
curl -X POST https://api.descovo.com/v1/people/ask \
  -H "Authorization: Bearer $DESCOVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Heads of data at fintech companies in New York","pageSize":10}'
POST/v1/companies/askAsk in plain English (companies)

Same, for companies.

Cost: 2 credits + 1 per result

Contacts

POST/v1/contacts/revealReveal email and phone

Work email, personal email and direct phone for a LinkedIn profile. Charged only for fields found. Add "mode": "lite" or "turbo" for the other reveal depths.

Cost: 2 per work email, 3 per phone, 5 for both (lite: 1 per field)

POST /v1/contacts/reveal
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":false},"validateEmails":true}'
POST/v1/contacts/reveal/batchReveal a list of people

Send up to 2,000 LinkedIn URLs and get their emails and phones back. Returns a taskId right away and runs in the background; charged per unique person, and anything not found is refunded when the task finishes.

Cost: 2 per work email, 3 per phone, 5 for both — per person found, misses refunded

POST /v1/contacts/reveal/batch
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}}'
POST/v1/contacts/reveal/batch/pollGet list reveal results

Collect a list reveal by its taskId. People come back as they finish; page with nextCursor until done is true.

Cost: Free

POST /v1/contacts/reveal/batch/poll
curl -X POST https://api.descovo.com/v1/contacts/reveal/batch/poll \
  -H "Authorization: Bearer $DESCOVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"taskId":"the-taskId-from-reveal-batch"}'
POST/v1/emails/verifyVerify an email

Deliverability check for one address.

Cost: 1 credit

POST /v1/emails/verify
curl -X POST https://api.descovo.com/v1/emails/verify \
  -H "Authorization: Bearer $DESCOVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"someone@example.com"}'
POST/v1/lookup/emailFind the person behind an email

Email in, profile out. Add "mode": "lite" for a lighter, cheaper lookup.

Cost: 2 credits (lite: 1)

POST /v1/lookup/email
curl -X POST https://api.descovo.com/v1/lookup/email \
  -H "Authorization: Bearer $DESCOVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"someone@example.com"}'
POST/v1/lookup/phoneFind the person or company behind a phone

Phone in, profile or company out. Free when nothing is found.

Cost: 3 credits when found

POST /v1/lookup/phone
curl -X POST https://api.descovo.com/v1/lookup/phone \
  -H "Authorization: Bearer $DESCOVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"+14155550100"}'

Match and enrich

POST/v1/people/matchMatch a person

Send whatever you have (name, company, email, title, LinkedIn) and get the best-matching profile back. Free when nothing matches.

Cost: 2 credits per profile returned

POST /v1/people/match
curl -X POST https://api.descovo.com/v1/people/match \
  -H "Authorization: Bearer $DESCOVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"personName":{"value":"Satya Nadella"},"companyDomain":{"value":"microsoft.com"}}'
POST/v1/companies/matchMatch a company

Name, domain or LinkedIn in; the company record out.

Cost: 2 credits per company returned

POST /v1/companies/match
curl -X POST https://api.descovo.com/v1/companies/match \
  -H "Authorization: Bearer $DESCOVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"companyDomain":{"value":"ramp.com"}}'
POST/v1/people/enrichLive profile

Fetch a LinkedIn profile as it is right now, by slug.

Cost: 2 credits

POST /v1/people/enrich
curl -X POST https://api.descovo.com/v1/people/enrich \
  -H "Authorization: Bearer $DESCOVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"satyanadella"}'
POST/v1/companies/enrichLive company

Fetch a LinkedIn company page as it is right now.

Cost: 2 credits

POST /v1/companies/enrich
curl -X POST https://api.descovo.com/v1/companies/enrich \
  -H "Authorization: Bearer $DESCOVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"slug","value":"stripe"}'

Account

GET/v1/creditsCredit balance

Available, used, limit and the reset date.

Cost: Free

GET/v1Route index

Every route this API serves.

Cost: Free

GET/v1/openapi.jsonOpenAPI spec

Machine-readable schema for every route.

Cost: Free

Full request and response schemas for every route are in openapi.json. Need higher limits or volume pricing? Talk to us.