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.

Descovo uses a credit-based billing model: you spend credits each time the API returns data. Different operations cost different amounts, and some operations — like estimating enrichment cost or checking status — are free. Every API response includes a chargeInfo field that tells you exactly how credits were charged for that call.

​
Check your credit balance

Use GET /v1/credits to retrieve your current balance at any time. Pass your API key as a query parameter: 
GET https://api.descovo.com/v1/credits?apiKey=sk_live_xxx
Example response: 
{
  "output": {
    "credits": 48500
  },
  "chargeInfo": {
    "method": "free"
  }
}
Check your balance before running large search or enrichment jobs so you can estimate whether you have enough credits to complete the work.

​
The chargeInfo field

Every Descovo API response includes a chargeInfo object. The method field tells you how credits were handled for that specific call:
​
chargeInfo
object
Credit charge information for the request.

​
Method values explained

MethodWhen it appearsWhat it means
charged-nowSearch, sync enrichment, live enrichmentCredits were deducted immediately when the response was returned.
charged-for-async-processBatch poll, enrichment status checksCredits were already charged when the async job was started; this call is free.
charging-laterAudience build startCredits will be charged after the async operation completes, based on actual results.
freeCreate audience, set search params, estimate, export, credit checkNo credits were charged for this call.

​
Per-operation credit costs

The table below shows typical credit costs per successful operation. Exact rates may vary by account — contact your account manager for your specific pricing.
OperationTriggerTypical cost
getPersonFromDbEach profile returned in people search or audience build1 credit
getCompanyFromDbEach company returned in company search or audience build1 credit
Work email revealEach work email found during contact enrichment2 credits
Personal email revealEach personal email found during contact enrichment2 credits
Phone number revealEach phone number found during contact enrichment3 credits
liveEnrichCompanyEach live company fetch2 credits
liveEnrichPersonEach live profile fetch2 credits
Credits are only charged for successful results. If a search returns 0 results, you are not charged. If a contact enrichment request finds no email for a profile, you are not charged for that profile.

​
Tips for managing credit usage

  • Estimate before large audience enrichments. Use POST /v1/audiences/{audienceId}/enrichment/estimate (free) to see a credit breakdown before you commit.
  • Use smaller page sizes when exploring. Start with pageSize: 25 to verify your filters are working correctly before fetching thousands of results.
  • Prefer batch over sync for large lists. Batch contact enrichment is more efficient than calling the sync endpoint repeatedly for many profiles.
  • Disable enrichment types you do not need. If you only need work emails, set getPersonalEmails: false and getPhoneNumbers: false to avoid unnecessary charges.