# Mobile number finder API: find a direct dial with Scalelist

Scalelist's Mobile Number Finder returns a person's direct mobile number from one identifier: a LinkedIn profile URL, a work email, or a name with a company. A found number costs $0.58, drawn from Prepaid lead data credit bought by card, and a lookup that finds nothing is free. Send `POST https://agents.scalelist.com/zcj/otnorztzrszr/agent/phone/find` with a JSON body and your agent credential as a bearer.

## At a glance

- **Endpoint:** `POST https://agents.scalelist.com/zcj/otnorztzrszr/agent/phone/find`, one person per request
- **Body:** `linkedin_profile_url`, or `email`, or a name (`first_name` or `full_name`) with a company (`company_domain` or `company_name`). Optional: `last_name`, `job_title`, `city`, `linkedin_id`, `custom`.
- **Price:** $0.58, charged only when `status` is `found`
- **Payment:** card only, through prepaid credit on the Prepaid lead data plan, with a minimum card purchase of $1. Pay as you go does not cover this service.
- **Credential:** an agent credential on every call, as `Authorization: Bearer <token>`. Registering one is a free call ([auth.md](https://agents.scalelist.com/zcj/otnorztzrszr/auth.md)).
- **Response:** `request_id`, `phone` (a string, or `null`), `status` (`found` or `not_found`)
- **Full purchase flow:** [the buyer skill](https://agents.scalelist.com/zcj/otnorztzrszr/SKILL.md)

## Choose the identifier to send

One identifier is enough. Extra details narrow the match when names collide.

| What you have | Fields to send |
| --- | --- |
| A LinkedIn profile URL (the most accurate input) | `linkedin_profile_url` |
| LinkedIn's internal id for the person | `linkedin_id` |
| A work email | `email` |
| A name and a company | `first_name` or `full_name`, plus `company_domain` or `company_name`. `last_name` is optional. |
| Two people at one company with the same name | Add `job_title` |
| Same-name people in different places | Add `city` |

A first name alone is not enough to search on. An `email` sent with other details sharpens the match. `custom` takes a row id or list name, which the result carries back unchanged.

## Find a mobile number

1. Get an access token. Register once at [auth.md](https://agents.scalelist.com/zcj/otnorztzrszr/auth.md), exchange the assertion, and keep the token in `ACCESS_TOKEN`. Reuse an existing credential if you hold one.

2. Check that you hold Prepaid lead data credit:

   ```bash
   curl -s https://agents.scalelist.com/zcj/otnorztzrszr/agent/entitlements -H "Authorization: Bearer $ACCESS_TOKEN"
   ```

   A 200 lists your active plans with `remainingCreditUsd`. With no credit, buy Prepaid lead data by card, at least $1; [the buyer skill](https://agents.scalelist.com/zcj/otnorztzrszr/SKILL.md) and [card payment](https://agents.scalelist.com/zcj/otnorztzrszr/payment/card.md) carry the purchase.

3. Send the lookup:

   ```bash
   curl -s -X POST https://agents.scalelist.com/zcj/otnorztzrszr/agent/phone/find \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"first_name": "Alex", "last_name": "Example", "company_domain": "example.com", "custom": {"row": "42"}}'
   ```

   With an email, send `{"email": "alex@example.com"}`. With a profile, send `{"linkedin_profile_url": "https://www.linkedin.com/in/<profile-id>"}`.

4. Read the result:

   ```json
   {"request_id": "<id>", "phone": "<mobile number>", "status": "found"}
   ```

   `status: "found"` carries the number and draws $0.58 from credit. `status: "not_found"` returns `phone: null` and costs nothing. A credit-funded response carries a `zc-billing` header with `chargedUsd` and `remainingCreditUsd`. A response without that header billed nothing.

## Call it after the email finder or people search

The phone lookup takes the identifiers the other Scalelist services return, from the same credit balance.

| Earlier call | Field it returns | Send it as |
| --- | --- | --- |
| B2B Email Finder (`POST /agent/email/find`) | `email` | `email` |
| People Search (`POST /agent/people/search`) | `linkedin_url` on each profile | `linkedin_profile_url` |
| Domain Email Finder (`POST /agent/email/domain`) | `email` and `linkedin_url` on each contact | `linkedin_profile_url`, or `email` |

Send one phone request per person.

## What is charged and what is not

- This service is paid only from Prepaid lead data credit, bought by card. Lookups draw it down; unused credit stays on the balance. Top up with `POST https://agents.scalelist.com/zcj/otnorztzrszr/extend` and `{"amountUsd": "<amount>"}`.
- A `not_found` lookup and a `503` are free.
- The endpoint finds a direct mobile number. For a work email, use the B2B Email Finder.

## Errors

| Status | Meaning | Action |
| --- | --- | --- |
| `401 bearer_required` | No agent credential on the call | Register at [auth.md](https://agents.scalelist.com/zcj/otnorztzrszr/auth.md) and retry with the bearer |
| `401 invalid_token` | The token did not verify or expired | Exchange the stored assertion for a fresh token |
| `403 plan_required` | No plan with credit covers the call | Buy Prepaid lead data from the `purchase.url` in the body, then retry |
| `usage_exhausted` | The credit balance is used up | Top up with `POST https://agents.scalelist.com/zcj/otnorztzrszr/extend` |
| `400` | A field has the wrong type | Fix the body |
| `422` | Not enough to search on, such as a name with no company | Add a company, or send a profile URL or email |
| `409` | This request was already served | Use the earlier result instead of resending |
| `429` | Too many requests from this agent | Wait, then retry |
| `503` | Temporarily unavailable, not charged | Retry later |

## Frequently asked questions

### Is a lookup charged when no mobile number is found?

No. Credit is drawn only when the response has `status: "found"`. A `not_found` result returns `phone: null` and costs nothing, and the `zc-billing` header shows what a found number drew.

### Can I find a mobile number from an email address alone?

Yes. A work email in `email` is enough on its own. A LinkedIn profile URL in `linkedin_profile_url` is also enough on its own and is the most accurate input.

### Can I pay for one phone lookup by card without buying credit?

No. The Mobile Number Finder is sold on the Prepaid lead data credit plan, not pay as you go. Buy credit by card, with a minimum of $1, then each found number draws $0.58.

### Does the endpoint look up several people in one request?

`POST /agent/phone/find` takes one person's identifiers per request, so a list of prospects on this endpoint is one request per person.

## Keep reading

- [Buyer skill](https://agents.scalelist.com/zcj/otnorztzrszr/SKILL.md): the full purchase flow
- [Mobile Number Finder](https://agents.scalelist.com/zcj/otnorztzrszr/services/phone-finder): the service page with its price and plan
- [How to pay](https://agents.scalelist.com/zcj/otnorztzrszr/payment.md): credit, top-ups and the `zc-billing` header
- [Identity](https://agents.scalelist.com/zcj/otnorztzrszr/auth.md): register and exchange an agent credential
- [Error reference](https://agents.scalelist.com/zcj/otnorztzrszr/errors.md): every error code

---

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