Quickstart: Find People Showing Intent on a Topic
What this does
Start from a topic, get back the people researching it right now, strongest intent first. This quickstart is the list-building direction. The enrichment quickstart starts from people you already have. This quickstart finds people you do not.
topic in -> free preview -> dry_run cost -> POST /api/v1/intent/people (paged) -> people out
Each row is one person, returned as a hem (sha256 of a normalized email) you can match against your own contacts, plus a person_id. Raw emails are never returned unless you ask for them with resolve.
Before you start
You need an organization API key + secret pair. The Authentication guide walks through it. Every request below sends both headers:
X-Api-Key: dlvr_...
X-Api-Secret: ...
1. Find the topic_id
Topics are identified by topic_id. Search the taxonomy by name:
curl "https://api.delivr.ai/api/v1/taxonomy/topics?search=crm&limit=5" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "X-Api-Secret: YOUR_API_SECRET"{
"response": {
"topics": [
{
"topic_id": "4eyes_105087",
"name": "Customer Relationship Management (CRM)",
"status": "active",
"topic_type": "B2B"
}
]
}
}Copy the topic_id of the topic you want. The Taxonomy API guide covers browsing by category and requesting a topic that does not exist yet.
2. Preview for free
POST /api/v1/intent/people/preview returns a capped, masked sample (up to 25) of the strongest people on the topic: company, department and seniority band, with field coverage. It also returns count, the number of people on the topic who match your min_score and min_perc_score. Nothing is billed.
curl -X POST "https://api.delivr.ai/api/v1/intent/people/preview" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "X-Api-Secret: YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{"topic_id": "4eyes_105087", "min_score": "high"}'{
"response": {
"topic_id": "4eyes_105087",
"preview": true,
"masked": true,
"count": 18420,
"field_coverage": {
"business_email": 18,
"personal_email": 11,
"mobile_phone": 9,
"direct_phone": 4,
"linkedin_url": 21,
"job_title": 23,
"seniority": 22,
"department": 22,
"company_name": 24,
"company_domain": 24,
"postal_address": 7
},
"results": [
{
"hem": null,
"company_name": "Northwind Logistics",
"department": "finance",
"seniority_band": "VP+",
"score": "high",
"perc_score": 97
}
]
},
"as_of": "2026-06-21"
}- Each preview row shows the person's
company_name,departmentandseniority_band(VP+,Director,ManagerorStaff), andnullwhere we do not know it.hemisnull, and no row carries a name, title, contact field or person key. The paid endpoint below returns thehem. field_coveragecounts, for each field the paid pull returns, how many people in the sample hold it.maskedistrue.- The preview does not paginate: it takes no
cursorand returns nonext_cursor. You always get the top of the list. countis every person on the topic who matches the request'smin_scoreandmin_perc_score.resolveandresolve_linkedinapply only to partner organizations enabled for the raw hem. The masked preview ignores them.as_ofis the single day the intent data covers. The dataset is rebuilt daily, so a person can be on a topic one day and not the next.
3. Check the cost with dry_run
The paid endpoint bills one record per person returned. Send the same request you plan to run with "dry_run": true to see what it would charge, without being charged and without getting records back:
curl -X POST "https://api.delivr.ai/api/v1/intent/people" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "X-Api-Secret: YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{"topic_id": "4eyes_105087", "min_score": "high", "page_size": 50, "dry_run": true}'{
"dry_run": true,
"meter": "intent_signal_scored",
"records_to_charge": 50,
"note": "Cost preview only: no results were returned and nothing was billed. A live run of this request would charge records_to_charge against the named meter."
}records_to_charge covers that one request, which is one page. To estimate a full pull, use the preview's count, sent with the same min_score and min_perc_score you will pull with. A pull to the last page bills one record for every person who matches, so check count before you page to the end of a large topic. Details in Rate Limits and Metering.
4. Pull the list with cursor paging
Drop dry_run and page through the results. Results are ordered by perc_score, strongest first. page_size is 1 to 500 (default 50).
curl -X POST "https://api.delivr.ai/api/v1/intent/people" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "X-Api-Secret: YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{"topic_id": "4eyes_105087", "min_score": "high", "page_size": 50}'{
"response": {
"topic_id": "4eyes_105087",
"count": 18420,
"results": [
{
"person_id": "c41f6a0d92b7e5381a4d7f0e63b9a2c58d1e9f47b30a6c25e8d7149fa3b06e21",
"hem": "7bb9e30283184c3b4bbbf2262a600be7165d7e6f50e424a611aa64394e7ecdb5",
"score": "high",
"perc_score": 97
}
],
"next_cursor": "eyJ0IjoiNGV5ZXNfMTE4MDU2Iiwic2siOiIwMiM3YmI5ZTMwMiJ9"
},
"as_of": "2026-06-21"
}To get the next page, send the same body with "cursor" set to the next_cursor you received. Stop only when next_cursor is absent:
- A page can come back shorter than
page_size, or empty, because people who opted out are removed after the page is read. A short or empty page is not the end of the results. countis returned on the first page only.- Paging continues to the last person on the topic who matches your filters.
resolve: trueaddsseen_emailwhere we have it, andresolve_linkedin: trueaddslinkedin_url. Both are billed at the same intent rate.
Complete example: pull a topic (Python)
import requests
API = "https://api.delivr.ai/api/v1/intent/people"
HEADERS = {
"X-Api-Key": "YOUR_API_KEY",
"X-Api-Secret": "YOUR_API_SECRET",
}
body = {"topic_id": "4eyes_105087", "min_score": "high", "page_size": 500}
people = []
while True:
resp = requests.post(API, headers=HEADERS, json=body, timeout=60)
resp.raise_for_status()
page = resp.json()["response"]
people.extend(page["results"])
cursor = page.get("next_cursor")
if not cursor:
break
body["cursor"] = cursor
print(f"pulled {len(people)} people")Can I filter companies by employee size, revenue or industry?
Not on POST /api/v1/intent/companies/multi or POST /api/v1/intent/companies. The multi-topic request takes only topic_ids, min_score, min_people_count, group_by, per_topic_limit, min_topics, page_size, cursor and dry_run. A field outside that list, such as an employee range, revenue or industry, is ignored rather than rejected. A request that includes one returns the same unfiltered companies. Each company row carries domain and its intent signals only, with no employee, revenue or industry fields.
To get companies that match a size, revenue or industry and research your topics, build an Intent Audience instead. Its filters accept company_employee_count_range, company_revenue_range and company_industry alongside the topic rule, and each row carries the person's company_domain and company fields. See Building Audience Filters for the values.
Errors you might see
| Status | Meaning | Fix |
|---|---|---|
400 | Malformed request (for example, missing topic_id) | Check the request body against the examples above |
401 | Missing or invalid key/secret pair | Re-copy both halves from the dashboard. See Authentication |
402 with error payment_method_required | Your organization has no card or bank account on file, so paid requests are refused (previews and dry_run requests still work) | An organization owner or admin adds one in the dashboard under Billing, then retry. Other 402 codes are listed in Rate Limits and Metering |
429 with error platform_cap_exceeded | Over a daily or monthly usage limit | Do not retry straight away: kind says whether to wait for resets_at, send a smaller request, or contact support. See Rate Limits and Metering |
Any other 429 | Over your request rate limit | Back off and retry. See Rate Limits and Metering |
Where to go next
- Several topics at once:
POST /api/v1/intent/people/multitakes a list of topics. - Companies instead of people:
POST /api/v1/intent/companiestakes the same flow at the account level, withmin_people_countin place ofmin_perc_score. The companies preview'scountmatchesmin_scoreandmin_people_count. Both endpoints have/previewvariants. - Restrict to your own audience: pass
audience_idto get only the members of one of your audiences who show intent on the topic. See the endpoint reference. - Which API should I use? if your use case is not list building.
Updated 7 days ago
