Create a verification
POST
/v1/verify/verifications
curl -X POST "https://us1.platform.bird.com/v1/verify/verifications" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": {
"phone_number": "+15551234567"
},
"metadata": {
"correlation_id": "signup-7f3a"
}
}'Creates a verification for a recipient and sends them a one-time passcode. Provide a recipient in to — an email address (verified over email), a phone number (verified over SMS), or both. If a verification is already in progress for the same recipient, that one is reused and its passcode is re-sent once the resend cooldown has elapsed, rather than starting a second verification. The response includes the verification's current state; the passcode itself is never returned. Submit the passcode the recipient enters with the check endpoint.
Payload Permintaan
to
object
wajib
The recipient to verify. Provide an email_address, a phone_number, or both; at least one is required.
Tampilkan parameter turunan
to.email_address
string
The recipient's email address.
to.phone_number
string
The recipient's phone number in E.164 format.
options
object
Per-request overrides applied to this verification only.
Tampilkan parameter turunan
options.code_length
integer
Passcode length for this verification, overriding the configured length.
options.channels
array of string
Reorder or narrow the delivery channels for this request. List channel names in the order to try them; a channel you omit is not used for this request, and a channel not already enabled for the recipient is ignored. Omit the field to use the configured order.
metadata
object
Optional key/value pairs to attach to the verification, for example a correlation id. Returned on the verification.
Payload Respons
id
string
wajib
status
string
wajib
The verification's current state: pending (awaiting a valid passcode), verified, failed (too many incorrect attempts), or expired (the time window elapsed before a correct passcode).
reason
nullable string
Why the verification reached its final state, or null while pending or once verified. Open enum — treat any unrecognized value as a future reason.
to
object
wajib
The recipient to verify. Provide an email_address, a phone_number, or both; at least one is required.
Tampilkan atribut turunan
to.email_address
string
The recipient's email address.
to.phone_number
string
The recipient's phone number in E.164 format.
channels
array of object
wajib
The ordered channels this verification uses to deliver the passcode. An email recipient is verified over email; a phone recipient is verified over SMS.
Tampilkan atribut turunan
channels.channel
string
wajib
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.
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.
metadata
object
The key/value pairs attached when the verification was created.
expires_at
string
wajib
When the verification expires if no correct passcode is submitted.
verified_at
nullable string
When the verification was completed, or null if it is not yet verified.
created_at
string
wajib
updated_at
string
wajib