---
title: "Caller Registration"
description: "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](/guides/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](/api-reference/voip-connections).

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

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/caller-registration` | Caller name setting and every number's registrations |
| `PUT` | `/v1/caller-registration/caller-name` | Save the caller name |
| `POST` | `/v1/caller-registration/register` | Register numbers in your own carrier account |
| `GET` | `/v1/caller-registration/twilio-business-profile` | Check a Twilio account's Primary Business Profile |
| `POST` | `/v1/caller-registration/refresh` | Check registrations under review now |
| `DELETE` | `/v1/caller-registration/registrations/{registration_id}` | Turn off a Telnyx caller name |

## Registration object

```json
{
  "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"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Registration id |
| `phone_number_id` | integer | The [phone number](/api-reference/phone-numbers) it belongs to |
| `kind` | string | `cnam` (caller name), `shaken_stir` (verified caller ID) or `voice_integrity` (spam-filter registration) |
| `provider` | string | `telnyx` or `twilio`: the account the registration lives in |
| `status` | string | `pending` (being sent), `submitted`, `in_review`, `approved`, `rejected`, `failed` or `off` |
| `display_name` | string | `cnam` only: the name shown on calls |
| `status_detail` | string | Plain-language detail: a rejection reason, what failed, or what happens next |
| `trust_product_sid` | string | Twilio only: the Trust Hub registration the number joined |
| `submitted_at`, `checked_at`, `updated_at` | timestamp or null | ISO 8601 UTC. `checked_at` is the last time ThunderPhone read the status from the carrier |

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

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/caller-registration \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json
{
  "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"
}
```

| Field | Description |
|-------|-------------|
| `caller_name.caller_name` | The saved name; blank means "use the organization's name" |
| `caller_name.default_caller_name` | The organization name cut to a valid caller name; blank when the organization still has its generated name (such as "Jane's Team") |
| `caller_name.effective_caller_name` | What ThunderPhone numbers show; blank when turned off or when there is no usable name |
| `numbers[].carrier` | `thunderphone`, `twilio`, `telnyx`, `signalwire`, `vonage`, `manual` or `other` |
| `numbers[].eligible_kinds` | What you can register on this number yourself. Empty for ThunderPhone numbers (handled automatically) and for carriers ThunderPhone can't register with; never `cnam` for toll-free or non-US numbers |
| `numbers[].registrations` | One [registration object](#registration-object) or `null` per kind |

---

## Save the caller name

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

<CodeGroup>
```bash cURL
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}'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `caller_name` | string | no | 1 to 15 letters, numbers and spaces, starting with a letter. `""` uses the organization's name |
| `enabled` | boolean | no | `false` stops showing a caller name on ThunderPhone numbers |

Returns `200 OK` with the same body as [Get registrations](#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.

<CodeGroup>
```bash cURL
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
    }
  }'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `kind` | string | yes | `cnam`, `shaken_stir` or `voice_integrity`. Telnyx numbers take `cnam` only |
| `phone_number_ids` | integer[] | yes | 1 to 200 of your numbers on a Twilio or Telnyx connection |
| `display_name` | string | no | `cnam` only. Defaults to the organization's caller name |
| `voice_integrity` | object | for `voice_integrity` | `use_case` (one of `voice_integrity_use_cases`), `employee_count` and `daily_call_volume` (whole numbers, 1 or more) |

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.

| Status | When |
|--------|------|
| `400` | A ThunderPhone number (its caller name is automatic), a kind the number's carrier doesn't support (caller names are for US local numbers only, not toll-free), an invalid name, missing Voice Integrity answers, or no contact email on the requesting user (Twilio needs one) |
| `404` | A number that isn't in your organization |
| `409` | The Twilio account has no approved Primary Business Profile: `code` is `business_profile_required`, with `console_url` and `business_profile_status`. A `409` with no `code` means the Twilio credentials are incomplete or Twilio refused the check; the reason is in `detail` |
| `503` | Twilio couldn't be reached to check the Business Profile; try again |

---

## Check a Twilio Business Profile

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

```json
{
  "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](#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](#save-the-caller-name)).

## Related

- [Caller ID and spam registration](/guides/caller-id-and-spam-registration)
- [Phone numbers](/api-reference/phone-numbers)
- [VoIP connections](/api-reference/voip-connections)