Phone Number Labels

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

{
  "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

curl https://api.thunderphone.com/v1/phone-number-labels \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Returns an array of Label objects, 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.

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"
  }'

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()

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

Returns 200 OK with the Label object — both insert and update cases return the same status because the endpoint is upsert-style.

Delete a label

curl -X DELETE https://api.thunderphone.com/v1/phone-number-labels/7 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Returns 204 No Content.

Phone Numbers

Manage numbers your agents answer on and call from.

Calls

Call history shows labels beside each external number.

Overview

Organizations

Agents

Phone Numbers

Calls

Billing

Developer

Endpoints

Label object

List labels

Upsert a label

Delete a label

Phone Numbers

Calls

​Endpoints

​Label object

​List labels

​Upsert a label

​Delete a label

​Related

Phone Numbers

Calls

Endpoints

Label object

List labels

Upsert a label

Delete a label

Related