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

# Phone Number Labels

> Annotate external phone numbers with human-readable names that appear in call history.

Phone number labels let you tag the external numbers that call you or
that you call out to — e.g. "Aetna Insurance" for a specific
`+1-555-...` customer line. Labels are org-scoped (everyone in your org
shares the same label set) and are applied by E.164 number string, not
by phone-number resource id. Labels show up in the call detail view and
in call history exports.

## Endpoints

| Method   | Path                                 | Description                       |
| -------- | ------------------------------------ | --------------------------------- |
| `GET`    | `/v1/phone-number-labels`            | List labels                       |
| `POST`   | `/v1/phone-number-labels`            | Upsert a label for a phone number |
| `DELETE` | `/v1/phone-number-labels/{label_id}` | Delete a label                    |

## Label object

```json theme={null}
{
  "id": 7,
  "phone_number": "+15551234567",
  "label": "Aetna Insurance",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}
```

| Field                      | Type      | Description                                |
| -------------------------- | --------- | ------------------------------------------ |
| `id`                       | integer   | Label id used by the delete endpoint       |
| `phone_number`             | string    | E.164-formatted phone number being labeled |
| `label`                    | string    | Display text, 1–100 chars                  |
| `created_at`, `updated_at` | timestamp | ISO 8601 UTC                               |

***

## List labels

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.thunderphone.com/v1/phone-number-labels \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY"
  ```
</CodeGroup>

Returns an array of [Label objects](#label-object), sorted by
`phone_number` ascending.

***

## Upsert a label

Idempotent: if a label already exists for this phone number in your org,
it's updated; otherwise a new one is created.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.thunderphone.com/v1/phone-number-labels \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "phone_number": "+15551234567",
      "label": "Aetna Insurance"
    }'
  ```

  ```python Python theme={null}
  label = requests.post(
      "https://api.thunderphone.com/v1/phone-number-labels",
      headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
      json={"phone_number": "+15551234567", "label": "Aetna Insurance"},
  ).json()
  ```
</CodeGroup>

| Field          | Type   | Required | Description     |
| -------------- | ------ | -------- | --------------- |
| `phone_number` | string | yes      | E.164-formatted |
| `label`        | string | yes      | 1–100 chars     |

Returns `200 OK` with the [Label object](#label-object) — both insert
and update cases return the same status because the endpoint is
upsert-style.

***

## Delete a label

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.thunderphone.com/v1/phone-number-labels/7 \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY"
  ```
</CodeGroup>

Returns `204 No Content`.

***

## Related

<CardGroup cols={2}>
  <Card title="Phone Numbers" icon="phone" href="/api-reference/phone-numbers">
    Manage numbers your agents answer on and call from.
  </Card>

  <Card title="Calls" icon="phone" href="/api-reference/calls">
    Call history shows labels beside each external number.
  </Card>
</CardGroup>