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.
请求载荷
to
object
必填
The recipient to verify. Provide an email_address, a phone_number, or both; at least one is required.
显示子参数
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.
显示子参数
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.
响应载荷
id
string
必填
status
string
必填
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
必填
The recipient to verify. Provide an email_address, a phone_number, or both; at least one is required.
显示子属性
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
必填
The ordered channels this verification uses to deliver the passcode. An email recipient is verified over email; a phone recipient is verified over SMS.
显示子属性
channels.channel
string
必填
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
必填
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
必填
updated_at
string
必填