# Search B2B contacts by job title with Bytemine's Prospect Finder API

Bytemine's Prospect Finder API searches B2B contacts by job title, company, industry and location, and returns candidates with email and phone masked and a `pid` for each. A search costs $0.01 per record returned, and revealing a contact's details costs $0.01 for each contact you choose. Send `POST https://agents.bytemine.ai/zcj/43d6sxxr8ww4/functions/v1/api-gateway/contacts/search` with your filters, then `POST …/contacts/unlock` with only the `pids` you will use, paying each call's 402 price quote.

## At a glance

- **Search:** `POST https://agents.bytemine.ai/zcj/43d6sxxr8ww4/functions/v1/api-gateway/contacts/search`, with filters in a JSON body
- **Unlock:** `POST https://agents.bytemine.ai/zcj/43d6sxxr8ww4/functions/v1/api-gateway/contacts/unlock` with `{"pids": [...]}`, or `GET https://agents.bytemine.ai/zcj/43d6sxxr8ww4/functions/v1/api-gateway/contacts/{contactId}` for one full profile by contact ID
- **Price:** $0.01 per record returned. $0.01 per contact unlocked or fetched by ID.
- **Payment:** each request answers with a 402 price quote, paid from a wallet over x402 or MPP, or drawn from prepaid Credits. No account or API key is needed.
- **Search response:** `data[]` with `pid`, name, title, company and location fields, plus masked `email` and `phone`. Also `pagination` and `credits_used`.
- **Unlock response:** `data[]` with `pid`, `email`, `work_email`, `personal_email`, `phone` and `email_source`, plus `credits_used`
- **Limits:** `pageSize` defaults to 20, with a maximum of 100. `page` is 0-indexed.
- **Full purchase flow:** [the buyer skill](https://agents.bytemine.ai/zcj/43d6sxxr8ww4/SKILL.md)

## Choose the search filters

Each list filter takes a string, an array of strings, or an array of `{"value": "...", "included": true}` objects.

| To find people by | Field | Example value |
| --- | --- | --- |
| Role | `jobTitles` | `["VP of Sales", "Head of Sales"]` |
| Level | `seniorityLevels` | `["VP", "Director"]` |
| Function | `departments` | `["Sales"]` |
| Employer | `companyNames` or `urls` | `["Example Inc"]`, `["example.com"]` |
| Sector | `industries`, `naicsCodes`, `sicCodes` | `["Information Technology and Services"]`, `["5112"]` |
| Company size | `employeeSizes` | `["51-200"]` |
| Place | `cities`, `states` (US, 2-letter codes) | `["Austin"]`, `["TX"]` |
| Background | `skills`, `schools` | `["Salesforce"]`, `["Example University"]` |
| Reachability | `hasPhone`, `hasPhoneCell`, `hasWorkEmail`, `hasDirectDialOnly`, `hasPersonalEmailOnly` | `true` |

`seniorityLevels` accepts `Owner`, `Partner`, `C-Team`, `VP`, `Director`, `Manager`, `Senior`, `Entry` and `Training`.

## Search wide, then unlock the contacts you use

1. Send the search:

   ```bash
   curl -s -X POST https://agents.bytemine.ai/zcj/43d6sxxr8ww4/functions/v1/api-gateway/contacts/search \
     -H 'Content-Type: application/json' \
     -d '{"jobTitles": ["VP of Sales", "Head of Sales"], "seniorityLevels": ["VP", "Director"], "industries": ["Information Technology and Services"], "states": ["TX"], "hasWorkEmail": true, "pageSize": 25}'
   ```

   The storefront returns a 402 with `payment.amountUsd` and a challenge for each rail. That amount can be a ceiling. You are charged only for the records the search returns, and the `zc-billing` response header reports `chargedUsd`. Pay the quote and retry the same request. [The buyer skill](https://agents.bytemine.ai/zcj/43d6sxxr8ww4/SKILL.md) has the steps.

2. Read the candidates. The paid response has this shape:

   ```json
   {
     "data": [
       {"pid": "<pid>", "first_name": "Alex", "last_name": "Example", "job_title": "VP of Sales",
        "seniority": "VP", "department": "Sales", "company_name": "Example Inc",
        "company_domain": "example.com", "company_industry": "Information Technology and Services",
        "company_employee_range": "51-200", "city": "Austin", "state": "TX", "country": "US",
        "linkedin_url": "https://linkedin.com/in/alex-example",
        "email": "<masked>", "phone": "<masked>"}
     ],
     "pagination": {"page": 0, "page_size": 25, "total": 0, "has_more": true},
     "credits_used": 0
   }
   ```

   Use the title, company and location fields to decide whom you need. Keep the `pid` of each person you choose.

3. Unlock only the chosen contacts:

   ```bash
   curl -s -X POST https://agents.bytemine.ai/zcj/43d6sxxr8ww4/functions/v1/api-gateway/contacts/unlock \
     -H 'Content-Type: application/json' \
     -d '{"pids": ["<pid-1>", "<pid-2>"]}'
   ```

   The 402 quotes $0.01 per contact. After payment, the response is:

   ```json
   {"data": [{"pid": "<pid-1>", "email": "alex@example.com", "work_email": "alex@example.com",
     "personal_email": "alex.example@example.com", "phone": "555-0100", "email_source": "<source>"}],
    "credits_used": 0}
   ```

4. Fetch more candidates by sending the same body with `"page": 1`, then `2`, and so on, while `pagination.has_more` is true. Each page is billed per record returned.

## Budget a list

The cost of a list is the records you search plus the contacts you unlock.

| Plan | Cost |
| --- | --- |
| One page of 100 results, unlock 10 | $1.10 |
| Five pages of 20 results, unlock 25 | $1.25 |
| One page of 100 results, unlock all 100 | $2 |

A card can pay a pay-as-you-go call only when that call costs $0.50 or more. A smaller search or unlock needs a wallet rail or prepaid Credits. Credits start at $0.50, or $0.50 by card, and calls draw down the balance. Buying Credits needs a bearer credential, which is the agent identity the storefront issues at [auth.md](https://agents.bytemine.ai/zcj/43d6sxxr8ww4/auth.md). The purchase is `POST /plans/{planId}/purchase`, with the plan ID taken from [the catalog](https://agents.bytemine.ai/zcj/43d6sxxr8ww4/manifest.json).

## Boundaries

- Search results carry masked `email` and `phone`. Contact details come only from unlock or from `GET …/contacts/{contactId}`.
- Search bills per record returned, not per request or per page. Unlock bills per contact.
- Once a paid call is forwarded, Bytemine's own status code and body come back, including its own errors.

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `402` with no `reason` | The price quote for this call | Pay it and retry the same request, or stop |
| `400 invalid_request` | The body is malformed | Fix the JSON and resend |
| `settlement_failed` | The payment did not settle, and `settlementReason` says why | Fix the wallet, then send a fresh request for a new 402 |
| `409 payment_request_mismatch` | A payment was reused for a different request | Request a fresh 402 for the new body |
| `usage_exhausted` | The Credits balance is used up | Top up with `POST https://agents.bytemine.ai/zcj/43d6sxxr8ww4/extend` and `{"amountUsd": "..."}` |
| `401 bearer_required` | A Credits purchase was sent without an agent credential | Register at [auth.md](https://agents.bytemine.ai/zcj/43d6sxxr8ww4/auth.md), or pay per call |

## Frequently asked questions

### Does the contact search API charge for contacts I don't unlock?

Yes for the search, no for the unlock. Every record a search returns is billed at $0.01. The $0.01 unlock charge applies only to the `pids` you send to the unlock endpoint.

### What does a prospect search return before unlocking?

Each record includes the `pid`, name, job title, seniority, department, company name, domain, industry and size, location, LinkedIn URL and headline. The email and phone are masked until you unlock the contact.

### How much does a list of 50 contacts cost?

Searching 100 candidates and unlocking 50 of them costs $1.50. The 402 states the exact amount before each payment.

### Can I call the prospecting API without an account or API key?

Yes. Pay-as-you-go calls are paid one at a time over x402 or MPP and need no account, key or credential. Buying Credits needs the agent identity the storefront issues.

### How do I get the next page of search results?

Send the same filters with `page` set to the next number, starting from `0`. Stop when `pagination.has_more` is false.

## Keep reading

- [Buyer skill](https://agents.bytemine.ai/zcj/43d6sxxr8ww4/SKILL.md): the full purchase flow
- [How to pay](https://agents.bytemine.ai/zcj/43d6sxxr8ww4/payment.md): rails, ceiling pricing and Credits
- [Prospect Finder API reference](https://agents.bytemine.ai/zcj/43d6sxxr8ww4/services/prospect-finder/openapi.json): request and response schemas
- [Error reference](https://agents.bytemine.ai/zcj/43d6sxxr8ww4/errors.md): every error code

---

Updated 2026-10-16. All Bytemine guides: https://agents.bytemine.ai/guides.md. Storefront: https://agents.bytemine.ai/zcj/43d6sxxr8ww4/llms.txt.