Descovo

// 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.

client.py
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.

search.py
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.

reveal.py
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.

bulk.py
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:
        break

Handle the four errors that matter

HTTP errors and what to do
StatusCodeWhat to do
400invalid_requestThe body does not match the route, for example an unknown field. Fix it; nothing was charged
401unauthorizedNo key, or a revoked key
402insufficient_creditsOut of credits. Stop and top up; retrying will not help
429rate_limitedToo fast. Wait and retry
errors.py
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:
        raise

Keep 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.