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, department and seniority_band (VP+, Director, Manager or Staff), and null where we do not know it. hem is null, and no row carries a name, title, contact field or person key. The paid endpoint below returns the hem.
  • field_coverage counts, for each field the paid pull returns, how many people in the sample hold it. masked is true.
  • The preview does not paginate: it takes no cursor and returns no next_cursor. You always get the top of the list.
  • count is every person on the topic who matches the request's min_score and min_perc_score.
  • resolve and resolve_linkedin apply only to partner organizations enabled for the raw hem. The masked preview ignores them.
  • as_of is 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.
  • count is returned on the first page only.
  • Paging continues to the last person on the topic who matches your filters.
  • resolve: true adds seen_email where we have it, and resolve_linkedin: true adds linkedin_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

StatusMeaningFix
400Malformed request (for example, missing topic_id)Check the request body against the examples above
401Missing or invalid key/secret pairRe-copy both halves from the dashboard. See Authentication
402 with error payment_method_requiredYour 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_exceededOver a daily or monthly usage limitDo 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 429Over your request rate limitBack off and retry. See Rate Limits and Metering

Where to go next

  • Several topics at once: POST /api/v1/intent/people/multi takes a list of topics.
  • Companies instead of people: POST /api/v1/intent/companies takes the same flow at the account level, with min_people_count in place of min_perc_score. The companies preview's count matches min_score and min_people_count. Both endpoints have /preview variants.
  • Restrict to your own audience: pass audience_id to 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.

Did this page help you?