---
title: "Find mobile numbers in bulk"
method: POST
path: "/api/v1/phone/find/bulk"
tags: ["Phone Enrichment"]
---

# Find mobile numbers in bulk

`POST /api/v1/phone/find/bulk`

## Request

- Base URL: `https://api.scalelist.com`
- URL: `https://api.scalelist.com/api/v1/phone/find/bulk`
- Auth: API key in header `x-api-key`

Find up to 100 mobile numbers in one call. Returns a task id straight away; results arrive later.

• Supply `webhook_url` and the results are POSTed there when the batch finishes.
• Or poll `GET /phone/find/bulk?job_id=<task_id>` whenever you like.

**10 credits per number found.** Send an `Idempotency-Key` header to make retries safe for 24h.

## Headers

- `idempotency-key` string

## Request body

- object
  - `requests` union[], required
    - union
      - object
        - `linkedin_id` string, required: LinkedIn numeric member id (strongest signal, sufficient on its own)
        - `first_name` string: Pair with a company signal, or omit in favor of full_name
        - `last_name` string: Optional, may be omitted or empty
        - `full_name` string: Alternative to first_name + last_name. Split on whitespace; everything after the first token becomes the last name
        - `company_name` string: Required alongside a name signal (provide this OR company_domain)
        - `company_domain` string: Company domain without protocol or @ (provide this OR company_name)
        - `email` string: Known email, sufficient on its own; also boosts match precision when combined with other signals
        - `job_title` string: Optional, disambiguates same-name matches at the same company
        - `city` string: Optional, disambiguates same-name matches across regions
        - `linkedin_profile_url` string, uri: Full LinkedIn profile URL (sufficient on its own)
        - `custom` object: Arbitrary metadata echoed back verbatim in the per-lead result and webhook payload
      - object
        - `linkedin_id` string: LinkedIn numeric member id (strongest signal, sufficient on its own)
        - `first_name` string: Pair with a company signal, or omit in favor of full_name
        - `last_name` string: Optional, may be omitted or empty
        - `full_name` string: Alternative to first_name + last_name. Split on whitespace; everything after the first token becomes the last name
        - `company_name` string: Required alongside a name signal (provide this OR company_domain)
        - `company_domain` string: Company domain without protocol or @ (provide this OR company_name)
        - `email` string: Known email, sufficient on its own; also boosts match precision when combined with other signals
        - `job_title` string: Optional, disambiguates same-name matches at the same company
        - `city` string: Optional, disambiguates same-name matches across regions
        - `linkedin_profile_url` string, uri, required: Full LinkedIn profile URL (sufficient on its own)
        - `custom` object: Arbitrary metadata echoed back verbatim in the per-lead result and webhook payload
      - object
        - `linkedin_id` string: LinkedIn numeric member id (strongest signal, sufficient on its own)
        - `first_name` string: Pair with a company signal, or omit in favor of full_name
        - `last_name` string: Optional, may be omitted or empty
        - `full_name` string: Alternative to first_name + last_name. Split on whitespace; everything after the first token becomes the last name
        - `company_name` string: Required alongside a name signal (provide this OR company_domain)
        - `company_domain` string: Company domain without protocol or @ (provide this OR company_name)
        - `email` string, required: Known email, sufficient on its own; also boosts match precision when combined with other signals
        - `job_title` string: Optional, disambiguates same-name matches at the same company
        - `city` string: Optional, disambiguates same-name matches across regions
        - `linkedin_profile_url` string, uri: Full LinkedIn profile URL (sufficient on its own)
        - `custom` object: Arbitrary metadata echoed back verbatim in the per-lead result and webhook payload
      - object
        - `linkedin_id` string: LinkedIn numeric member id (strongest signal, sufficient on its own)
        - `first_name` string, required: Pair with a company signal, or omit in favor of full_name
        - `last_name` string: Optional, may be omitted or empty
        - `full_name` string: Alternative to first_name + last_name. Split on whitespace; everything after the first token becomes the last name
        - `company_name` string, required: Required alongside a name signal (provide this OR company_domain)
        - `company_domain` string: Company domain without protocol or @ (provide this OR company_name)
        - `email` string: Known email, sufficient on its own; also boosts match precision when combined with other signals
        - `job_title` string: Optional, disambiguates same-name matches at the same company
        - `city` string: Optional, disambiguates same-name matches across regions
        - `linkedin_profile_url` string, uri: Full LinkedIn profile URL (sufficient on its own)
        - `custom` object: Arbitrary metadata echoed back verbatim in the per-lead result and webhook payload
      - object
        - `linkedin_id` string: LinkedIn numeric member id (strongest signal, sufficient on its own)
        - `first_name` string, required: Pair with a company signal, or omit in favor of full_name
        - `last_name` string: Optional, may be omitted or empty
        - `full_name` string: Alternative to first_name + last_name. Split on whitespace; everything after the first token becomes the last name
        - `company_name` string: Required alongside a name signal (provide this OR company_domain)
        - `company_domain` string, required: Company domain without protocol or @ (provide this OR company_name)
        - `email` string: Known email, sufficient on its own; also boosts match precision when combined with other signals
        - `job_title` string: Optional, disambiguates same-name matches at the same company
        - `city` string: Optional, disambiguates same-name matches across regions
        - `linkedin_profile_url` string, uri: Full LinkedIn profile URL (sufficient on its own)
        - `custom` object: Arbitrary metadata echoed back verbatim in the per-lead result and webhook payload
      - object
        - `linkedin_id` string: LinkedIn numeric member id (strongest signal, sufficient on its own)
        - `first_name` string: Pair with a company signal, or omit in favor of full_name
        - `last_name` string: Optional, may be omitted or empty
        - `full_name` string, required: Alternative to first_name + last_name. Split on whitespace; everything after the first token becomes the last name
        - `company_name` string, required: Required alongside a name signal (provide this OR company_domain)
        - `company_domain` string: Company domain without protocol or @ (provide this OR company_name)
        - `email` string: Known email, sufficient on its own; also boosts match precision when combined with other signals
        - `job_title` string: Optional, disambiguates same-name matches at the same company
        - `city` string: Optional, disambiguates same-name matches across regions
        - `linkedin_profile_url` string, uri: Full LinkedIn profile URL (sufficient on its own)
        - `custom` object: Arbitrary metadata echoed back verbatim in the per-lead result and webhook payload
      - object
        - `linkedin_id` string: LinkedIn numeric member id (strongest signal, sufficient on its own)
        - `first_name` string: Pair with a company signal, or omit in favor of full_name
        - `last_name` string: Optional, may be omitted or empty
        - `full_name` string, required: Alternative to first_name + last_name. Split on whitespace; everything after the first token becomes the last name
        - `company_name` string: Required alongside a name signal (provide this OR company_domain)
        - `company_domain` string, required: Company domain without protocol or @ (provide this OR company_name)
        - `email` string: Known email, sufficient on its own; also boosts match precision when combined with other signals
        - `job_title` string: Optional, disambiguates same-name matches at the same company
        - `city` string: Optional, disambiguates same-name matches across regions
        - `linkedin_profile_url` string, uri: Full LinkedIn profile URL (sufficient on its own)
        - `custom` object: Arbitrary metadata echoed back verbatim in the per-lead result and webhook payload
  - `webhook_url` string, uri: Optional destination URL for the completion callback. When omitted, poll GET /phone/find/bulk?job_id=... for results.

## Response `202`

Task accepted (or idempotent replay of an earlier submission).

- object: Task accepted (or idempotent replay of an earlier submission).
  - `taskId` string: Mongo ObjectId of the durable search task.
  - `status` 'queued'
  - `total` integer: Number of lead requests queued.

## Other responses

- `400`: Validation error. `code` discriminates the specific cause: `idempotency_key_invalid` (bad header format) or `idempotency_key_reused` (same key, different body within 24h).
- `401`: Missing or unrecognised API key.
- `402`: Insufficient credits to start the batch.

---

[API](https://skmtc.dev/scalelist/apis/scalelist-api.md) · [All operations](https://skmtc.dev/scalelist/apis/scalelist-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scalelist/apis/scalelist-api/revisions/4863f1805423?raw)