Phone Numbers

Phone Number Labels

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#

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

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

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.

Related#