Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.descovo.com/llms.txt

Use this file to discover all available pages before exploring further.

Audiences are the foundation of Descovo’s scale enrichment workflows. An audience is a saved list of companies and prospects that you build once from search filters, then enrich and export without needing to hold thousands of records in memory. Follow the seven steps below in order — skipping steps or changing audience state out of sequence causes 400 errors.
Steps 3 and 5 charge credits. Always check your credit balance before calling the build or enrich endpoints. Use the estimate endpoint (Step 4) to preview costs before committing.

​
The workflow at a glance

1

Create an audience

2

Set search filters

3

Build the audience (charges credits)

4

Estimate enrichment cost (free)

5

Trigger enrichment (charges credits)

6

Poll enrichment status (free)

7

Export results (free)

​
Step 1: Create an audience

Create an empty audience. This is free and puts the audience in DRAFT status. Endpoint: POST /v1/audiences/create
​
apiKey
string
required
Your Descovo API key.
​
name
string
required
A descriptive name for the audience, e.g. "AI VPs in US".
​
creationMethod
string
default:"NORMAL"
How the audience should be built:
  • "NORMAL" — search companies first, then find prospects at those companies (typical use case)
  • "START_FROM_PROSPECTS" — search prospects directly without a company filter
{
  "apiKey": "sk_live_xxx",
  "name": "AI VPs in US",
  "creationMethod": "NORMAL"
}
Save the audienceId — you’ll use it for every subsequent step.

​
Step 2: Set search filters

Define the company and prospect filters for your audience. This is free and only allowed while the audience is in DRAFT status. Endpoint: PATCH /v1/audiences/{audienceId}/search-params
​
apiKey
string
required
Your Descovo API key.
​
companySearchParams
object
Company filters using the same schema as Company Search. Applies when creationMethod is "NORMAL".
​
prospectSearchParams
object
People filters using the same schema as People Search.
​
maxCompanies
number
default:"1000"
Maximum number of companies to include in the audience.
​
maxProspects
number
default:"10000"
Maximum number of prospects to include in the audience.
{
  "apiKey": "sk_live_xxx",
  "companySearchParams": {
    "keywords": ["artificial intelligence", "machine learning"],
    "headquartersCountryCode": ["US"],
    "employeeCountV2": {
      "min": 50,
      "max": 1000
    },
    "industriesV2": ["artificial-intelligence"],
    "stage": ["SEED", "SERIES_A", "SERIES_B"]
  },
  "prospectSearchParams": {
    "jobTitleV2": {
      "included": ["VP Engineering", "VP of Engineering", "Head of Engineering"],
      "excluded": ["Recruiter", "HR"]
    },
    "country3LetterCode": ["USA"],
    "yearsOfExperience": {
      "min": 5
    }
  },
  "maxCompanies": 1000,
  "maxProspects": 10000
}
You can only set search params while the audience is in DRAFT. If you receive a 400 because the audience has already been built, create a new audience and start over.

​
Step 3: Build the audience

Trigger the search and save the results to the audience. This transitions the status from DRAFT to BUILDING, then to NORMAL once complete. Endpoint: POST /v1/audiences/{audienceId}/build
This step charges credits. Companies cost 1 credit each; prospects cost 1 credit each. Credits are charged after the build completes based on actual results found.
​
apiKey
string
required
Your Descovo API key.
{
  "apiKey": "sk_live_xxx"
}
Poll GET /v1/audiences/aud_123?apiKey=sk_live_xxx until status is NORMAL before proceeding to enrichment.
If you receive a 400 because the audience is already BUILDING, poll the status endpoint instead of retrying the build. If the status is FAILED, create a new audience.

​
Step 4: Estimate enrichment cost

Before committing credits to enrichment, request a cost and time estimate. This is always free. Endpoint: POST /v1/audiences/{audienceId}/enrichment/estimate
​
apiKey
string
required
Your Descovo API key.
​
maxProspectsToEnrich
number
Cap the number of prospects to enrich. Useful for reducing cost on large audiences.
​
enrichmentType
object
Which contact data to retrieve (getWorkEmails, getPersonalEmails, getPhoneNumbers).
​
runCompanyLiveEnrichment
boolean
Whether to run live company enrichment for companies in the audience.
​
runProfileLiveEnrichment
boolean
Whether to run live profile enrichment for prospects in the audience.
​
runProfileSalesNav
boolean
Whether to run Sales Navigator enrichment (free when available).
​
runContactEnrichment
boolean
Whether to run contact reveal (email and phone).
{
  "apiKey": "sk_live_xxx",
  "maxProspectsToEnrich": 5000,
  "enrichmentType": {
    "getWorkEmails": true,
    "getPersonalEmails": false,
    "getPhoneNumbers": true
  },
  "runCompanyLiveEnrichment": true,
  "runProfileLiveEnrichment": true,
  "runProfileSalesNav": true,
  "runContactEnrichment": true
}
Show the user totalCredits and timeEstimate.formatted and ask for explicit confirmation before proceeding. If the estimate is too high, they can reduce maxProspectsToEnrich or disable some enrichment types.

​
Step 5: Trigger enrichment

Once the user confirms the estimate, start the enrichment run. Credits are charged upfront. Endpoint: POST /v1/audiences/{audienceId}/enrich
This step charges credits upfront based on the estimate. Only call this after the user has explicitly confirmed the cost.
​
apiKey
string
required
Your Descovo API key.
​
maxProspectsToEnrich
number
Must match the value used in your estimate.
​
enrichmentType
object
Must match the configuration used in your estimate.
​
runCompanyLiveEnrichment
boolean
Whether to run live company enrichment.
​
runProfileLiveEnrichment
boolean
Whether to run live profile enrichment.
​
runProfileSalesNav
boolean
Whether to run Sales Navigator enrichment.
​
runContactEnrichment
boolean
Whether to run contact reveal.
​
userEmail
string
If provided, Descovo sends an email notification when enrichment completes.
{
  "apiKey": "sk_live_xxx",
  "maxProspectsToEnrich": 5000,
  "enrichmentType": {
    "getWorkEmails": true,
    "getPersonalEmails": false,
    "getPhoneNumbers": true
  },
  "runCompanyLiveEnrichment": true,
  "runProfileLiveEnrichment": true,
  "runProfileSalesNav": true,
  "runContactEnrichment": true,
  "userEmail": "you@example.com"
}
Save the enrichmentId alongside the audienceId to track progress in the next step.

​
Step 6: Poll enrichment status

Check the enrichment progress until it completes. Polling is free. Endpoint: GET /v1/audiences/{audienceId}/enrichment/status Auth: Pass your API key as a query parameter: ?apiKey=sk_live_xxx 
GET /v1/audiences/aud_123/enrichment/status?apiKey=sk_live_xxx
Response
{
  "output": {
    "enrichmentId": "enr_789",
    "currentStage": "FETCHING_CONTACT_DETAILS",
    "progressPercent": 60,
    "stepsCompleted": [
      "Initialization",
      "Sales Navigator Enrichment",
      "Live Enrichment",
      "Resubmitting Audience",
      "Cleaning Names",
      "Fetching Contact Details"
    ],
    "currentStep": "Fetching Contact Details",
    "stepsRemaining": [
      "Validating Contact Details",
      "Exporting CSV",
      "Completed"
    ],
    "createdAt": "2026-01-20T12:45:00.000Z",
    "completedAt": null
  },
  "chargeInfo": {
    "method": "free",
    "message": "Checking enrichment status is free."
  }
}
Poll every ~30 seconds. Enrichment is complete when progressPercent reaches 100 or currentStage is "DONE".
Surface progress to users with a short update like: “Enrichment is 60% complete — fetching contact details.” This keeps them informed during longer runs without overwhelming them with raw JSON.

​
Step 7: Export results

Once enrichment is complete, export companies or prospects as CSV. Exports are free but subject to account export quotas.
Endpoint: POST /v1/audiences/{audienceId}/export/prospects
​
apiKey
string
required
Your Descovo API key.
​
format
string
default:"PROSPECT_GENERIC_CSV"
Export format. Use "PROSPECT_GENERIC_CSV" for a standard CSV.
​
onlyWithContacts
boolean
default:"false"
When true, only include prospects where at least one email or phone number was found.
​
maxRowsToExport
number
Maximum number of rows to include in the export.
​
excludeFields
string[]
Field names to omit from the export.
​
userEmail
string
If provided, Descovo emails download links when the export is ready.
{
  "apiKey": "sk_live_xxx",
  "format": "PROSPECT_GENERIC_CSV",
  "onlyWithContacts": true,
  "maxRowsToExport": 10000,
  "excludeFields": [],
  "userEmail": "you@example.com"
}
Always include userEmail so you receive download links by email, even if the session ends before the export completes.

​
Common errors

ErrorCauseResolution
401 Invalid API keyThe apiKey value is missing or incorrectProvide a valid Descovo API key and retry
404 Audience not foundThe audienceId is wrong or belongs to a different accountVerify the audience ID; create a new audience if needed
400 Invalid status for operationAttempted build or filter change on a non-DRAFT audience; attempted enrichment on a non-NORMAL audienceCheck the current audience status and take the appropriate next action (poll if building, create a new audience if failed)
429 Rate limitedToo many requests in a short periodWait before retrying; do not retry in a tight loop