# Descovo REST API reference

> Base URL https://api.descovo.com/v1. JSON in, JSON out. Authenticate with `Authorization: Bearer <key>` (or an `x-api-key` header). The same key and the same credits work on the MCP server.

Source page: https://descovo.com/docs/rest
OpenAPI document: https://api.descovo.com/v1/openapi.json

## Conventions

- Every response is `{"data": ..., "credits": {"charged": n, "available": n}}`; errors are `{"error": {"code", "message"}}`.
- A body field the route does not know is rejected with HTTP 400 and is not charged.
- Search costs 1 credit per profile, company, or job returned; count queries are free.
- 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.
- Create a key at https://descovo.com/app/keys. New accounts start with 500 credits.

## Search

### Search people

`POST https://api.descovo.com/v1/people/search`

Filter by title, company, seniority, function, industry, location and more. Put the company in top-level currentCompanies so the title must hold at that same job. Pages with a cursor.

Cost: 1 credit per person returned.

```bash
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}'
```

### Count people

`POST https://api.descovo.com/v1/people/count`

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

Cost: Free.

### Search companies

`POST https://api.descovo.com/v1/companies/search`

Filter by name, domain, headcount, industry, location and technology.

Cost: 1 credit per company returned.

```bash
curl -X POST https://api.descovo.com/v1/companies/search \
  -H "Authorization: Bearer $DESCOVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"searchParams":{"domains":["ramp.com"]},"pageSize":1}'
```

### Count companies

`POST https://api.descovo.com/v1/companies/count`

Matches for company filters.

Cost: Free.

### Search job postings

`POST https://api.descovo.com/v1/jobs/search`

Open roles by title, company and location.

Cost: 1 credit per posting returned.

```bash
curl -X POST https://api.descovo.com/v1/jobs/search \
  -H "Authorization: Bearer $DESCOVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"searchParams":{"companies":{"identifier":"domain","value":["stripe.com"]}},"pageSize":5}'
```

### Ask in plain English (people)

`POST https://api.descovo.com/v1/people/ask`

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

Cost: 2 credits + 1 per result.

```bash
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}'
```

### Ask in plain English (companies)

`POST https://api.descovo.com/v1/companies/ask`

Same, for companies.

Cost: 2 credits + 1 per result.

## Contacts

### Reveal email and phone

`POST https://api.descovo.com/v1/contacts/reveal`

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

```bash
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}'
```

### Reveal a list of people

`POST https://api.descovo.com/v1/contacts/reveal/batch`

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.

```bash
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}}'
```

### Get list reveal results

`POST https://api.descovo.com/v1/contacts/reveal/batch/poll`

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

Cost: Free.

```bash
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"}'
```

### Verify an email

`POST https://api.descovo.com/v1/emails/verify`

Deliverability check for one address.

Cost: 1 credit.

```bash
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"}'
```

### Find the person behind an email

`POST https://api.descovo.com/v1/lookup/email`

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

Cost: 2 credits (lite: 1).

```bash
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"}'
```

### Find the person or company behind a phone

`POST https://api.descovo.com/v1/lookup/phone`

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

Cost: 3 credits when found.

```bash
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

### Match a person

`POST https://api.descovo.com/v1/people/match`

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.

```bash
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"}}'
```

### Match a company

`POST https://api.descovo.com/v1/companies/match`

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

Cost: 2 credits per company returned.

```bash
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"}}'
```

### Live profile

`POST https://api.descovo.com/v1/people/enrich`

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

Cost: 2 credits.

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

### Live company

`POST https://api.descovo.com/v1/companies/enrich`

Fetch a LinkedIn company page as it is right now.

Cost: 2 credits.

```bash
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

### Credit balance

`GET https://api.descovo.com/v1/credits`

Available, used, limit and the reset date.

Cost: Free.

```bash
curl https://api.descovo.com/v1/credits \
  -H "Authorization: Bearer $DESCOVO_API_KEY"
```

### Route index

`GET https://api.descovo.com/v1`

Every route this API serves.

Cost: Free.

```bash
curl https://api.descovo.com/v1 \
  -H "Authorization: Bearer $DESCOVO_API_KEY"
```

### OpenAPI spec

`GET https://api.descovo.com/v1/openapi.json`

Machine-readable schema for every route.

Cost: Free.

```bash
curl https://api.descovo.com/v1/openapi.json \
  -H "Authorization: Bearer $DESCOVO_API_KEY"
```
