Sending verifications

Verifying a user is two calls: POST /v1/verify/verifications sends a passcode to an email address or phone number, and POST /v1/verify/verifications/check submits what the user typed and tells you whether it matched. Bird generates the code, delivers it, stores only a hash, and enforces expiry and attempt limits; your app never sees or stores the code itself. Full request and response schemas live in the API reference for creating a verification and checking a code.

Send a code

The smallest valid request is a to recipient:

const verification = await bird.verify.verifications.create({
  to: { phone_number: "+15551234567" },
});
console.log(verification.id, verification.status);

verification = client.verify.verifications.create(to={"phone_number": "+15551234567"})
print(verification.id, verification.status)

verification, err := client.Verify.Verifications.Create(context.Background(), bird.VerifyVerificationsCreateParams{
	To: bird.VerificationTo{PhoneNumber: bird.String("+15551234567")},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(verification.Id, *verification.Status)

$verification = $bird->verify->verifications->create(
    (new VerificationCreateRequest())->setTo((new VerificationTo())->setPhoneNumber('+15551234567')),
);
echo $verification->getId(), ' ', $verification->getStatus();

bird verify verifications create --body-file - <<'JSON'
{
  "metadata": {
    "correlation_id": "signup-7f3a"
  },
  "to": {
    "phone_number": "+15551234567"
  }
}
JSON

curl -X POST https://us1.platform.bird.com/v1/verify/verifications \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": { "phone_number": "+15551234567" }
  }'

Use your regional host (https://us1.platform.bird.com or https://eu1.platform.bird.com) with a matching bk_{region}_... key.

Recipient

to names who you're verifying: an email, a phone_number in E.164 format, or both. The recipient determines the delivery channels. An email address resolves to the email channel. A phone number resolves to the phone channels available in its destination country, in the order your country configuration sets there: in most countries WhatsApp first with SMS as fallback, in some SMS first, with Telegram after both. Supplying both addresses gives Bird more than one way to reach the user: if a send on one channel fails, delivery advances to the next channel in the plan.

Options

options overrides settings for this request only:

code_length: passcode length for this verification, 4 to 8 digits, overriding the default.
channels: reorder or narrow the delivery channels for this request. List channel names (sms, whatsapp, email, telegram) in the order to try them; a channel you omit is not used, and a name not in the recipient's resolved plan is ignored. You can't add a channel this way, only trim or reorder what the recipient and country configuration already allow, and a list that leaves no usable channel fails the request with 422.

Metadata

metadata is a free-form object returned on every read; use it to carry your own user ID or session reference. Sender choices and the verification settings don't ride on the request: they come from your workspace's configuration, managed in the dashboard (see Verification settings).

The response

Code example

{
  "id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
  "status": "pending",
  "reason": null,
  "to": { "phone_number": "+15551234567" },
  "channels": [{ "channel": "whatsapp" }, { "channel": "sms" }],
  "last_channel": "whatsapp",
  "expires_at": "2026-07-23T14:55:58Z",
  "verified_at": null,
  "created_at": "2026-07-23T14:45:58Z",
  "updated_at": "2026-07-23T14:45:58Z"
}

channels is the ordered delivery plan this verification resolved to (a phone recipient lists its phone channels in attempt order), and last_channel is where the most recent code went. expires_at is when the verification lapses if no correct code arrives; resends don't extend it.

Check the code

Submit whatever the user typed to POST /v1/verify/verifications/check, keyed by the same recipient; no verification ID needed. Supply exactly the to set you created the verification with: one created with both addresses isn't found by either address alone.

const result = await bird.verify.verifications.check({
  to: { phone_number: "+15551234567" },
  code: "123456",
});
console.log(result.success);

result = client.verify.verifications.check(
    to={"phone_number": "+15551234567"}, code="123456"
)
print(result.success)

result, err := client.Verify.Verifications.Check(context.Background(), bird.VerifyVerificationsCheckParams{
	To:   bird.VerificationTo{PhoneNumber: bird.String("+15551234567")},
	Code: "123456",
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(*result.Success)

$result = $bird->verify->verifications->check(
    (new VerificationCheckRequest())
        ->setTo((new VerificationTo())->setPhoneNumber('+15551234567'))
        ->setCode('123456'),
);
echo $result->getSuccess() ? 'verified' : 'failed';

bird verify verifications check 123456 --phone-number +15551234567

curl -X POST https://us1.platform.bird.com/v1/verify/verifications/check \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": { "phone_number": "+15551234567" },
    "code": "123456"
  }'

The response says whether it matched:

Code example

{
  "success": false,
  "reason": "incorrect_code",
  "attempts_remaining": 4,
  "verification": {
    "id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
    "status": "pending",
    "reason": null,
    "to": { "phone_number": "+15551234567" },
    "channels": [{ "channel": "whatsapp" }, { "channel": "sms" }],
    "last_channel": "whatsapp",
    "expires_at": "2026-07-23T14:55:58Z",
    "verified_at": null,
    "created_at": "2026-07-23T14:45:58Z",
    "updated_at": "2026-07-23T14:46:38Z"
  }
}

Two behaviors here trip up first integrations:

A wrong code is a 200, not an error. success: false with a reason (incorrect_code, expired, attempts_exhausted) is a normal answer; attempts_remaining tells you how many tries are left. Reserve your error handling for actual request failures.
A verification is checkable exactly once it resolves. Once a verification reaches a final state, verified or otherwise, further checks return 404. Treat the first definitive answer as the answer; don't re-check to "confirm".

If the user asked for a new code, call the create endpoint again with the same recipient: the in-progress verification is reused rather than replaced. Once the resend cooldown has elapsed (60 seconds by default) a fresh code goes out; within the cooldown the call returns the live verification without sending again. Every code sent for the live verification stays valid until it resolves or expires, so the user can enter whichever one arrived.

Send the code on another channel

When the user reports that no code arrived at all, POST /v1/verify/verifications/next-channel advances the verification to the next channel in its plan and sends a fresh code there. This is the endpoint behind an "I didn't receive my code" button: your app decides to move channels rather than wait for a delivery-status signal.

Key it by the same recipient you created the verification with, as with a check:

const verification = await bird.verify.verifications.nextChannel({
  to: { phone_number: "+15551234567" },
});
console.log(verification.last_channel);

verification = client.verify.verifications.next_channel(
    to={"phone_number": "+15551234567"}
)
print(verification.last_channel)

verification, err := client.Verify.Verifications.NextChannel(context.Background(), bird.VerifyVerificationsNextChannelParams{
	To: bird.VerificationTo{PhoneNumber: bird.String("+15551234567")},
})
if err != nil {
	log.Fatal(err)
}
if verification.LastChannel != nil {
	fmt.Println(*verification.LastChannel)
}

$verification = $bird->verify->verifications->nextChannel(
    (new VerificationNextChannelRequest())->setTo((new VerificationTo())->setPhoneNumber('+15551234567')),
);
echo $verification->getLastChannel();

bird verify verifications next-channel --phone-number +15551234567

curl -X POST "https://{region}.platform.bird.com/v1/verify/verifications/next-channel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {
      "phone_number": "+15551234567"
    }
  }'

The response is the verification, with last_channel naming the channel the new code went to. Every code already sent stays valid, so a message that arrives late can still be checked.

Two things separate this from a resend:

The resend cooldown does not apply. A deliberate channel switch is a different act from asking for the same channel again, so the send goes out immediately.
The channel moves forward, not the verification. The expiry, the attempt budget, and the verification ID all stay as they were; only the delivery channel advances.

Reach for a resend when the user wants another try on a channel that works, and for this endpoint when the channel itself looks like the problem. A phone number whose plan is WhatsApp then SMS advances to SMS; a recipient with only one usable channel has nowhere to go.

Four responses need handling rather than a plain retry:

Status	What happened	What to do
404	No verification is in progress for that recipient	Create one
422 NoNextChannel	The plan has no further channel to advance to	Resend on the current channel by calling create again
422 NoAvailableChannel	Every remaining channel failed to send	Surface the failure to the user; the verification cannot be delivered
429	Sends for the account are being requested too quickly	Back off for the period in the Retry-After header

Each code this endpoint sends is billed like any other Verify send; see Cost and billing.

Statuses

A verification is pending until it resolves into a final state, with reason saying why:

Status	Meaning	Reason
verified	A correct code arrived in time	none
failed	Too many incorrect attempts	attempts_exhausted
expired	The window elapsed before a correct code	ttl_elapsed

The status enum also reserves canceled and blocked for future use: no verification resolves to them today, but handle them as terminal if they appear. reason is an open enum; treat an unrecognized value as a future reason, not an error.

Track verifications in the dashboard

The Verifications page lists every verification the workspace created, filterable by status. Each row opens a detail view with the recipient, the resolved channel plan, the last channel used, expiry and verification times, and the metadata you attached: everything except the code itself, which is never stored or shown.

The Verifications page listing verifications with status, recipient, channel, and creation time columns

Verification settings

The Configure page sets the workspace's verification cycle. Each field shows the effective value: your override where you've set one, otherwise Bird's platform default.

Duration: how long a code remains valid. Default 10 minutes; 1 minute to 999 minutes.
Maximum Retries: how many check attempts before the verification fails with attempts_exhausted. Default 5; 1 to 10.
Retry Delay: the cooldown before a new code can be sent to the same recipient. Default 60 seconds; 0 to 3600.

The Configure page's General tab with Duration, Maximum Retries, and Retry Delay fields

Code length isn't a field on this page: codes default to 6 digits, numeric, and options.code_length sets 4 to 8 digits per request.

Abuse guardrails

Independent of your settings, Verify enforces platform caps to keep OTP traffic from being weaponized, whether against your wallet (SMS pumping) or against a victim's inbox:

5 sends per recipient per rolling hour, counted per address, across starting and resending a verification.
10 checks per recipient per minute, throttling brute-force code guessing on top of the attempt limit.

Moving to another channel is bounded by the channel plan rather than by that hourly cap: each call advances strictly forward, so one verification yields at most one send per remaining channel however often you call it.

Hitting a cap returns 429; back off and retry after the period in the Retry-After header. Your account's overall request limits are separate and plan-scaled; see Rate limits.

Retrying safely

All three endpoints accept the Idempotency-Key header: send it with a unique value per logical request, and a retry after a timeout or dropped connection replays the original response instead of processing the request again, so a retried create or channel advance doesn't send a second code and a retried check doesn't consume another attempt. Replayed responses carry an Idempotency-Replay header. See idempotency for key format and retention.

Cost and billing

A verification is billed per code sent, not per verification: each delivery is charged to your wallet at that channel's rate for the destination, so a resend, or a fallback that moves delivery to a second channel, adds one charge per send. Sends on free routes cost nothing, a send rejected before it was billed is never charged, and checks are free. Payment methods & wallet covers balance and top-ups.

Next steps

Page	What it covers
Senders & branding	What the code messages look like and how to send from your own domain
Country configuration	Per-country channel order, enablement, and sender overrides
Events	The verification lifecycle and delivery events, and their webhook payloads
Idempotency	Safe retries with the Idempotency-Key header
API reference: create a verification	Send-endpoint schema and error details
API reference: check a code	Check-endpoint schema and error details
API reference: advance to the next channel	Next-channel schema and error details