# Find decision makers and verified work emails with BlitzAPI's API

BlitzAPI's People Search finds the right person at a target account, and People Enrichment returns that person's verified work email from their LinkedIn profile URL. A search costs $0.001 per person returned and a work email costs $0.001 per verified email found, drawn from prepaid Credits bought by card. A lookup that finds nothing costs nothing. Send `POST https://agents.blitz-api.ai/zcj/tazxwazrempp/v2/search/waterfall-icp-keyword` with your titles in order of preference, then `POST https://agents.blitz-api.ai/zcj/tazxwazrempp/v2/enrichment/email` with each person's LinkedIn URL from the search result sent as `person_linkedin_url`, both with `Authorization: Bearer <access_token>`.

## At a glance

- **Endpoints:** `POST https://agents.blitz-api.ai/zcj/tazxwazrempp/v2/search/waterfall-icp-keyword`, `/v2/search/people`, `/v2/search/employee-finder`, `/v2/enrichment/email`, `/v2/enrichment/person`, `/v2/enrichment/email-to-person`
- **Body:** JSON. Searches take person and company filters and `max_results`. Enrichment takes `person_linkedin_url` or `email`.
- **Price:** $0.001 per person returned by a search, $0.001 per verified work email found, $0.001 per person profile returned. A page or lookup that returns nobody costs nothing.
- **Payment:** card only, through the Credits plan, at least $0.60 per card purchase. Wallet payments are not offered, and there is no per-call 402.
- **Credential:** a free agent credential the storefront issues, sent as a bearer token. No BlitzAPI account or API key.
- **Response:** JSON with `results` for searches, `found` with `email` or `person` for enrichment, and a `fair_usage` block.
- **Limits:** up to 50 people per page on People Search and Employee Finder, up to 100 people and 10 tiers per waterfall request, one lookup per enrichment request.
- **Full purchase flow:** [the buyer skill](https://agents.blitz-api.ai/zcj/tazxwazrempp/SKILL.md)

## Find the decision maker, then the work email

1. Get a free agent credential and buy Credits once by card, from $0.60. [The buyer skill](https://agents.blitz-api.ai/zcj/tazxwazrempp/SKILL.md) has the steps; calls then draw on the balance with the credential as a bearer token.

2. Send a waterfall search with your titles in order of preference:

   ```bash
   curl -s -X POST "https://agents.blitz-api.ai/zcj/tazxwazrempp/v2/search/waterfall-icp-keyword" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "company_linkedin_url": "<company_linkedin_url>",
       "cascade": [
         {"include_title": ["Chief Revenue Officer", "VP Sales"], "exclude_title": ["assistant", "intern"], "location": ["US"]},
         {"include_title": ["Head of Sales", "Sales Director"], "exclude_title": ["assistant", "intern"], "location": ["US"]},
         {"include_title": ["CEO", "founder"], "location": ["WORLD"]}
       ],
       "max_results": 1
     }'
   ```

   Tier 1 fills `max_results` first. When it finds fewer people, the next tier fills the remaining slots, and no person is returned twice. The response has this shape:

   ```json
   {"results": [{"icp": 2, "ranking": 1, "person": {"full_name": "<full_name>", "linkedin_url": "<person_linkedin_url>", "headline": "<job_title> | @<employer>", "experiences": [{"job_title": "<job_title>", "job_is_current": true}]}}], "results_length": 1, "max_results": 1, "company_linkedin_url": "<company_linkedin_url>", "fair_usage": {"records_used": 1, "request_id": "<request_id>"}}
   ```

   `icp` is the tier that matched, counted from 1.

3. Read the verified work email, sending the person's LinkedIn URL from the search result as `person_linkedin_url`:

   ```bash
   curl -s -X POST "https://agents.blitz-api.ai/zcj/tazxwazrempp/v2/enrichment/email" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"person_linkedin_url": "<person_linkedin_url>"}'
   ```

   ```json
   {"found": true, "email": "jane@example.com", "mx": [{"host": "<mx_host>", "priority": 1}], "all_emails": [{"email": "jane@example.com", "email_domain": "example.com", "company_linkedin_url": "<company_linkedin_url>", "job_order_in_profile": 1}]}
   ```

   Each email is checked against a live mail server and checked again at least once every 30 days. When no address can be proven, the lookup returns Not Found and nothing is billed.

4. For the full profile and career history, send the same body to `https://agents.blitz-api.ai/zcj/tazxwazrempp/v2/enrichment/person`. The response holds `found` and a `person` object.

Each plan-funded response carries a `zc-billing` header with `chargedUsd` and `remainingCreditUsd`. A delivered response with no `zc-billing` header billed nothing.

## Choose the search

| You have | Send | Required fields |
| --- | --- | --- |
| One account and a ranked list of titles | `/v2/search/waterfall-icp-keyword` | `company_linkedin_url`, `cascade` |
| One company, and you want its staff by level or function | `/v2/search/employee-finder` | `company_linkedin_url` |
| A profile of buyers across many companies | `/v2/search/people` | none: set `people` and `company` filters |
| A work email, and you want the person | `/v2/enrichment/email-to-person` | `email` |

A People Search body for sales leaders at mid-sized US software companies:

```json
{
  "people": {
    "job_level": ["VP", "C-Team"],
    "job_function": ["Sales & Business Development"],
    "location": {"country_code": ["US"]}
  },
  "company": {
    "industry": {"include": ["Software Development"]},
    "employee_range": ["51-200", "201-500"]
  },
  "max_results": 50,
  "cursor": null
}
```

The documented example response shows `results`, `total_results` and a `cursor`. Send the cursor back for the next page. `industry`, `job_level` and `job_function` take exact values from the API reference. Title filters match as keywords, and a value in square brackets, such as `"[CEO]"`, requires an exact match. Employee Finder pages by `page` and returns `total_pages`.

## Budget a run

| Run | Cost |
| --- | --- |
| 20 accounts, one decision maker each, 15 emails proven | $0.035 |
| One People Search page of 50, emails proven for 40 | $0.09 |

## Limits

- One person per enrichment request, with no batch parameter.
- Every call draws on Credits. A call that finds nothing costs nothing, and a 422 does not run and uses no records.

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `401 bearer_required` | No access token | Register at [auth.md](https://agents.blitz-api.ai/zcj/tazxwazrempp/auth.md), exchange, retry |
| `401 invalid_token` | Token expired or invalid | Re-exchange the stored assertion for a fresh token |
| `403 plan_required` | No Credits cover the call | Buy Credits, then retry |
| `usage_exhausted` | Credits ran out | `POST https://agents.blitz-api.ai/zcj/tazxwazrempp/extend` with `{"amountUsd": "<amount>"}` |
| Not Found | The lookup found nothing, including a work email that cannot be proven | Not billed. Try the next person |
| `422` | Unknown field or invalid value. `errors[]` names the field and the closest match | Fix the body and resend. The request did not run |
| `429` | Rate limit reached | Wait, then retry |

## Frequently asked questions

### Is a work email charged when it cannot be verified?

No. Find Work Email is billed only when it finds a verified address. An address that cannot be proven against a live mail server comes back Not Found and costs nothing.

### How does the waterfall ICP search choose a decision maker?

You send up to 10 tiers of job titles in order of preference. The first tier fills `max_results`, later tiers fill only the slots left, and each result's `icp` field names the tier that matched.

### Can I find a work email from a LinkedIn profile URL?

Yes. Send `POST https://agents.blitz-api.ai/zcj/tazxwazrempp/v2/enrichment/email` with `person_linkedin_url`. The response gives `email` and, in `all_emails`, each address with the company it belongs to.

### Do I need a BlitzAPI account or API key?

No. You register a free agent credential with the storefront, buy Credits by card, and send the access token as `Authorization: Bearer` on every call.

### Can I list every employee at one company?

Yes. Employee Finder takes `company_linkedin_url` and filters by `job_level`, `job_function` and `country_code`, up to 50 people per page. It costs $0.001 per person returned.

## Keep reading

- [Buyer skill](https://agents.blitz-api.ai/zcj/tazxwazrempp/SKILL.md): registration, Credits and recovery
- [Identity](https://agents.blitz-api.ai/zcj/tazxwazrempp/auth.md): registering and refreshing the agent credential
- [How to pay](https://agents.blitz-api.ai/zcj/tazxwazrempp/payment.md): card checkout, Credits and top-ups
- [Error reference](https://agents.blitz-api.ai/zcj/tazxwazrempp/errors.md): every storefront error code
- [People Search API reference](https://agents.blitz-api.ai/zcj/tazxwazrempp/services/people-search/openapi.json): every filter and value
- [People Enrichment API reference](https://agents.blitz-api.ai/zcj/tazxwazrempp/services/people-enrichment/openapi.json): request and response fields

---

Updated 2026-10-22. All BlitzAPI guides: https://agents.blitz-api.ai/guides.md. Storefront: https://agents.blitz-api.ai/zcj/tazxwazrempp/llms.txt.