# Lookup

Check and format a phone number, and look up the caller name registered for it. Paths are relative to
`https://api.contactivity.io/v1/projects/{project_id}`; see the [overview](/guides/overview.md).

| Method | Path | Scope | Purpose |
|---|---|---|---|
| GET | `/lookup/{phone_number}` | `lookup:read` | Validate and format a number; with `fields=caller_name`, also its caller name |
| GET | `/lookups` | `lookup:read` | List caller name lookups, newest first (paged) |

`{phone_number}` is E.164, URL-encoded: `+12125550100` is `%2B12125550100`.

## Validate and format (free)

Without `fields`, a lookup only checks and formats the number. It is free and is not listed in `/lookups`.

```bash
curl https://api.contactivity.io/v1/projects/$PROJECT_ID/lookup/%2B12125550100 \
  -H "Authorization: Bearer $API_KEY"
```

```json
{
  "phone_number": "+12125550100",
  "country": "US",
  "calling_country_code": "1",
  "national_format": "(212) 555-0100",
  "valid": true,
  "caller_name": null,
  "price": {"amount": "0.000000", "currency": "USD"}
}
```

| Field | Description |
|---|---|
| `phone_number` | The number in E.164 |
| `country` | ISO country code, or `null` when unknown |
| `calling_country_code` | The country calling code, without `+` |
| `national_format` | The number as dialed in its country (`+1` numbers only; `null` otherwise) |
| `valid` | Whether the number can be a real number in its country |
| `caller_name` | `null` unless `fields=caller_name` |
| `price` | What this request cost |

## Caller name

Add `fields=caller_name` to look up the name registered for the number. US and Canada (`+1`) numbers only.

```bash
curl "https://api.contactivity.io/v1/projects/$PROJECT_ID/lookup/%2B12125550100?fields=caller_name" \
  -H "Authorization: Bearer $API_KEY"
```

```json
{
  "id": "lk_us1_6f0c1d2e3a4b5c6d7e8f9a0b",
  "phone_number": "+12125550100",
  "fields": ["caller_name"],
  "country": "US",
  "calling_country_code": "1",
  "national_format": "(212) 555-0100",
  "valid": true,
  "caller_name": {"name": "ACME CORP", "error_code": null},
  "price": {"amount": "0.010000", "currency": "USD"},
  "created_at": "2026-10-30T14:03:11.123Z"
}
```

`caller_name.name` is the name, up to 15 characters, or `null`. `caller_name.error_code` says why there is no name:

| `error_code` | Meaning | Charged |
|---|---|---|
| `null` | A name was found | Yes |
| `not_found` | No name is registered for the number | Yes |
| `unavailable` | The lookup could not be done right now; try again later | No |

Each caller name lookup is stored and listed in `GET /lookups` (`{data, has_more, next_cursor}`, `limit` and
`starting_after` as in every list). Lookups are never deleted.

## Pricing

- Validation and formatting (no `fields`) are free.
- Each `fields=caller_name` request is charged the caller name price, including a repeat lookup of the same number.
- A lookup with `error_code: "unavailable"` is not charged.

The price is in `GET /pricing` under `number_features.lookup_caller_name` (`null`: not offered on your account) and
on the portal's **Pricing** page. Charges show in your ledger as **Lookup**. Your balance must be above zero.

## Errors

| Status | `code` | When |
|---|---|---|
| 400 | `invalid_parameter` (`param: phone_number`) | The number is not E.164 |
| 400 | `invalid_parameter` (`param: fields`) | An unknown field, or `caller_name` for a number outside `+1` |
| 402 | `insufficient_balance` | Your balance is zero or below |
| 403 | `insufficient_scope` | The API key does not have `lookup:read` |
| 409 | `feature_unavailable` | Caller name lookup is not offered on your account |

## Twilio-compatible route

Code written for Twilio Lookup v2 can call
`GET https://api.contactivity.io/compat/twilio/v2/PhoneNumbers/{PhoneNumber}?Fields=caller_name` with the same
Basic credentials as the other Twilio-compatible routes. The response has Twilio's shape (`caller_name`,
`caller_type`, `error_code`); billing is the same as above. See the
[compatibility guide](/guides/compat-migration.md#twilio-lookup).
