---
title: "Phone Number Labels"
description: "Attach human-readable labels to external phone numbers so call history, transcripts, and exports show meaningful names instead of raw digits everywhere."
---

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
{
  "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
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
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
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
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="Manage numbers in the dashboard" icon="tags" href="/guides/get-a-phone-number#label-phone-numbers">
    Add, edit, and remove labels from Phone Numbers or call history.
  </Card>
  <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>