Developer Documentation

API Reference

Build with saved lead-search sessions: start a discovery search, poll its progress, retrieve only the results you need, and export the durable list when it is ready. The public contract stays focused on the product workflow.

Overview

All endpoints return JSON and live under /api/public. Discovery starts return 202 while work is queued; keep the session ID, poll its status, then read paginated results. API access requires an eligible API plan and uses the same account balance and active-search capacity as the workspace.

Format

JSON REST

Auth

API key

Results

Saved sessions

Authentication

Send the key as a Bearer token or in the X-API-Key header. Create and revoke keys in Billing; store them on your server rather than in browser code.

curl https://dnleads.co/api/public/capabilities \
  -H "Authorization: Bearer dnl_live_YOUR_KEY_HERE"

curl https://dnleads.co/api/public/capabilities \
  -H "X-API-Key: dnl_live_YOUR_KEY_HERE"

Base URL

https://dnleads.co/api/public

Current discovery contract

Keywords Leads uses the shared Discovery API. Industry Leads uses the same contract only when /discovery/configreports it as enabled. A search is durable from the moment it is accepted, supports filters and contacted tracking, and can be archived, restored, or exported. Results are delivered as usable domains; internal retrieval and settlement details are not part of this contract.

Keywords Leads

1–10 keywords, 1–1,000 requested results, optional country and language filters.

Industry Leads

When enabled: 1–5 catalog categories, a catalog market and language, and 1–1,000 requested results.

Keywords and Industry each have one lifetime free search, with up to 50 results. Fewer results still use the search. API-key access itself remains subject to the plan's API entitlement.

GET/discovery/config

Configuration, estimates, and catalogs

Fetch configuration before rendering a start form. It reports enabled tools, public limits, account allowance status, and no reset date for lifetime allowances. Request an estimate before each paid start; it returns one all-in customer total only.

# Read available tools and the account's current allowance
curl https://dnleads.co/api/public/discovery/config \
  -H "Authorization: Bearer dnl_live_YOUR_KEY_HERE"

# Get the current all-in customer estimate
curl "https://dnleads.co/api/public/discovery/estimate?tool=keywords&results=250" \
  -H "Authorization: Bearer dnl_live_YOUR_KEY_HERE"


# Industry is enabled: load its catalog values after reading config
curl https://dnleads.co/api/public/discovery/catalog/categories \
  -H "Authorization: Bearer dnl_live_YOUR_KEY_HERE"
curl https://dnleads.co/api/public/discovery/catalog/markets \
  -H "Authorization: Bearer dnl_live_YOUR_KEY_HERE"

`included`	boolean	Whether this start is covered by the account's included allowance.
`requestedResults`	number	The validated result count for the next batch.
`estimatedCredits`	number	One customer-facing total credit estimate for the requested scope.
`mayAdjust`	boolean	Signals that the delivered total can adjust only under the stated discovery settlement policy.

POST/discovery/keywords/start

Start Keywords Leads

Start a saved domain search with one or more keywords. For paid starts, request an estimate first. Keep the returned session ID for follow-up requests.

`keywords`required	string \| string[]	One to ten non-empty keywords, each up to 120 characters.
`resultCount`required	integer	A whole number from 1 through 1,000. Free included starts are limited to 50.
`countryCode`	string	Optional two-letter ISO country filter, for example `US`.
`languageCode`	string	Optional language filter, for example `en`.
`clientRequestId`	string	Optional 8–80 character idempotency key for safe client retries.

curl -X POST https://dnleads.co/api/public/discovery/keywords/start \
  -H "Authorization: Bearer dnl_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": ["managed it providers", "cloud consulting"],
    "resultCount": 250,
    "countryCode": "US",
    "languageCode": "en",
    "clientRequestId": "keywords-us-20260911"
  }'

POST/discovery/industry/start

Start Industry Leads

Configuration currently enables this workflow. Load categories and markets, then submit catalog codes for the selected market.

`categoryCodes`required	number[]	One to five codes returned by `/discovery/catalog/categories`.
`locationCode`required	number	A market code returned by `/discovery/catalog/markets`.
`languageCode`required	string	A language supported by the selected catalog market.
`resultCount`required	integer	A whole number from 1 through 1,000. Free included starts are limited to 50.
`clientRequestId`	string	Optional idempotency key for safe retries.

curl -X POST https://dnleads.co/api/public/discovery/industry/start \
  -H "Authorization: Bearer dnl_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "categoryCodes": [123, 456],
    "locationCode": 2840,
    "languageCode": "en",
    "resultCount": 250,
    "clientRequestId": "industry-us-20260911"
  }'

GET/discovery/sessions/:sessionId

Sessions, results, and export

A start response contains a saved session. Poll until its status is terminal, then fetch results with explicit filters and pagination. Only delivered rows are returned or exported.

# List saved sessions for one discovery tool
curl "https://dnleads.co/api/public/discovery/history?tool=keywords&limit=20" \
  -H "Authorization: Bearer dnl_live_YOUR_KEY_HERE"

# Poll one session and read a filtered result page
curl https://dnleads.co/api/public/discovery/sessions/SESSION_ID \
  -H "Authorization: Bearer dnl_live_YOUR_KEY_HERE"
curl "https://dnleads.co/api/public/discovery/sessions/SESSION_ID/results?page=1&pageSize=50&email=has&sort=confidence" \
  -H "Authorization: Bearer dnl_live_YOUR_KEY_HERE"

# Continue a paid saved search with its original scope. Choose the additional
# result count, and reuse clientRequestId if the network response is lost.
curl -X POST https://dnleads.co/api/public/discovery/sessions/SESSION_ID/load-more \
  -H "Authorization: Bearer dnl_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"resultCount": 250, "clientRequestId": "load-more-20260911-001"}'

# Export only the saved, delivered rows
curl -L https://dnleads.co/api/public/discovery/sessions/SESSION_ID/export.csv \
  -H "Authorization: Bearer dnl_live_YOUR_KEY_HERE" \
  -o discovery.csv

`page / pageSize`	integer	Pages begin at 1; pageSize is 10–100 and defaults to 50.
`q`	string	Searches saved domain, title, or description.
`contacted`	contacted \| not_contacted	Filters contacted state.
`enrichment`	ready \| pending \| failed	Filters automatic website-detail progress.
`website / email`	has \| missing	Filters saved website or email availability.
`sort`	newest \| oldest \| domain \| confidence \| enrichment	Chooses a supported deterministic ordering.
`Load More body`	object	Send `resultCount` from 1 to 1,000 and a unique `clientRequestId`. Reuse that same ID only when retrying the same request after a lost response.

Billing, capacity, and retention

Use /discovery/estimate before every paid Discovery start. It returns one all-in confirmation total for the requested scope. A start may be delayed by account-wide active-search capacity or the API request budget. Paid plans have no daily, weekly, or cooldown search cap; active access, credits, and the plan's parallel-search slots govern when a search can start.

Sign in with an eligible API plan, then use GET /usage to read your actual shared balance. This reference does not display sample credit totals.

curl https://dnleads.co/api/public/usage \
  -H "Authorization: Bearer dnl_live_YOUR_KEY_HERE"

Browse results and download CSV/JSON files for 4 calendar months from search creation, for all tools and plans. Then searches and their results are automatically and permanently deleted from your DNLeads account. They cannot be browsed, downloaded, or recovered. Download anything you want to keep before it expires.

Saved input, result, and enrichment data may be reused for up to 4 calendar months. Reading or reusing cached data does not extend its expiry.

The expiry timestamp is returned with saved sessions. Archive, restore, result reads, and exports never extend it. Once a search expires, it is permanently unavailable through both the workspace and API.

GET/capabilities

Discover enabled API features

Read capabilities at integration setup and whenever your app needs to adapt to account access. Keywords Leads entries point to the Discovery contract; Industry is present only when enabled. Maps, Advertiser, Domain, and compatibility routes are listed with their own supported endpoints.

curl https://dnleads.co/api/public/capabilities \
  -H "Authorization: Bearer dnl_live_YOUR_KEY_HERE"

`tools`	array	Current start, status, result, catalog, and export URLs for the available tools.
`discovery`	object	Shared Discovery configuration endpoints and the public total credit estimate rule.
`parallelSearchStatus`	object	Current account-wide active-search slots.
`rateRemaining`	number	Requests remaining for the API key's account in the current minute.

Existing API compatibility routes

Domain Leads: enter a domain to find similar companies, not a report on that domain.

Existing /tools/domain/*, Maps Leads, and Advertiser Leads routes remain available for integrations already using them. Historic /tools/keywords/*sessions stay readable, but new Keywords Leads starts return a migration response. New Discovery integrations must first read the available configuration, then use the enabled/discovery/* endpoints in this reference.

Use GET /capabilities rather than hard-coding optional tool availability or customer-facing totals.

Errors and retry behavior

Error responses contain an error message and may include a stable code, a retry hint, or current active-search status. Treat unknown fields as additive and do not rely on internal operational details.

400	Bad Request	Validate fields against the endpoint contract.
401	Unauthorized	Supply a valid active API key.
402	Access required	Renew API access or add sufficient account balance.
409	State conflict	Refresh the saved session before retrying the action.
429	Try later	Respect rate, included-allowance, or active-search capacity feedback.
503	Temporarily unavailable	Retry with backoff; a saved session can still be polled safely.

For product retention and account terms, see the search storage terms.