voice-verified-numbers

Verify number ownership

Completes the number ownership verification challenge that registering the number started. Submit the code delivered by the verification call. An incorrect code is rejected.

If the verification call could not be started previously, this request can retry it and place another call to the same number. Your organization must still meet the identity-verification requirements for registering verified numbers; otherwise the request returns 412. For an expired or exhausted challenge, delete the verified number and register it again, which places a new verification call, and submit the new code against the ID the registration returns.

A successful ownership check is retained even when organization eligibility prevents outbound activation. If the verified number's status is verified after a 412 or 503, complete the missing steps or contact support, then resubmit an empty object ({}). The saved proof is reused without checking a code again. While proof is still pending, include the code; an empty object is rejected. A 412 means missing verification steps or an eligibility decision requiring support; a 503 means assessment is pending or unavailable. outbound_enabled indicates whether activation has completed. Outbound calls remain subject to routing and number ownership requirements.

Activation attempts to enable the number's country as a Voice destination. An unavailable country or a failed settings update can leave it disabled. Check Voice > Destinations before calling; see the verified number guide.

post/v1/voice/verified-numbers/{verified_number_id}/verify

Request

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

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Request body

codestring

The 6-digit verification code read out by the verification call. Required until ownership is verified. Omit it when retrying activation of an already verified number.

Example request

{
  "code": "123456"
}

Response

Number ownership verified.

idstring required
workspace_idstring required
phone_numberstring required

The phone number in E.164 format registered as an outbound caller ID.

namestring 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.

statusstring 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_enabledboolean 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_atstring date-time nullable required

When the verified number was verified. null when its status is pending or failed.

created_atstring date-time required
updated_atstring date-time required

Example response

{
  "id": "vvn_01krdgeqcxet5s7t44vh8rt9mg",
  "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
  "phone_number": "+14155551234",
  "name": "Support line",
  "status": "pending",
  "created_at": "2026-05-20T09:14:52Z",
  "updated_at": "2026-05-25T16:42:01Z"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.