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.
Request Payload
to
object
required
The recipient to verify. Provide an email_address, a phone_number, or both; at least one is required.
Show child parameters
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.
Show child parameters
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.
Response Payload
id
string
required
status
string
required
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
required
The recipient to verify. Provide an email_address, a phone_number, or both; at least one is required.
Show child attributes
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
required
The ordered channels this verification uses to deliver the passcode. An email recipient is verified over email; a phone recipient is verified over SMS.
Show child attributes
channels.channel
string
required
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
required
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
required
updated_at
string
required