Contact enrichment endpoints: sync, batch, and audience

Contact enrichment lets you retrieve verified work emails, personal emails, and phone numbers for people in your prospect list. Descovo offers three patterns depending on the scale of your use case: a synchronous single-profile endpoint for quick lookups, an async batch endpoint for large lists, and audience-based enrichment when you want to process an entire saved segment. Credits are charged per data point successfully returned — if no email or phone is found for a profile, you are not charged.

Sync
Batch start
Batch poll

Sync contact enrichment

Use the sync endpoint when you need contact data for a single LinkedIn profile and want the result immediately in the response.Endpoint: POST https://api.descovo.com/v1/individual-reveal/sync
Auth: apiKey in the request body
Credit behavior: Charged immediately per data type found

Request parameters

apiKey

string

required

Your Descovo API key.

linkedinUrl

string

required

The full LinkedIn profile URL of the person to enrich. Example: "https://www.linkedin.com/in/example-profile/".

enrichmentTypes

object

required

Which contact data types to request. Set each to true or false.

Show properties

enrichmentTypes.getWorkEmails

boolean

default:"false"

Retrieve verified work email addresses.

enrichmentTypes.getPersonalEmails

boolean

default:"false"

Retrieve personal email addresses.

enrichmentTypes.getPhoneNumbers

boolean

default:"false"

Retrieve phone numbers.

Response fields

output

object

Hide properties

output.linkedinUrl

string

The LinkedIn URL that was enriched.

output.workEmails

string[]

Found work email addresses. Empty array if none found or not requested.

output.personalEmails

string[]

Found personal email addresses. Empty array if none found or not requested.

output.phoneNumbers

string[]

Found phone numbers. Empty array if none found or not requested.

chargeInfo

object

Show properties

chargeInfo.method

string

charged-now — credits are deducted immediately.

chargeInfo.creditsCharged

number

Total credits deducted for this enrichment.

Example

Request:

{
  "apiKey": "sk_live_xxx",
  "linkedinUrl": "https://www.linkedin.com/in/example-profile/",
  "enrichmentTypes": {
    "getWorkEmails": true,
    "getPersonalEmails": false,
    "getPhoneNumbers": true
  }
}

Response:

{
  "output": {
    "linkedinUrl": "https://www.linkedin.com/in/example-profile/",
    "workEmails": ["person@company.com"],
    "personalEmails": [],
    "phoneNumbers": ["+1-555-123-4567"]
  },
  "chargeInfo": {
    "method": "charged-now",
    "creditsCharged": 5
  }
}

Use sync enrichment for 1–5 profiles where you need results inline. For more than ~10 profiles, use the batch endpoint instead.

Batch contact enrichment — start

Use the batch endpoint to enrich a large list of LinkedIn profiles in a single async job. You submit up to 10,000 profiles, and Descovo processes them in the background. Credits are charged upfront based on unique, deduplicated profiles.Endpoint: POST https://api.descovo.com/v1/contact-enrich/batch/start
Auth: apiKey in the request body
Credit behavior: Charged immediately when the job starts, based on unique profiles after deduplication
Max profiles: 10,000 per batch (duplicates are deduplicated automatically)

Request parameters

apiKey

string

required

Your Descovo API key.

enrichmentTypes

object

required

Which contact data types to request for each person.

Show properties

enrichmentTypes.getWorkEmails

boolean

default:"false"

Retrieve verified work email addresses.

enrichmentTypes.getPersonalEmails

boolean

default:"false"

Retrieve personal email addresses.

enrichmentTypes.getPhoneNumbers

boolean

default:"false"

Retrieve phone numbers.

personDetails

object[]

required

Array of people to enrich. Each entry must include a LinkedIn URL.

Show personDetails item properties

personDetails[].linkedinUrl

string

required

Full LinkedIn profile URL, e.g. "https://www.linkedin.com/in/example-1/".

Response fields

output

object

Hide properties

output.taskId

string

ID for this batch job. Use it to poll for results with the batch poll endpoint.

output.numPeopleEnqueued

number

Number of unique profiles queued for enrichment after deduplication.

output.numDuplicatesSkipped

number

Number of duplicate entries that were removed before queuing.

chargeInfo

object

Show properties

chargeInfo.method

string

charged-now — credits are deducted when the batch starts.

chargeInfo.creditsCharged

number

Total credits charged for this batch.

Example

Request:

{
  "apiKey": "sk_live_xxx",
  "enrichmentTypes": {
    "getWorkEmails": true,
    "getPersonalEmails": true,
    "getPhoneNumbers": false
  },
  "personDetails": [
    { "linkedinUrl": "https://www.linkedin.com/in/example-1/" },
    { "linkedinUrl": "https://www.linkedin.com/in/example-2/" }
  ]
}

Response:

{
  "output": {
    "taskId": "aud_abc123",
    "numPeopleEnqueued": 2,
    "numDuplicatesSkipped": 0
  },
  "chargeInfo": {
    "method": "charged-now",
    "creditsCharged": 10
  }
}

Save the taskId from this response. You need it to poll for results. There is no way to retrieve it again after this call.

Batch contact enrichment — poll

After starting a batch job, poll this endpoint to check progress and retrieve completed results page by page. The job processes asynchronously, so you will typically need to poll multiple times before all results are ready.Endpoint: POST https://api.descovo.com/v1/contact-enrich/batch/poll
Auth: apiKey in the request body
Credit behavior: Free — credits were charged when the batch was started

Request parameters

apiKey

string

required

Your Descovo API key.

taskId

string

required

The taskId returned when you started the batch.

take

number

Number of completed results to return in this poll response. Defaults to 100.

cursor

string

Pagination cursor for results. Pass null on the first poll, then pass the nextCursor from each response to page through completed results.

Response fields

output

object

Hide properties

output.overallStats

object

Progress summary for the entire batch.

Show properties

output.overallStats.totalPeopleToFetch

number

Total unique profiles in this batch.

output.overallStats.numCompleted

number

Profiles that have been processed so far.

output.overallStats.numRemaining

number

Profiles not yet processed.

output.overallStats.numRejected

number

Profiles that could not be processed (e.g. invalid URL).

output.overallStats.numDuplicates

number

Duplicate entries that were skipped.

output.done

boolean

true when all profiles in the batch have been processed.

output.pageResults

object[]

Enriched contact results for this page.

Show pageResults item properties

output.pageResults[].inputs

object

The input identifiers for this profile, including the original linkedinUrl.

output.pageResults[].outputs

object

Found contact data: emails (array of strings) and phoneNumbers (array of strings).

output.nextCursor

string | null

Pass as cursor in the next poll call to fetch additional result pages. null when no more results are available.

chargeInfo

object

Show properties

chargeInfo.method

string

charged-for-async-process — credits were already charged when the batch started.

Example

First poll request:

{
  "apiKey": "sk_live_xxx",
  "taskId": "aud_abc123",
  "take": 100,
  "cursor": null
}

Response (still in progress):

{
  "output": {
    "overallStats": {
      "totalPeopleToFetch": 200,
      "numCompleted": 120,
      "numRemaining": 80,
      "numRejected": 5,
      "numDuplicates": 10
    },
    "done": false,
    "pageResults": [
      {
        "inputs": {
          "linkedinUrl": {
            "value": "https://www.linkedin.com/in/example-1/"
          }
        },
        "outputs": {
          "emails": ["person@company.com"],
          "phoneNumbers": ["+1-555-123-4567"]
        }
      }
    ],
    "nextCursor": "encrypted_cursor_here"
  },
  "chargeInfo": {
    "method": "charged-for-async-process",
    "creditsCharged": 0,
    "message": "Credits were already charged when the batch was started."
  }
}

Subsequent page request:

{
  "apiKey": "sk_live_xxx",
  "taskId": "aud_abc123",
  "take": 100,
  "cursor": "encrypted_cursor_here"
}

Poll every 30–60 seconds until done is true. Use overallStats to show progress to your users: completed, remaining, and rejected counts. Continue paginating with nextCursor until it returns null to collect all results.

Enriching contacts within an audience

For full-scale workflows — finding, filtering, enriching, and exporting a large segment — use audience-based enrichment rather than the batch endpoint. The audience workflow gives you search filters, cost estimation, and CSV export in a single pipeline. See Audiences for the complete endpoint sequence.

Credit costs

Data type	Typical cost
Work email found	2 credits
Personal email found	2 credits
Phone number found	3 credits

Credits are charged only for data that is successfully found. Profiles where no contact data is available do not consume credits for those data types.

Overview

Endpoints

Contact enrichment endpoints: sync, batch, and audience

Sync contact enrichment

Request parameters

Response fields

Example

Batch contact enrichment — start

Request parameters

Response fields

Example

Batch contact enrichment — poll

Request parameters

Response fields

Example

Enriching contacts within an audience

Credit costs

Overview

Endpoints

Documentation Index

​Sync contact enrichment

​Request parameters

​Response fields

​Example

​Batch contact enrichment — start

​Request parameters

​Response fields

​Example

​Batch contact enrichment — poll

​Request parameters

​Response fields

​Example

​Enriching contacts within an audience

​Credit costs

Sync contact enrichment

Request parameters

Response fields

Example

Batch contact enrichment — start

Request parameters

Response fields

Example

Batch contact enrichment — poll

Request parameters

Response fields

Example

Enriching contacts within an audience

Credit costs