> ## 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.

# Reverse Phone

> Find a person from their phone number.

## Use case

Identify the person behind a phone number — name, employer, title, LinkedIn, and other contact details. Use it to enrich inbound calls, qualify form submissions, deduplicate CRM records, or investigate unknown numbers.

## Endpoint

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

<Card title="API Reference" icon="code" href="/api-reference/enrichment/reverse-phone-lookup-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/reverse-phone" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "lead": {
        "phone": "+14155551234"
      }
    }'
  ```

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

  response = requests.post(
      "https://api.sixtyfour.ai/reverse-phone",
      headers={
          "x-api-key": "YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "lead": {
              "phone": "+14155551234"
          }
      }
  )
  response.raise_for_status()
  result = response.json()
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.sixtyfour.ai/reverse-phone", {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      lead: {
        phone: "+14155551234"
      }
    })
  });

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

## Async pattern

For production workflows, use `/reverse-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 /reverse-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 resolved person record is 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/reverse-phone-async",
      headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
      json={
          "lead": {
              "phone": "+14155551234"
          }
      }
  )
  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/reverse-phone-async", {
      method: "POST",
      headers: { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" },
      body: JSON.stringify({
        lead: { phone: "+14155551234" }
      })
    });
    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 /reverse-phone-async
{
  "lead": {
    "phone": "+14155551234"
  },
  "webhook_url": "https://your-server.com/webhooks/sixtyfour"
}
```

## Bulk processing

Use `/reverse-phone-bulk` (sync) or `/reverse-phone-bulk-async` (async) to resolve up to 100 phone numbers 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/reverse-phone-bulk" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "leads": [
        { "phone": "+14155551234" },
        { "phone": "+16195555678" }
      ]
    }'
  ```

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

  response = requests.post(
      "https://api.sixtyfour.ai/reverse-phone-bulk",
      headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
      json={
          "leads": [
              {"phone": "+14155551234"},
              {"phone": "+16195555678"}
          ]
      }
  )
  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/reverse-phone-bulk-async",
      headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
      json={
          "leads": [
              {"phone": "+14155551234"},
              {"phone": "+16195555678"}
          ]
      }
  )
  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>