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.
Treść żądania
to
object
wymagane
The recipient to verify. Provide an email_address, a phone_number, or both; at least one is required.
Pokaż parametry podrzędne
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.
Pokaż parametry podrzędne
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.
Treść odpowiedzi
id
string
wymagane
status
string
wymagane
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
wymagane
The recipient to verify. Provide an email_address, a phone_number, or both; at least one is required.
Pokaż atrybuty podrzędne
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
wymagane
The ordered channels this verification uses to deliver the passcode. An email recipient is verified over email; a phone recipient is verified over SMS.
Pokaż atrybuty podrzędne
channels.channel
string
wymagane
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
wymagane
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
wymagane
updated_at
string
wymagane