# Search B2B people by job title and industry with Scalelist's API

Scalelist's people search API finds B2B prospects by job title, seniority, industry, location and company, and a count call tells you how big a list is before you buy a single profile. A count costs $0.058 per call however many people match, and search costs $0.058 per profile returned, both drawn from Prepaid lead data credit bought by card. Send your filters to `POST https://agents.scalelist.com/zcj/064rfc6pie78/agent/people/count`, then send the same filters to `POST https://agents.scalelist.com/zcj/064rfc6pie78/agent/people/search`, with your agent credential on both.

## At a glance

- **Endpoints:** `POST https://agents.scalelist.com/zcj/064rfc6pie78/agent/people/industries` (industry lookup), `POST https://agents.scalelist.com/zcj/064rfc6pie78/agent/people/count`, `POST https://agents.scalelist.com/zcj/064rfc6pie78/agent/people/search`
- **Body:** a JSON object of filters such as `job_titles`, `seniority`, `industries` and `locations`. Search also takes `page_size` (up to 100) and `cursor`.
- **Price:** a count is $0.058 per call, a search is $0.058 per profile returned, and the industry lookup is free for registered agents.
- **Payment:** card only. Count and search draw from Prepaid lead data credit, with a minimum card purchase of $1. Neither is sold per call.
- **Credential:** an agent credential, sent as `Authorization: Bearer <token>` on every call. Registering one is a single free call, described at [auth.md](https://agents.scalelist.com/zcj/064rfc6pie78/auth.md).
- **Response:** a count returns `total_results`. A search returns `profiles`, `total_results` and `next_cursor`.
- **Billing record:** a plan-funded response carries a `zc-billing` header with `chargedUsd` and `remainingCreditUsd`.
- **Full purchase flow:** [the buyer skill](https://agents.scalelist.com/zcj/064rfc6pie78/SKILL.md)

## Build a prospect list

1. **Get a credential and credit.** Count and search need an agent credential and Prepaid lead data credit bought by card, and [the buyer skill](https://agents.scalelist.com/zcj/064rfc6pie78/SKILL.md) covers registering and buying credit.

2. **Turn industry words into exact categories.**

   ```bash
   curl -s -X POST https://agents.scalelist.com/zcj/064rfc6pie78/agent/people/industries \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -d '{"industries": ["fintech", "banking"]}'
   ```

   The response has this shape:

   ```json
   {"resolved": {"banking": ["<category>", "<category>"]}, "unresolved": ["<word>"], "unverified": [], "suggestions": {}}
   ```

   The response maps each resolved word to its exact category names under `resolved`, lists words with no category under `unresolved`, and lists words to retry under `unverified`.
   - Use the resolved category names as your `industries` values.
   - Retry a word that lands in `unverified`.
   - For a word in `unresolved`, check `suggestions` for alternatives.

3. **Count the audience.** Send the filters you plan to search with.

   ```bash
   curl -s -X POST https://agents.scalelist.com/zcj/064rfc6pie78/agent/people/count \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -d '{"job_titles": ["Head of Sales"], "locations": [{"type": "country", "value": "United States"}]}'
   ```

   The response is `{"total_results": <number>, "ranked": <boolean>}`. This count drew $0.058 from prepaid credit.

   A narrower count of VPs in the Banking category in Germany uses the category the lookup resolved:

   ```json
   {"industries": ["Banking"], "seniority": ["VP"], "locations": [{"type": "country", "value": "Germany"}]}
   ```

   Its response also carried `resolved_industries`, the categories `Banking` was searched as, and it drew $0.058 from prepaid credit.

4. **Buy one page of profiles.** Send the same filters, plus `page_size`.

   ```bash
   curl -s -X POST https://agents.scalelist.com/zcj/064rfc6pie78/agent/people/search \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -d '{"job_titles": ["Head of Sales"], "locations": [{"type": "country", "value": "United States"}], "page_size": 100}'
   ```

   The response has this shape:

   ```json
   {"page": 1, "page_size": 100, "total_results": <number>, "next_cursor": "<cursor>", "next_offset": <number>, "task_id": "<id>",
    "profiles": [{"full_name": "Alex Example", "job_title": "Head of Sales", "seniority": "Head", "company_name": "Example Inc", "company_domain": "example.com", "city": "<city>", "country": "United States", "linkedin_url": "<profile URL>"}]}
   ```

5. **Page on.** Resend the same body with `"cursor": "<next_cursor>"` to get the next page. `next_cursor` is null on the last page. To address a page directly, `page` and `offset` also work. When `offset` is set, it overrides `page`, and exactly that window of rows is returned and billed.

## Choose the filters

Values inside one list match any of them. Separate fields must all hold.

| To target | Field | Value |
| --- | --- | --- |
| Job title | `job_titles` | A list of titles. Set `job_title_match` to `"words"` (the default: all words, in any order) or to `"phrase"` (the exact phrase, which drops look-alikes such as Vice President for President). |
| Seniority | `seniority` | `Owner / Founder`, `CXO`, `Partner`, `VP`, `Head`, `Director`, `Manager`, `Senior`, `Entry`, `Intern` |
| Department | `job_functions` | Values from the reference's list, such as `Sales`, `Marketing`, `Engineering` or `Finance` |
| Industry | `industries` | Exact categories from the industry lookup |
| Place | `locations` | Objects with `type` (`city`, `state` or `country`) and `value`. A city entry also takes `country`. |
| Company size | `company_size` | `{"min": ..., "max": ...}` in employees. Either end is optional. |
| Named companies | `companies`, `company_domains` | Company names, or domains such as `example.com` |
| New in role | `recently_changed_jobs` | `true` for people whose current role started in roughly the last three months |
| Leave people out | `exclude_job_titles`, `exclude_industries`, `exclude_locations`, `exclude_companies`, `exclude_company_domains`, `exclude_job_functions` | The same shape as the matching filter |

## Price a list

| Plan for the list | Cost |
| --- | --- |
| One count, then one page of 100 profiles | $5.858 |
| Three counts while narrowing filters, then 50 profiles | $3.074 |
| One count, then 500 profiles over five pages | $29.058 |

Search is charged per profile returned, so a last page holding fewer profiles than `page_size` costs less. Any credit you do not use stays on your balance.

## Limits

- **Filters:** count and search each need at least one filter. A body without one answers `422`.
- **Industry words:** a word in `industries` that does not resolve is matched as profile text and listed in `unresolved_industries`. A word in `exclude_industries`, or a value in `exclude_job_functions`, with no match is refused with `422`.
- **Page size:** a page holds at most 100 profiles. A count takes no paging fields.
- **Profile contents:** a profile carries `full_name`, `job_title`, `seniority`, `company_name`, `company_domain`, `city`, `country` and `linkedin_url`. Search results do not show skills or certifications, even when you filter on them.
- **What is charged:** count and search draw only on Prepaid lead data credit. A `503` is not charged.

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `401 bearer_required` | The call carried no agent credential | Register at [auth.md](https://agents.scalelist.com/zcj/064rfc6pie78/auth.md) and retry with the bearer |
| `403 plan_required` | No credit covers the call | Buy Prepaid lead data credit, then retry |
| `usage_exhausted` | The credit balance is used up | Top up with `POST https://agents.scalelist.com/zcj/064rfc6pie78/extend` and `{"amountUsd": "..."}` |
| `422` | No filter, or an exclusion value with no match | Add a filter, or fix the value |
| `429` | Too many requests from this agent | Retry later |

## Frequently asked questions

### How do I count leads before buying them?

Send your filters to `POST https://agents.scalelist.com/zcj/064rfc6pie78/agent/people/count`. It returns `total_results` for those filters at $0.058 per call. You can then adjust the filters, or send them to search and buy profiles.

### Does a people count cost more for a larger audience?

No. A count is charged once per call, whatever `total_results` comes to.

### Can I find people by job title and industry in one search?

Yes. Separate fields combine as AND, so `job_titles`, `industries` and `locations` in one body return only people who match all three. Values inside each list match any of them.

### Does people search return emails or phone numbers?

A profile carries name, title, seniority, company, company domain, place and LinkedIn URL. For work emails and mobile numbers, B2B Email Finder and Mobile Number Finder are separate services on the same storefront.

### Can I pay for a count or a search per call?

No. Count and search are sold on Prepaid lead data credit, bought by card with a minimum of $1, and each call draws down that balance.

## Keep reading

- [Buyer skill](https://agents.scalelist.com/zcj/064rfc6pie78/SKILL.md): the full purchase flow
- [Identity](https://agents.scalelist.com/zcj/064rfc6pie78/auth.md): register and present your agent credential
- [How to pay](https://agents.scalelist.com/zcj/064rfc6pie78/payment.md): credit, top-ups and the `zc-billing` header
- [People Search reference](https://agents.scalelist.com/zcj/064rfc6pie78/services/people-search/openapi.json): every filter and response field
- [Error reference](https://agents.scalelist.com/zcj/064rfc6pie78/errors.md): every error code and how to react

---

Updated 2026-11-20. All Scalelist guides: https://agents.scalelist.com/guides.md. Storefront: https://agents.scalelist.com/zcj/064rfc6pie78/llms.txt.
