---
title: "Create a verified number"
method: POST
path: "/v1/voice/verified-numbers"
tags: ["voice-verified-numbers"]
---

# Create a verified number

`POST /v1/voice/verified-numbers`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/voice/verified-numbers`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

Registers a phone number as an outbound caller ID for the workspace and starts
verification. The API places a verification call to the number that reads out
a code; submit that code to the verify endpoint to prove ownership. The
verified number is returned in the "pending" state until verification completes.

Idempotency is optional. For retry protection, supply an `Idempotency-Key`
on the first attempt and reuse it with the same request. A retained successful
response is replayed for three hours. Without a key, retries are processed
normally and can return `409` if the number is already registered. If a
response is lost, list the workspace's verified numbers to check the registration
before trying again.

A `412` means required identity verification is incomplete or organization
eligibility prevents registration. Follow the error's recovery guidance:
complete missing verification, or contact support about an eligibility review
or denial. An eligibility assessment still in progress returns `503`; retry later.

## Headers

- `Idempotency-Key` string
- `X-Workspace-Id` string
- `X-Organization-Id` string

## Request body

- VoiceVerifiedNumberCreate
  - `phone_number` string, required: The phone number to register as an outbound caller ID, in E.164 format (a leading `+` followed by the country code and national number). Must be unique within the workspace. Creating the verified number starts verification: a verification call is placed to this number.
  - `name` string: Your label for this verified number, to tell several registered numbers apart. Omit it to register the number without one and add it later. It is yours to choose and appears nowhere on a call, so it never affects what the person you are calling sees.

## Response `201`

Verified number registered and pending verification.

- VoiceVerifiedNumber
  - `id` string, required
  - `workspace_id` string, required
  - `phone_number` string, required: The phone number in E.164 format registered as an outbound caller ID.
  - `name` string, nullable, required: Your label for this verified number, to tell several registered numbers apart. `null` when the verified number has no label. It is yours to choose and appears nowhere on a call, so changing it never affects what the person you are calling sees. Set it with the verified number update operation.
  - `status` string, required: Verification state of the verified number. - `pending`: the number is registered but ownership has not yet been proven. - `verified`: the workspace proved ownership of the number. Check the resource's activation or direction fields for outbound availability. - `failed`: terminal because the verification challenge expired or the attempt limit was exhausted. Delete the verified number and register it again to retry. Open enum: additional states may be added over time, so treat an unrecognized value as a future state rather than an error.
  - `outbound_enabled` boolean, required: Whether outbound caller ID activation has completed. A verified number can remain inactive until activation requirements are met. Outbound calls remain subject to routing and number ownership requirements.
  - `verified_at` string, date-time, nullable, required: When the verified number was verified. `null` when its status is `pending` or `failed`.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `409`: Resource conflict
- `412`: Precondition failed
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)