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.
Verzoekpayload
to
object
verplicht
The recipient to verify. Provide an email_address, a phone_number, or both; at least one is required.
Onderliggende parameters tonen
to.email_address
string
The recipient's email address.
to.phone_number
string
The recipient's phone number in E.164 format.
code
string
verplicht
The passcode the recipient received.
Response Payload
success
boolean
verplicht
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
verplicht
Onderliggende attributen tonen
verification.id
string
verplicht
verification.status
string
verplicht
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
verplicht
The recipient to verify. Provide an email_address, a phone_number, or both; at least one is required.
Onderliggende attributen tonen
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
verplicht
The ordered channels this verification uses to deliver the passcode. An email recipient is verified over email; a phone recipient is verified over SMS.
Onderliggende attributen tonen
verification.channels.channel
string
verplicht
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
verplicht
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
verplicht
verification.updated_at
string
verplicht
attempts_remaining
nullable integer
The number of check attempts left, or null once the verification is complete.