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

# Phone Breaches

> Check whether a phone number has appeared in known data breaches, with the exposure count and first/last-seen dates. Costs 1 credit.

## Overview

Phone Breaches tells you whether a phone number has been exposed in known data
breaches, and how many times. Use it to flag high-risk numbers during sign-up,
account recovery, or fraud review.

There are three ways to run it:

* **Agent API** (`POST /api/agent/phone-breaches`): the API-key endpoint
  documented on this page, for programmatic access.
* **In-app** (`POST /api/phone/breaches`): the session-authenticated endpoint
  used by the dashboard. First lookup of a number costs 1 credit; repeats of the
  same number are free for the same customer for six months.
* **Bulk** (`POST /api/phone-jobs` with `{"feature": "breaches"}`): enqueue an
  async job that checks up to 1,000,000 numbers with background workers; poll
  `GET /api/phone-jobs?id=<id>` for progress and download results as CSV.

## Authentication

Requires an API key in the `Authorization` header.

```bash theme={"dark"}
Authorization: Bearer YOUR_API_KEY
```

## Request

<ParamField body="query" type="string" required>
  The phone number to check. Include the country code (e.g. `+14155552671`).
</ParamField>

### Example request

<CodeGroup>
  ```bash cURL (API Key) theme={"dark"}
  curl -X POST "https://encrata.com/api/agent/phone-breaches" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "+14155552671"}'
  ```

  ```python Python theme={"dark"}
  import requests

  resp = requests.post(
      "https://encrata.com/api/agent/phone-breaches",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={"query": "+14155552671"},
  )
  print(resp.json())
  ```
</CodeGroup>

## Response

```json theme={"dark"}
{
  "phone": "+14155552671",
  "breached": true,
  "total_breaches": 3,
  "first_breached": "2016-05-01",
  "last_breached": "2021-11-01",
  "summary": "Exposed in 3 known data breaches",
  "credits": 1
}
```

| Field            | Type    | Description                                                    |
| ---------------- | ------- | -------------------------------------------------------------- |
| `phone`          | string  | The normalized (E.164) phone number that was checked.          |
| `breached`       | boolean | Whether the number appears in any known breach.                |
| `total_breaches` | integer | How many known breaches the number appears in.                 |
| `first_breached` | string  | Date the number was first seen in a breach (if known).         |
| `last_breached`  | string  | Date the number was most recently seen in a breach (if known). |
| `summary`        | string  | A human-readable one-line verdict.                             |
| `credits`        | integer | Credits charged (always 1).                                    |

## Cost

1 credit per number checked (single and per-number in bulk).