> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sixtyfour.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Find Phone

> Find phone numbers for people.

## Use case

Discover phone numbers for leads for sales outreach, CRM enrichment, or lead qualification.

## Endpoint

```http theme={null}
POST https://api.sixtyfour.ai/find-phone
```

<Card title="API Reference" icon="code" href="/api-reference/enrichment/find-phone-sync">
  See the full request/response schema and parameters in the API Reference.
</Card>

## Pricing

See [Credits & Pricing Guide](/guides/credits-and-pricing) for credit costs.

## Errors

For error responses (400, 403, 422, etc.), see [Handling Errors](/api-reference/errors).

## Sync usage

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.sixtyfour.ai/find-phone" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "lead": {
        "name": "Sarah Johnson",
        "company": "TechCorp Inc",
        "linkedin_url": "https://linkedin.com/in/sarahjohnson"
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.sixtyfour.ai/find-phone",
      headers={
          "x-api-key": "YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "lead": {
              "name": "Sarah Johnson",
              "company": "TechCorp Inc",
              "linkedin_url": "https://linkedin.com/in/sarahjohnson"
          }
      }
  )
  response.raise_for_status()
  result = response.json()
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.sixtyfour.ai/find-phone", {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      lead: {
        name: "Sarah Johnson",
        company: "TechCorp Inc",
        linkedin_url: "https://linkedin.com/in/sarahjohnson"
      }
    })
  });

  const result = await response.json();
  ```
</CodeGroup>

## Async pattern

For production workflows, use `/find-phone-async` to submit a job and poll for results. This avoids long-lived HTTP connections and lets you parallelize many lookups without blocking your client.

The flow is:

1. **Submit** — `POST /find-phone-async` with the same body as the sync endpoint. Response includes a `task_id`.
2. **Poll** — `GET /job-status/{task_id}` until `status` is `completed`, `failed`, or `cancelled`.
3. **Read result** — When `completed`, the discovered phone numbers are in the `result` field, in the same shape as the sync response.

<Note>The async start endpoint returns uppercase `RUNNING`. Subsequent `/job-status/{task_id}` calls return lowercase statuses. `charge_amount` is returned in cents, not credits.</Note>

### Polling example

<CodeGroup>
  ```python Python theme={null}
  import requests
  import time

  response = requests.post(
      "https://api.sixtyfour.ai/find-phone-async",
      headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
      json={
          "lead": {
              "name": "Sarah Johnson",
              "company": "TechCorp Inc",
              "linkedin_url": "https://linkedin.com/in/sarahjohnson"
          }
      }
  )
  response.raise_for_status()
  task_id = response.json()["task_id"]

  while True:
      status = requests.get(
          f"https://api.sixtyfour.ai/job-status/{task_id}",
          headers={"x-api-key": "YOUR_API_KEY"}
      ).json()

      if status["status"] == "completed":
          results = status["result"]
          break
      if status["status"] in ("failed", "cancelled"):
          raise RuntimeError(f"Job {status['status']}: {status.get('error', 'Unknown error')}")

      time.sleep(5)
  ```

  ```javascript JavaScript theme={null}
  async function runAsync() {
    const start = await fetch("https://api.sixtyfour.ai/find-phone-async", {
      method: "POST",
      headers: { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" },
      body: JSON.stringify({
        lead: {
          name: "Sarah Johnson",
          company: "TechCorp Inc",
          linkedin_url: "https://linkedin.com/in/sarahjohnson"
        }
      })
    });
    if (!start.ok) throw new Error(`Submit failed: ${start.status}`);
    const { task_id } = await start.json();

    while (true) {
      const pollRes = await fetch(
        `https://api.sixtyfour.ai/job-status/${task_id}`,
        { headers: { "x-api-key": "YOUR_API_KEY" } }
      );
      if (!pollRes.ok) throw new Error(`Poll failed: ${pollRes.status}`);
      const status = await pollRes.json();

      if (status.status === "completed") return status.result;
      if (["failed", "cancelled"].includes(status.status)) {
        throw new Error(`Job ${status.status}: ${status.error || "Unknown error"}`);
      }
      await new Promise(r => setTimeout(r, 5000));
    }
  }
  ```
</CodeGroup>

### Webhook callback

Pass a `webhook_url` to receive the result via HTTP POST instead of polling. The signed payload, retry behavior, and verification steps are documented in [Outgoing Webhooks](/api-reference/webhooks/outgoing).

```json theme={null}
POST /find-phone-async
{
  "lead": {
    "name": "Sarah Johnson",
    "company": "TechCorp Inc",
    "linkedin_url": "https://linkedin.com/in/sarahjohnson"
  },
  "webhook_url": "https://your-server.com/webhooks/sixtyfour"
}
```

## Bulk processing

Use `/find-phone-bulk` (sync) or `/find-phone-bulk-async` (async) to process up to 100 leads in a single call. Both accept a `leads` array and the same `providers` and `webhook_url` fields as the single-lead endpoints.

### Bulk sync

Returns 200 OK with results once every lead is processed. Best for small batches where you want a single round-trip.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.sixtyfour.ai/find-phone-bulk" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "leads": [
        {
          "name": "Sarah Johnson",
          "company": "TechCorp Inc",
          "linkedin_url": "https://linkedin.com/in/sarahjohnson"
        },
        {
          "name": "John Doe",
          "company": "Example Corp",
          "linkedin_url": "https://linkedin.com/in/johndoe"
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.sixtyfour.ai/find-phone-bulk",
      headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
      json={
          "leads": [
              {
                  "name": "Sarah Johnson",
                  "company": "TechCorp Inc",
                  "linkedin_url": "https://linkedin.com/in/sarahjohnson"
              },
              {
                  "name": "John Doe",
                  "company": "Example Corp",
                  "linkedin_url": "https://linkedin.com/in/johndoe"
              }
          ]
      }
  )
  response.raise_for_status()
  results = response.json()
  ```
</CodeGroup>

### Bulk async

Submit a batch, get back a `task_id`, then poll `/job-status/{task_id}` (or set `webhook_url` to receive a callback). Recommended for batches of more than a handful of leads, or when you don't want to hold a long-lived HTTP connection.

<CodeGroup>
  ```python Python theme={null}
  import requests
  import time

  response = requests.post(
      "https://api.sixtyfour.ai/find-phone-bulk-async",
      headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
      json={
          "leads": [
              {
                  "name": "Sarah Johnson",
                  "company": "TechCorp Inc",
                  "linkedin_url": "https://linkedin.com/in/sarahjohnson"
              },
              {
                  "name": "John Doe",
                  "company": "Example Corp",
                  "linkedin_url": "https://linkedin.com/in/johndoe"
              }
          ]
      }
  )
  response.raise_for_status()
  task_id = response.json()["task_id"]

  while True:
      status = requests.get(
          f"https://api.sixtyfour.ai/job-status/{task_id}",
          headers={"x-api-key": "YOUR_API_KEY"}
      ).json()

      if status["status"] == "completed":
          results = status["result"]
          break
      if status["status"] in ("failed", "cancelled"):
          raise RuntimeError(f"Job {status['status']}: {status.get('error', 'Unknown error')}")

      time.sleep(10)
  ```
</CodeGroup>