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

> Look up intelligence about a phone number carrier, line type, format, country, messaging gateway, validation, risk assessment, and breach exposure. Costs 1 credit.

## 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 look up. 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" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "+14155552671"}'
  ```

  ```python Python theme={"dark"}
  from encrata import Encrata

  client = Encrata("YOUR_API_KEY")
  result = client.phone_lookup("+14155552671")

  print(result.carrier.name)       # "T-Mobile"
  print(result.country.name)       # "United States"
  print(result.validation.is_voip) # False
  ```

  ```javascript JavaScript theme={"dark"}
  const resp = await fetch("https://encrata.com/api/agent/phone", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query: "+14155552671" }),
  });
  const data = await resp.json();
  ```

  ```go Go theme={"dark"}
  body := `{"query": "+14155552671"}`
  req, _ := http.NewRequest("POST", "https://encrata.com/api/agent/phone",
      strings.NewReader(body))
  req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
  req.Header.Set("Content-Type", "application/json")
  resp, _ := http.DefaultClient.Do(req)
  ```
</CodeGroup>

## Response

<ResponseField name="query" type="string">
  The original query submitted.
</ResponseField>

<ResponseField name="phone" type="string">
  The normalized phone number.
</ResponseField>

<ResponseField name="valid" type="boolean">
  Whether the phone number is valid.
</ResponseField>

<ResponseField name="format" type="object">
  Phone number formats.

  <Expandable title="format fields">
    <ResponseField name="international" type="string">
      International format (e.g. `+1 415-555-2671`).
    </ResponseField>

    <ResponseField name="local" type="string">
      Local format (e.g. `(415) 555-2671`).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="country" type="object">
  Country and location details.

  <Expandable title="country fields">
    <ResponseField name="code" type="string">
      ISO country code (e.g. `US`).
    </ResponseField>

    <ResponseField name="name" type="string">
      Country name (e.g. `United States`).
    </ResponseField>

    <ResponseField name="prefix" type="string">
      Country calling code (e.g. `+1`).
    </ResponseField>

    <ResponseField name="region" type="string">
      Region or state.
    </ResponseField>

    <ResponseField name="city" type="string">
      City name.
    </ResponseField>

    <ResponseField name="timezone" type="string">
      Timezone (e.g. `America/Los_Angeles`).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="type" type="string">
  Line type: `mobile`, `landline`, `voip`, `toll_free`, etc.
</ResponseField>

<ResponseField name="carrier" type="object">
  Carrier information.

  <Expandable title="carrier fields">
    <ResponseField name="name" type="string">
      Carrier name (e.g. `T-Mobile`).
    </ResponseField>

    <ResponseField name="line_type" type="string">
      Line type according to the carrier.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="messaging" type="object">
  SMS gateway information.

  <Expandable title="messaging fields">
    <ResponseField name="sms_domain" type="string">
      SMS gateway domain (e.g. `tmomail.net`).
    </ResponseField>

    <ResponseField name="sms_email" type="string">
      SMS-to-email address (e.g. `4155552671@tmomail.net`).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="validation" type="object">
  Validation and activity signals.

  <Expandable title="validation fields">
    <ResponseField name="is_valid" type="boolean">
      Whether the number is currently valid/active.
    </ResponseField>

    <ResponseField name="line_status" type="string">
      Line status: `active`, `inactive`, `unknown`.
    </ResponseField>

    <ResponseField name="is_voip" type="boolean">
      Whether the number is VoIP.
    </ResponseField>

    <ResponseField name="minimum_age" type="integer">
      Estimated minimum age of the line in years.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="registration" type="object">
  Registration information.

  <Expandable title="registration fields">
    <ResponseField name="name" type="string">
      Registered name (if available).
    </ResponseField>

    <ResponseField name="type" type="string">
      Registration type: `personal`, `business`, etc.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="risk" type="object">
  Risk assessment.

  <Expandable title="risk fields">
    <ResponseField name="risk_level" type="string">
      Risk level: `low`, `medium`, `high`.
    </ResponseField>

    <ResponseField name="is_disposable" type="boolean">
      Whether this is a disposable/burner number.
    </ResponseField>

    <ResponseField name="is_abuse_detected" type="boolean">
      Whether abuse has been detected on this number.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="breaches" type="object">
  Breach exposure data.

  <Expandable title="breaches fields">
    <ResponseField name="total_breaches" type="integer">
      Number of data breaches the phone number appears in.
    </ResponseField>

    <ResponseField name="date_first_breached" type="string">
      Date of first known breach.
    </ResponseField>

    <ResponseField name="date_last_breached" type="string">
      Date of most recent breach.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="credits" type="integer">
  Credits consumed (always 1).
</ResponseField>

### Example response

```json 200 OK theme={"dark"}
{
  "query": "+14155552671",
  "phone": "+14155552671",
  "valid": true,
  "format": {
    "international": "+1 415-555-2671",
    "local": "(415) 555-2671"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "prefix": "+1",
    "region": "California",
    "city": "San Francisco",
    "timezone": "America/Los_Angeles"
  },
  "location": "San Francisco, California, US",
  "type": "mobile",
  "carrier": {
    "name": "T-Mobile",
    "line_type": "mobile"
  },
  "messaging": {
    "sms_domain": "tmomail.net",
    "sms_email": "4155552671@tmomail.net"
  },
  "validation": {
    "is_valid": true,
    "line_status": "active",
    "is_voip": false,
    "minimum_age": 3
  },
  "registration": {
    "name": "John Doe",
    "type": "personal"
  },
  "risk": {
    "risk_level": "low",
    "is_disposable": false,
    "is_abuse_detected": false
  },
  "breaches": {
    "total_breaches": 2,
    "date_first_breached": "2021-03-15",
    "date_last_breached": "2024-08-22"
  },
  "credits": 1
}
```

## Notes

* This endpoint costs **1 credit** per lookup.
* Include the country code for best results (e.g. `+1` for US, `+44` for UK).
* All sections (messaging, validation, registration, risk, breaches) are returned when available from the upstream provider.