---
title: "Caller IDs"
description: "Register the numbers your workspace presents on outbound calls and prove you own them with a verification call, on the Numbers page in the dashboard."
canonical: "https://bird.com/docs/guides/voice/caller-ids"
---

# Caller IDs

A caller ID is a number your workspace can present on an outbound call. Bird checks the SIP `From` header on every call against the Bird numbers this workspace can present and its verified external numbers. Calls that present an ineligible number are refused.

Manage caller IDs under **Voice** > [**Numbers**](https://bird.com/dashboard/w/voice/numbers), which lists every number your workspace can use for voice. A number you bought from us and a number you verified appear in the same list, one row per number. A number that is both appears once. A number you bought from us is ready to present as soon as you hold it, with no verification call: holding it is the proof. The procedure below is for a number you own somewhere else.

Each row shows the name, the number and its country, its **Provider**, the directions it carries, and what it is used for. A number awaiting its code shows **Verifying**; one whose code expired or attempts ran out shows **Failed**. Each page contains up to 25 numbers. Select a row to open that number's own page.

## Register a number

1. Select **Add number** > **Verify a number you own**.
2. Enter the number in E.164 format: a leading `+`, country code, and national number. A number can be registered once in your workspace.
3. Save it. A verification call is placed to the number straight away.
4. Answer the call and listen for the six-digit code.
5. Enter the code in the dashboard. You have five attempts, and an accepted code changes the status to **Verified**.

Caller-ID verification does not charge your workspace for the verification call. Registration still requires Voice management permission and the account's approval to register verified numbers. Name the number afterwards on its own page. See [Name a number](#name-a-number).

After verification, check the country you intend to call under **Voice** > [**Destinations**](https://bird.com/dashboard/w/voice/destinations). Verification attempts to enable the verified number's country, but unavailable countries or a failed settings update can leave it disabled. A verified caller ID and an enabled destination are separate requirements.

## Register and verify through the API

[Register a number](/docs/api/reference/create-voice-verified-number) to start its verification call, then [submit the code](/docs/api/reference/verify-voice-verified-number) against the ID the registration returns. [List your caller IDs](/docs/api/reference/list-voice-verified-numbers) to find a number registered in the dashboard. You can also [rename](/docs/api/reference/update-voice-verified-number) or [delete](/docs/api/reference/delete-voice-verified-number) a caller ID. Reads require `voice_management:read`; registration, verification, renaming and deletion require `voice_management:write`. The API reference includes SDK, Bird command-line, and MCP examples.

If the original verification call could not be started, submitting the code can start another call to the registered number. Your organization must still meet the registration requirements. If the code expires or attempts are exhausted, delete the caller ID and register the number again, which places a new verification call, then submit the new code against the ID that registration returns. If the code is accepted but activation returns `412` or `503`, ownership is still proven and the caller ID reads `verified` with `outbound_enabled: false`. A `412` means identity verification is incomplete, which you finish in the dashboard, or an eligibility review or denial, which needs support. A `503` means the eligibility assessment is pending or unavailable, so retry later. Once resolved, submit an empty verification request to the same ID; do not delete and re-register it.

After verification, [check your Voice destinations](/docs/api/reference/list-voice-destinations) and [enable the number's country](/docs/api/reference/update-voice-destinations) when supported and needed. Verification attempts to enable it, but a successful caller-ID verification can leave the destination disabled and outbound calls to that country blocked.

## One verification at a time

Registration can return `E21036` when the verification provider already has a challenge for that number belonging to another workspace or purpose. Wait for that verification to finish or expire, then register the number again. A proof obtained for another workspace does not verify the number in yours.

The same refusal covers a number that is busy for another reason: a login code or a Trust Hub verification already in flight to it. If no other workspace is verifying the number, that is usually why, and the wait is the same.

A verification that has already finished elsewhere does not block you: the same number can be a verified caller ID in more than one workspace, and each one proves it separately.

## Statuses

| Status       | What it means                                                                                              |
| ------------ | ---------------------------------------------------------------------------------------------------------- |
| **Pending**  | Registered, awaiting the code. Use **Enter code** on the row to finish it                                  |
| **Verified** | The code was accepted. The number can be presented as the caller on outbound calls                         |
| **Failed**   | The code expired or attempts were used up. Use **Get a new code** on the row for a fresh verification call |

**Get a new code** registers the number again and calls it with a new code. If the first call never arrived and the number is still pending, remove the caller ID and add the number again.

If you read these values from your own tooling, match the ones you handle and treat any other as a status you do not handle rather than an error.

## CLI verification and delivery disclaimer

Bird performs CLI (Calling Line Identification) verification to confirm that an A-number is valid and authorised for use before outbound calls can be placed from the platform. This verification ensures the number is legitimate and under the customer's control.

However, verification does not guarantee end-to-end delivery of the CLI or connection of the call where the CLI is not a number procured through Bird. Downstream carriers and international operators apply their own national regulations and traffic policies, which are outside Bird's control. These may include:

- Anti-spoofing and caller ID authentication frameworks (e.g. STIR/SHAKEN in the US, Ofcom CLI guidelines in the UK)
- Requirements for the CLI to be a locally registered or in-country number
- Spam and fraud filtering applied by terminating operators
- Restrictions on specific traffic categories, such as gambling, financial promotions, debt collection, or political messaging
- Blocking of international calls presenting a domestic CLI ("origin-based" restrictions)
- Do-not-originate lists and regulator-mandated blocking

For these reasons, Bird can verify a CLI but cannot guarantee that (1) the CLI will be preserved and displayed to the called party, or (2) the call will connect via domestic trunks or international Tier 1 partners and operators. To maximise CLI delivery and call completion rates, we recommend using numbers procured through Bird, which are provisioned and routed in line with local regulatory requirements.

## Name a number

A name labels the number in the dashboard and in the dialer's **Call from** list. It is not sent with the call.

Select the number in the **Numbers** list to open its page, then set **Name** and save. Leave the field empty to show just the number. Naming works at any status and does not change the number or its verification.

## Verify a number you cannot answer

Someone must answer the verification call and hear its code. If the number normally reaches an unattended system, route it temporarily to a phone you can answer, then move it back. Contact support if the number cannot receive calls.

## Remove a caller ID

Use **Remove caller ID** on the number's row. Removing verification takes away that proof for new calls. A number held by your workspace through Bird can remain eligible through its allocation; an external number that loses its proof is refused with `caller_id_not_verified`. Calls already in progress continue, and existing [call records](/docs/guides/voice/call-log) do not change.

## Next steps

| Page                                              | What it covers                                                       |
| ------------------------------------------------- | -------------------------------------------------------------------- |
| [Placing calls](/docs/guides/voice/placing-calls) | What Bird expects on the `INVITE`, including the `From` header       |
| [SIP trunks](/docs/guides/voice/sip-trunks)       | Creating a trunk and controlling which addresses and keys may use it |

## Related resources

- [What is a voice API?](/explained/voice/what-is-a-voice-api) (answer)
- [Voice](/voice-api) (product)
- [Voice overview](/docs/guides/voice/overview) (docs)

[Get an implementation brief](/learn/workspace?topic=voice)