// PYTHON GUIDE
Contact enrichment API in Python: search, reveal and bulk with requests
Updated November 20, 2026
You can call the Descovo contact enrichment API from Python with the requests library and one bearer key; there is no SDK to install. This guide builds a small helper, counts and searches people, reveals a work email for 2 credits when found, runs a bulk job of up to 2,000 profiles, and handles the errors you will meet.
Set up: one key, one helper
Create a key in the dashboard, export it as DESCOVO_API_KEY, and install requests. Every route lives under https://api.descovo.com/v1 and takes Authorization: Bearer <key>. Every successful response has the same shape: data with the result, and credits with what the call cost.
import os
import requests
API = "https://api.descovo.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['DESCOVO_API_KEY']}"}
class DescovoError(Exception):
def __init__(self, status, code, message):
super().__init__(f"{status} {code}: {message}")
self.status, self.code = status, code
def call(method, path, body=None, timeout=120):
r = requests.request(method, f"{API}{path}", headers=HEADERS, json=body, timeout=timeout)
payload = r.json()
if r.status_code >= 400:
err = payload.get("error", {})
raise DescovoError(r.status_code, err.get("code"), err.get("message"))
return payload["data"], payload.get("credits", {})
balance, _ = call("GET", "/credits")
print("credits available:", balance["available"])GET https://api.descovo.com/v1/credits is free and returns your balance, so it is a safe first call to confirm the key works.
Count, then search
https://api.descovo.com/v1/people/count is free; https://api.descovo.com/v1/people/search costs 1 credit per person returned. The count comes back in totalProfilesFound, so you know what a search will cost before you run it. The company goes in top-level currentCompanies so the title must hold at that same job.
filters = {
"searchParams": {
"jobTitleV3": {"anyOf": [{"type": "plain", "term": "Account Executive"}]},
},
"currentCompanies": [{"domain": "ramp.com"}],
}
# 1. Count first. It is free.
count, _ = call("POST", "/people/count", filters)
print("matches:", count["totalProfilesFound"])
# 2. Then fetch only as many people as you will use. Each one is charged.
page, credits = call("POST", "/people/search", {**filters, "pageSize": 10})
people = page["data"]
print(len(people), "people for", credits.get("charged"), "credits")If you would rather describe people in a sentence, post {"query": "..."} to /people/ask instead: 2 credits to read the question plus 1 per result.
Reveal an email or phone for one person
https://api.descovo.com/v1/contacts/reveal takes a LinkedIn profile URL. Search results carry the person's slug in primary_slug; the URL is https://www.linkedin.com/in/<slug>. A work email costs 2 credits and a direct phone 3, and credits.charged is zero when nothing is found.
def reveal(linkedin_url, phone=False):
data, credits = call("POST", "/contacts/reveal", {
"linkedinUrl": linkedin_url,
"enrichmentType": {
"getWorkEmails": True,
"getPersonalEmails": False,
"getPhoneNumbers": phone,
},
})
return data, credits.get("charged", 0)
for person in people:
slug = person.get("primary_slug")
if not slug:
continue
data, charged = reveal(f"https://www.linkedin.com/in/{slug}")
print(person.get("name"), data, "charged:", charged)Run a bulk job for a list
For more than a handful of people, one call to https://api.descovo.com/v1/contacts/reveal/batch queues up to 2,000 profile URLs and returns a taskId. Credits are taken when you submit and anything not found is refunded when the job finishes. Polling is free.
import time
urls = [f"https://www.linkedin.com/in/{p['primary_slug']}" for p in people if p.get("primary_slug")]
task, _ = call("POST", "/contacts/reveal/batch", {
"linkedinUrls": urls[:2000],
"enrichmentTypes": {"getWorkEmails": True, "getPersonalEmails": False, "getPhoneNumbers": False},
})
# Wait for the job to finish (results can also be read while it runs).
while not call("POST", "/contacts/reveal/batch/poll", {"taskId": task["taskId"]})[0]["done"]:
time.sleep(5)
# Then read every page.
cursor = None
while True:
body = {"taskId": task["taskId"]}
if cursor:
body["cursor"] = cursor
page, _ = call("POST", "/contacts/reveal/batch/poll", body)
for row in page["pageResults"]:
emails = [e["email"] for e in (row.get("outputs") or {}).get("emails", [])]
print(row["inputs"]["linkedinUrl"]["value"], emails)
cursor = page.get("nextCursor")
if not cursor:
breakHandle the four errors that matter
| Status | Code | What to do |
|---|---|---|
| 400 | invalid_request | The body does not match the route, for example an unknown field. Fix it; nothing was charged |
| 401 | unauthorized | No key, or a revoked key |
| 402 | insufficient_credits | Out of credits. Stop and top up; retrying will not help |
| 429 | rate_limited | Too fast. Wait and retry |
try:
data, credits = call("POST", "/contacts/reveal", {"linkedinUrl": url, "enrichmentType": {"getWorkEmails": True}})
except DescovoError as e:
if e.status == 402: # insufficient_credits: stop, do not retry
raise SystemExit("Out of credits")
if e.status == 429: # rate_limited: wait, then retry
time.sleep(5)
elif e.status == 400: # invalid_request: fix the body; nothing was charged
raise
else:
raiseKeep spend predictable
- Count before you search, and set pageSize to the number of people you will actually use.
- Ask only for the fields you need. Leaving getPhoneNumbers false keeps a reveal at the email price.
- Read credits.charged on every response and stop when a budget is reached.
- Use the bulk endpoint for lists: misses are refunded and repeats in the list are dropped.
Frequently asked questions
- Is there a Descovo Python SDK?
- No. The API is plain HTTPS with JSON bodies and a bearer key, so the requests library is all you need. An OpenAPI document is published at https://api.descovo.com/v1/openapi.json if you want to generate a client.
- How do I authenticate from Python?
- Send the header Authorization: Bearer followed by your API key on every request. Keep the key in an environment variable such as DESCOVO_API_KEY rather than in code.
- How do I know what a call cost?
- Every successful response includes credits.charged, the credits that call used, and usually credits.available, your balance afterwards.
- What happens when I run out of credits?
- The API returns HTTP 402 with the code insufficient_credits. Retrying does not help; add credits or change plan first.
- Can I try this for free?
- Yes. A new account gets 500 credits once, with no card required. Plans start free with 500 credits, then $99 a month for 5,000 credits.
TRY IT
Run the first snippet.
A new account starts with 500 credits and no card. That is enough to find 250 work emails, or 100 people with both a work email and a direct phone.