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 the recipient in to: an email address (verified over email), a phone number (verified over SMS), or both. With both, the passcode is sent over one channel at a time and delivery falls over to the other channel if the first fails; it is never sent to both at once.
Calling this again for the same recipient resumes the verification in progress rather than starting a second one: within the resend cooldown the request returns the current state without sending, and after it a fresh passcode is sent. Use the same call to send and to resend.
The 200 response is the verification's current state; the passcode itself is never returned. Submit the passcode the recipient enters with POST /v1/verify/verifications/check before the verification's expires_at. An invalid recipient returns 422, and requesting passcodes for the same recipient too often returns 429.
Anfrage-Nutzlast
to
object
erforderlich
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.
Untergeordnete Parameter anzeigen
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).
options
object
Per-request overrides applied to this verification only.
Untergeordnete Parameter anzeigen
options.code_length
integer
Passcode length for this verification. Omit to use 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. A list that leaves no usable channel fails the request with 422. 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.
Antwort-Payload
id
string
erforderlich
status
string
erforderlich
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
erforderlich
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.
Untergeordnete Attribute anzeigen
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
erforderlich
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 SMS.
Untergeordnete Attribute anzeigen
channels.channel
string
erforderlich
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
erforderlich
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
erforderlich
updated_at
string
erforderlich