Skip to main content
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

MethodPathDescription
GET/v1/phone-number-labelsList labels
POST/v1/phone-number-labelsUpsert 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"
}
FieldTypeDescription
idintegerLabel id used by the delete endpoint
phone_numberstringE.164-formatted phone number being labeled
labelstringDisplay text, 1–100 chars
created_at, updated_attimestampISO 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"
  }'
FieldTypeRequiredDescription
phone_numberstringyesE.164-formatted
labelstringyes1–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.