Advance a verification to its next channel
POST
/v1/verify/verifications/next-channel
bird verify verifications next-channel --body-file - <<'JSON'
{
"to": {
"phone_number": "+15551234567"
}
}
JSONcurl -X POST "https://us1.platform.bird.com/v1/verify/verifications/next-channel" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": {
"phone_number": "+15551234567"
}
}'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)
}Advances an in-progress verification to the next channel in its plan and sends a fresh passcode there, for a recipient who reports not receiving the code. Identify the verification by the same to used to create it; you do not need to store a verification ID.
The send bypasses the resend cooldown (a deliberate channel switch is a different act from a same-channel resend), and every passcode already sent stays valid, so a code that arrives late can still be checked. The response is the verification with last_channel set to the channel the new passcode went to. Concurrent requests for the same recipient are safe: each advances the plan at most one step. When two race, the request that completes the newer send is the authoritative one; the other returns the verification's committed state, whose last_channel still names the most recent send that completed. A later read of the verification always reflects the settled outcome.
An error status is returned when the verification cannot be advanced: 404 when no verification is in progress for the recipient, 422 with NoNextChannel when the plan has no further channel (fall back to a plain resend), 422 with NoAvailableChannel when every remaining channel failed to send, and 429 when sends for the account are requested too quickly.
Payload della richiesta
to
object
obbligatorio
The recipient to verify. Provide an email_address, a phone_number, or both; at least one is required. The addresses also identify the verification: a check must supply exactly the set used on the create call, so a verification created with both addresses is not found by either one alone.
Mostra parametri secondari
to.email_address
string
The recipient's email address. Case does not matter; the address is lowercased before use.
to.phone_number
string
The recipient's phone number in E.164 format, with the leading + and country code (for example +15551234567). A number in any other format is rejected as an invalid recipient (422).
Payload di risposta
id
string
obbligatorio
status
string
obbligatorio
The verification's current state: pending (the initial state, awaiting a correct passcode), verified (a correct passcode was submitted), failed (too many incorrect attempts), expired (the time window elapsed before a correct passcode), canceled (the verification was canceled before completing), or blocked (it was stopped by a fraud or abuse control).
Possible values: pending, verified, failed, expired, canceled, blocked
reason
nullable string
Why the verification reached its final state, or null while pending and once verified. See the enum for the values it can take.
to
object
obbligatorio
The recipient to verify. Provide an email_address, a phone_number, or both; at least one is required. The addresses also identify the verification: a check must supply exactly the set used on the create call, so a verification created with both addresses is not found by either one alone.
Mostra attributi secondari
to.email_address
string
The recipient's email address. Case does not matter; the address is lowercased before use.
to.phone_number
string
The recipient's phone number in E.164 format, with the leading + and country code (for example +15551234567). A number in any other format is rejected as an invalid recipient (422).
channels
array of object
obbligatorio
The channels this verification uses to deliver the passcode, in attempt order: the first entry is tried first and later entries are fallbacks. An email recipient is verified over email; a phone recipient is verified over the phone channels enabled for its destination country, in the order that country's configuration sets.
Mostra attributi secondari
channels.channel
string
obbligatorio
The channel a passcode is delivered over. Open enum — new channels may be added over time, so treat any unrecognized value as a future channel rather than an error.
Possible values (may grow over time): email, sms, whatsapp
last_channel
nullable string
The channel the most recent passcode was sent on, or null before the first send. Open enum; new channels may be added over time, so treat any unrecognized value as a future channel rather than an error.
Possible values (may grow over time): email, sms, whatsapp
metadata
object
The key/value pairs attached when the verification was created.
expires_at
string
obbligatorio
When the verification expires if no correct passcode is submitted first. After this time its status reports expired.
verified_at
nullable string
When the verification was completed, or null if it is not yet verified.
created_at
string
obbligatorio
updated_at
string
obbligatorio