Check a verification passcode
POST
/v1/verify/verifications/check
curl -X POST "https://us1.platform.bird.com/v1/verify/verifications/check" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": {
"phone_number": "+15551234567"
},
"code": "123456"
}'Checks a passcode for a recipient and returns the outcome together with the verification's current state. Identify the verification by the same to recipient used to create it — you do not need to store a verification id. A wrong, expired, or already-used passcode is reported in the response body, with success set to false and a reason such as incorrect_code or expired, rather than as an HTTP error; only a missing verification, malformed input, or rate limiting return an error status.
Payload della richiesta
to
object
obbligatorio
The recipient to verify. Provide an email_address, a phone_number, or both; at least one is required.
Mostra parametri secondari
to.email_address
string
The recipient's email address.
to.phone_number
string
The recipient's phone number in E.164 format.
code
string
obbligatorio
The passcode the recipient received.
Payload di risposta
success
boolean
obbligatorio
Whether the submitted passcode verified this verification. true means the passcode was correct and the verification is now complete; false means it was not verified — see reason. A verification that has already reached a final state is no longer checkable and returns 404.
reason
nullable string
Why the check did not succeed, or null when success is true. incorrect_code means the passcode was wrong and attempts remain; expired means the time window elapsed; attempts_exhausted means too many incorrect attempts. Open enum — treat any unrecognized value as a future reason.
verification
object
obbligatorio
Mostra attributi secondari
verification.id
string
obbligatorio
verification.status
string
obbligatorio
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).
verification.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.
verification.to
object
obbligatorio
The recipient to verify. Provide an email_address, a phone_number, or both; at least one is required.
Mostra attributi secondari
verification.to.email_address
string
The recipient's email address.
verification.to.phone_number
string
The recipient's phone number in E.164 format.
verification.channels
array of object
obbligatorio
The ordered channels this verification uses to deliver the passcode. An email recipient is verified over email; a phone recipient is verified over SMS.
Mostra attributi secondari
verification.channels.channel
string
obbligatorio
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.
verification.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.
verification.metadata
object
The key/value pairs attached when the verification was created.
verification.expires_at
string
obbligatorio
When the verification expires if no correct passcode is submitted.
verification.verified_at
nullable string
When the verification was completed, or null if it is not yet verified.
verification.created_at
string
obbligatorio
verification.updated_at
string
obbligatorio
attempts_remaining
nullable integer
The number of check attempts left, or null once the verification is complete.