Caller Registration

Set the caller name your ThunderPhone numbers show, and register numbers in your own Twilio or Telnyx account for caller name, verified caller ID and spam-filter registration.

These endpoints manage what carriers show and how they score your calls. The product guide is Caller ID and spam registration. Everything here is free.

• ThunderPhone numbers get the organization's caller name automatically: on purchase, and again whenever the caller name is saved.
• Numbers in your own carrier account are registered only when you ask: Telnyx numbers can get a caller name; Twilio numbers can get a caller name, verified caller ID (SHAKEN/STIR) and spam-filter registration (Twilio Voice Integrity). ThunderPhone uses the credentials saved on the number's VoIP connection.

Reads, and POST /refresh, are open to any organization role. Other changes need an admin or owner.

Endpoints#

Registration object#

{
  "id": 41,
  "phone_number_id": 812,
  "kind": "shaken_stir",
  "provider": "twilio",
  "status": "in_review",
  "display_name": "",
  "status_detail": "Twilio is reviewing it. This usually takes 1 to 3 days.",
  "trust_product_sid": "BU0123456789abcdef0123456789abcdef",
  "submitted_at": "2026-10-23T18:02:11.204Z",
  "checked_at": "2026-10-23T19:02:40.517Z",
  "updated_at": "2026-10-23T19:02:40.517Z"
}

ThunderPhone sends pending registrations within a few minutes and retries when the carrier is unreachable. It checks registrations under review about once an hour; carriers usually decide within 1 to 3 days. A registration whose number leaves your account, or its carrier account, turns off.

Get registrations#

curl https://api.thunderphone.com/v1/caller-registration \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

{
  "caller_name": {
    "caller_name": "",
    "enabled": true,
    "default_caller_name": "Acme Plumbing",
    "effective_caller_name": "Acme Plumbing",
    "max_length": 15
  },
  "numbers": [
    {
      "phone_number_id": 812,
      "number": "+12125550101",
      "label": "Main line",
      "number_type": "voip",
      "carrier": "twilio",
      "voip_connection_id": 37,
      "eligible_kinds": ["cnam", "shaken_stir", "voice_integrity"],
      "registrations": {
        "cnam": null,
        "shaken_stir": { "id": 41, "kind": "shaken_stir", "status": "in_review", "...": "..." },
        "voice_integrity": null
      }
    }
  ],
  "voice_integrity_use_cases": ["Appointment Reminders", "Customer Support", "..."],
  "twilio_trust_hub_url": "https://console.twilio.com/us1/account/trust-hub/overview"
}

Save the caller name#

Applies to every ThunderPhone number the organization has, and to numbers it buys later.

curl -X PUT https://api.thunderphone.com/v1/caller-registration/caller-name \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"caller_name": "Acme Plumbing", "enabled": true}'

Returns 200 OK with the same body as Get registrations. An invalid name returns 400 with the reason under caller_name.

Register numbers#

Registers numbers in the organization's own Twilio or Telnyx account. This changes that account: for Twilio, ThunderPhone adds each number to the account's Primary Business Profile, reuses the account's existing registration of that kind (or creates one), adds the numbers to it and submits it for review. Repeating a request never creates duplicates.

curl -X POST https://api.thunderphone.com/v1/caller-registration/register \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "voice_integrity",
    "phone_number_ids": [812, 813],
    "voice_integrity": {
      "use_case": "Appointment Reminders",
      "employee_count": 12,
      "daily_call_volume": 300
    }
  }'

Returns 202 Accepted with {"registrations": [...]} (status pending).

When the Twilio account already has a registration of that kind, the numbers join it. For voice_integrity the answers sent now are then not used; change them in Twilio's Trust Hub.

Check a Twilio Business Profile#

GET /v1/caller-registration/twilio-business-profile?connection_id=37 reads the Twilio account behind that connection.

{
  "connection_id": 37,
  "business_profile": {
    "sid": "BU0123456789abcdef0123456789abcdef",
    "friendly_name": "Acme Plumbing",
    "status": "twilio-approved",
    "approved": true
  },
  "console_url": "https://console.twilio.com/us1/account/trust-hub/overview"
}

business_profile is null when the account has none. status is Twilio's: draft, pending-review, in-review, twilio-approved or twilio-rejected.

Refresh status#

POST /v1/caller-registration/refresh reads every registration under review from the carrier now (each at most once a minute) and returns the same body as Get registrations.

Turn off a Telnyx caller name#

DELETE /v1/caller-registration/registrations/{registration_id} removes the caller name from a number in your Telnyx account. Returns 202 with the registration (status pending, then off). It returns 400 for Twilio registrations (remove those in Twilio's Trust Hub) and for a ThunderPhone number's caller name (turn that off with Save the caller name).

Related#

• Caller ID and spam registration
• Phone numbers
• VoIP connections