Audience API endpoints: create, build, enrich, export

Audiences are saved lists of companies and prospects. You define search filters, build the audience to populate it from Descovo’s database, optionally enrich contact details, and then export the results as a CSV. The workflow follows a fixed sequence of nine steps — skipping or reordering them causes validation errors. This page documents each endpoint in order, with request parameters, response fields, and examples.

Always follow the steps in sequence: create → set filters → build → poll status → estimate enrichment → enrich → poll enrichment → export. Attempting to build before setting filters, or enriching before building, returns a 400 error.

Step 1: Create audience

Create an empty audience in DRAFT status. No credits are charged at this step. Method: POST
Path: /v1/audiences/create
Auth: apiKey in body

Parameters

apiKey

string

required

Your Descovo API key.

name

string

required

A display name for this audience, e.g. "AI VPs in US".

creationMethod

string

default:"NORMAL"

How the audience searches for prospects. "NORMAL" searches companies first, then finds prospects within those companies. "START_FROM_PROSPECTS" searches prospects only, without a company filter step.

Example

{
  "apiKey": "sk_live_xxx",
  "name": "Seed-stage AI VPs in US",
  "creationMethod": "NORMAL"
}

Response

{
  "output": {
    "audienceId": "aud_123",
    "name": "Seed-stage AI VPs in US",
    "status": "DRAFT",
    "audienceSearchLogicId": "asl_456",
    "createdAt": "2026-01-20T12:34:56.000Z"
  },
  "chargeInfo": {
    "method": "free",
    "message": "Creating an audience is free. Credits are charged when you build the audience."
  }
}

Save the audienceId — you need it for every subsequent step.

Attach company and prospect filter criteria to the audience. You can only do this while the audience is in DRAFT status. Method: PATCH
Path: /v1/audiences/{audienceId}/search-params
Auth: apiKey in body

Parameters

apiKey

string

required

Your Descovo API key.

companySearchParams

object

Company filters using the same schema as company search. Supports keywords, headquartersCountryCode, employeeCountV2, industriesV2, stage, and all other company search fields.

prospectSearchParams

object

People filters using the same schema as people search. Supports jobTitleV2, country3LetterCode, yearsOfExperience, tags, and all other people search fields.

maxCompanies

number

default:"1000"

Maximum number of companies to include in the audience build.

maxProspects

number

default:"10000"

Maximum number of prospects to include in the audience build.

Example

{
  "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
}

Response

{
  "output": {
    "audienceId": "aud_123",
    "audienceSearchLogicId": "asl_456",
    "companySearchParams": { "...": "echo of your filters" },
    "prospectSearchParams": { "...": "echo of your filters" }
  },
  "chargeInfo": {
    "method": "free",
    "message": "Updating search parameters is free."
  }
}

Returns 400 if the audience is not in DRAFT status. If you need different filters after building, create a new audience.

Step 3: Build audience

Trigger the audience build. Descovo runs the company and people searches and saves the results to the audience. The audience transitions from DRAFT to BUILDING, then to NORMAL (or FAILED) when complete. Credits are charged per result found after the build completes. Method: POST
Path: /v1/audiences/{audienceId}/build
Auth: apiKey in body

Parameters

apiKey

string

required

Your Descovo API key.

Example

{
  "apiKey": "sk_live_xxx"
}

Response

{
  "output": {
    "audienceId": "aud_123",
    "status": "BUILDING",
    "message": "Audience build started. Use the get-audience-status endpoint to poll for completion."
  },
  "chargeInfo": {
    "method": "charging-later",
    "message": "Credits will be charged based on companies and profiles found."
  }
}

Credit behavior: 1 credit per company found, 1 credit per prospect found. Credits are deducted after the build completes. Error codes:

400 — audience is already BUILDING (poll status instead), already NORMAL (create a new audience for new filters), or FAILED (create a new audience).

Step 4: Poll audience status

Poll to check whether the audience build has completed before proceeding to enrichment. Method: GET
Path: /v1/audiences/{audienceId}
Auth: apiKey as query parameter

Example request

GET https://api.descovo.com/v1/audiences/aud_123?apiKey=sk_live_xxx

Response

{
  "output": {
    "audienceId": "aud_123",
    "name": "Seed-stage AI VPs in US",
    "status": "NORMAL",
    "numCompanies": 284,
    "numProspects": 1840,
    "createdAt": "2026-01-20T12:34:56.000Z"
  },
  "chargeInfo": {
    "method": "free"
  }
}

Poll every 30–60 seconds until status is "NORMAL". If status becomes "FAILED", create a new audience and retry.

Step 5: Estimate enrichment cost

Get a free cost and time estimate before triggering enrichment. Always call this step and show the estimate to users before proceeding. Method: POST
Path: /v1/audiences/{audienceId}/enrichment/estimate
Auth: apiKey in body
Cost: Free

Parameters

apiKey

string

required

Your Descovo API key.

maxProspectsToEnrich

number

Cap the number of prospects to include in enrichment. Useful for controlling cost on large audiences.

enrichmentType

object

Which contact data types to request.

Show properties

enrichmentType.getWorkEmails

boolean

Retrieve work emails.

enrichmentType.getPersonalEmails

boolean

Retrieve personal emails.

enrichmentType.getPhoneNumbers

boolean

Retrieve phone numbers.

runCompanyLiveEnrichment

boolean

Include live LinkedIn enrichment for companies in the audience.

runProfileLiveEnrichment

boolean

Include live LinkedIn enrichment for prospect profiles.

runProfileSalesNav

boolean

Include Sales Navigator data for prospects.

runContactEnrichment

boolean

Include contact enrichment (emails and phones).

Example

{
  "apiKey": "sk_live_xxx",
  "maxProspectsToEnrich": 5000,
  "enrichmentType": {
    "getWorkEmails": true,
    "getPersonalEmails": false,
    "getPhoneNumbers": true
  },
  "runCompanyLiveEnrichment": true,
  "runProfileLiveEnrichment": true,
  "runProfileSalesNav": true,
  "runContactEnrichment": true
}

Response

{
  "output": {
    "totalCredits": 22000,
    "breakdown": {
      "salesNav": { "credits": 0, "isFree": true },
      "liveCompany": { "credits": 0, "discounted": true },
      "liveProspect": { "credits": 5000, "discounted": false },
      "waterfall": {
        "credits": 14000,
        "originalCredits": 16000,
        "discount": 2000,
        "operations": {
          "workEmail": 8000,
          "personalEmail": 0,
          "phone": 6000
        }
      },
      "validation": { "credits": 0, "isFree": true }
    },
    "timeEstimate": {
      "totalSeconds": 1800,
      "formatted": "30 minutes"
    }
  },
  "chargeInfo": {
    "method": "free"
  }
}

Show totalCredits and timeEstimate.formatted to your users and get explicit confirmation before proceeding to Step 6. To reduce cost, lower maxProspectsToEnrich or disable enrichment types you do not need.

Step 6: Trigger enrichment

Start the enrichment job. Credits are charged upfront. Only trigger this after the user has confirmed the estimate from Step 5. Method: POST
Path: /v1/audiences/{audienceId}/enrich
Auth: apiKey in body

Parameters

apiKey

string

required

Your Descovo API key.

maxProspectsToEnrich

number

Maximum prospects to enrich. Match the value used in your estimate.

enrichmentType

object

Contact data types to request. Match the values used in your estimate.

runCompanyLiveEnrichment

boolean

Run live LinkedIn enrichment for companies.

runProfileLiveEnrichment

boolean

Run live LinkedIn enrichment for prospect profiles.

runProfileSalesNav

boolean

Include Sales Navigator data.

runContactEnrichment

boolean

Run contact enrichment (emails and phones).

userEmail

string

Optional email address. If provided, Descovo sends a notification when enrichment completes.

Example

{
  "apiKey": "sk_live_xxx",
  "maxProspectsToEnrich": 5000,
  "enrichmentType": {
    "getWorkEmails": true,
    "getPersonalEmails": false,
    "getPhoneNumbers": true
  },
  "runCompanyLiveEnrichment": true,
  "runProfileLiveEnrichment": true,
  "runProfileSalesNav": true,
  "runContactEnrichment": true,
  "userEmail": "user@example.com"
}

Response

{
  "output": {
    "enrichmentId": "enr_789",
    "status": "NOT_STARTED",
    "estimatedCredits": 22000
  },
  "chargeInfo": {
    "method": "charged-now",
    "message": "Credits were charged upfront for this enrichment."
  }
}

Save enrichmentId along with your audienceId — you need both to poll enrichment status.

Step 7: Poll enrichment status

Poll to track enrichment progress until it completes. Method: GET
Path: /v1/audiences/{audienceId}/enrichment/status
Auth: apiKey as query parameter
Cost: Free

Example request

GET https://api.descovo.com/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 until progressPercent reaches 100 or currentStage indicates completion.

Step 8: Export companies

Export the companies in the audience to CSV. This step is free. Method: POST
Path: /v1/audiences/{audienceId}/export/companies
Auth: apiKey in body
Cost: Free (subject to export quota)

Parameters

apiKey

string

required

Your Descovo API key.

format

string

default:"COMPANY_GENERIC_CSV"

Export format. Use "COMPANY_GENERIC_CSV" for a standard company CSV.

maxRowsToExport

number

Maximum number of company rows to include in the export.

excludeFields

string[]

Field names to omit from the export, e.g. ["internalId"].

userEmail

string

Optional email address. Descovo sends a download link to this address when the export is ready.

Example

{
  "apiKey": "sk_live_xxx",
  "format": "COMPANY_GENERIC_CSV",
  "maxRowsToExport": 5000,
  "excludeFields": ["internalId"],
  "userEmail": "user@example.com"
}

Response

{
  "output": {
    "exportId": "exp_001",
    "message": "Export scheduled. You will receive an email with download links.",
    "estimatedRows": 4200,
    "maxRowsAllowed": 10000
  },
  "chargeInfo": {
    "method": "free",
    "message": "Exports are free but subject to quota."
  }
}

Step 9: Export prospects

Export the enriched prospects in the audience to CSV. This step is free. Method: POST
Path: /v1/audiences/{audienceId}/export/prospects
Auth: apiKey in body
Cost: Free (subject to export quota)

Parameters

apiKey

string

required

Your Descovo API key.

format

string

default:"PROSPECT_GENERIC_CSV"

Export format. Use "PROSPECT_GENERIC_CSV" for a standard prospect CSV.

onlyWithContacts

boolean

default:"false"

When true, only exports prospects for whom at least one contact detail (email or phone) was found.

maxRowsToExport

number

Maximum number of prospect rows to include in the export.

excludeFields

string[]

Field names to omit from the export.

userEmail

string

Optional email address for download link delivery.

Example

{
  "apiKey": "sk_live_xxx",
  "format": "PROSPECT_GENERIC_CSV",
  "onlyWithContacts": true,
  "maxRowsToExport": 10000,
  "excludeFields": [],
  "userEmail": "user@example.com"
}

Response

{
  "output": {
    "exportId": "exp_002",
    "message": "Export scheduled. You will receive an email with download links.",
    "estimatedRows": 3800,
    "maxRowsAllowed": 10000
  },
  "chargeInfo": {
    "method": "free",
    "message": "Exports are free but subject to quota."
  }
}

Provide a userEmail on export requests so users receive download links by email, even if the session ends before the export finishes.

Common error codes

Code	Cause	Resolution
`401`	Invalid or missing API key	Check your `apiKey` value and retry.
`400`	Invalid audience status for the requested operation	Check the current status with Step 4 (poll status) and follow the valid next action.
`404`	Audience not found or access denied	Confirm the `audienceId` is correct. Create a new audience if needed.
`429`	Rate limit exceeded	Back off and retry after a delay.

Overview

Endpoints

Audience API endpoints: create, build, enrich, export

Step 1: Create audience

Parameters

Example

Response

Step 2: Set search filters

Parameters

Example

Response

Step 3: Build audience

Parameters

Example

Response

Step 4: Poll audience status

Example request

Response

Step 5: Estimate enrichment cost

Parameters

Example

Response

Step 6: Trigger enrichment

Parameters

Example

Response

Step 7: Poll enrichment status

Example request

Response

Step 8: Export companies

Parameters

Example

Response

Step 9: Export prospects

Parameters

Example

Response

Common error codes

Overview

Endpoints

Documentation Index

​Step 1: Create audience

​Parameters

​Example

​Response

​Step 2: Set search filters

​Parameters

​Example

​Response

​Step 3: Build audience

​Parameters

​Example

​Response

​Step 4: Poll audience status

​Example request

​Response

​Step 5: Estimate enrichment cost

​Parameters

​Example

​Response

​Step 6: Trigger enrichment

​Parameters

​Example

​Response

​Step 7: Poll enrichment status

​Example request

​Response

​Step 8: Export companies

​Parameters

​Example

​Response

​Step 9: Export prospects

​Parameters

​Example

​Response

​Common error codes

Step 1: Create audience

Parameters

Example

Response

Step 2: Set search filters

Parameters

Example

Response

Step 3: Build audience

Parameters

Example

Response

Step 4: Poll audience status

Example request

Response

Step 5: Estimate enrichment cost

Parameters

Example

Response

Step 6: Trigger enrichment

Parameters

Example

Response

Step 7: Poll enrichment status

Example request

Response

Step 8: Export companies

Parameters

Example

Response

Step 9: Export prospects

Parameters

Example

Response

Common error codes