# Verify number ownership

## POST

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

TypeScript

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

Python

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

Go

```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

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

CLI

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

cURL

```bash
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

```json
{
  "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](/content/docs/guides/voice/caller-ids/index.html).

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

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

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
