Verify number ownership · API reference — Bird

Verify number ownership

POST

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

TypeScript

const verifiedNumber = await bird.voice.verifiedNumbers.verify("vvn_01krdgeqcxet5s7t44vh8rt9mg", { code: "123456" });
console.log(verifiedNumber.id, verifiedNumber.status);

Python

verified_number = client.voice.verified_numbers.verify("vvn_01krdgeqcxet5s7t44vh8rt9mg", code="123456")
print(verified_number.id, verified_number.status)

Go

verifiedNumber, err := client.Voice.VerifiedNumbers.Verify(context.Background(), "vvn_01krdgeqcxet5s7t44vh8rt9mg", bird.VoiceVerifiedNumbersVerifyParams{
    Code: bird.Ptr("123456"),
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(verifiedNumber.Id, verifiedNumber.Status)

PHP

$verifiedNumber = $bird->voice->verifiedNumbers->verify(
    'vvn_01krdgeqcxet5s7t44vh8rt9mg', (new VoiceVerifiedNumberVerifyRequest())->setCode('123456'),
);
echo $verifiedNumber->getId(), ' ', $verifiedNumber->getStatus(), "\n";

CLI

bird voice verified-numbers verify <verified-number-id> --code 123456

cURL

curl -X POST "https://us1.platform.bird.com/v1/voice/verified-numbers/{verified_number_id}/verify" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "123456"
  }'

Response200

{
  "id": "vvn_01krdgeqcxet5s7t44vh8rt9mg",
  "workspace_id": "ws_01j8z5k2qvfpx9m3n7r4t6y8bc",
  "phone_number": "+14155551234",
  "name": "Support line",
  "status": "verified",
  "verified_at": "2026-09-23T10:15:00Z",
  "created_at": "2026-09-23T10:00:00Z",
  "updated_at": "2026-09-23T10:15:00Z"
}

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.

Parameters

verified_number_id string

ID of the verified number registration whose ownership challenge to complete.

Request Payload

code
string

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.

Response Payload

id
string

required

Unique identifier for this verified number.

workspace_id
string

required

phone_number
string

required

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

name
nullable string

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.

Open enum: additional states may be added over time, so treat an unrecognized value as a future state rather than an error.

Possible values (may grow over time): pending, verified, failed

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
nullable string

required

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

created_at
string

required

updated_at
string

required