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 used to create it; you do not need to store a verification ID.

A wrong or expired passcode is a normal outcome, not an HTTP error: the response is 200 with success set to false and a reason such as incorrect_code or expired. success: true means the verification is complete. Each verification reports its final outcome exactly once and is no longer checkable afterwards.

An error status is returned only when the check cannot be evaluated: 404 when no verification matches the recipient or the matching one already reached its final state, 422 for an invalid recipient, and 429 when passcodes for a recipient are checked too quickly.

Cuerpo de la solicitud

object

obligatorio

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.

Mostrar parámetros secundarios

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).

code

string

obligatorio

The passcode the recipient received. Passcodes are numeric; submit the digits exactly as delivered. An incorrect value is a normal 200 outcome with success: false, not an error.

Carga de respuesta

success

boolean

obligatorio

Whether the submitted passcode verified this verification. true means the passcode was correct and the verification is now complete; false means it did not verify, and reason says why. 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.

Possible values (may grow over time): incorrect_code, expired, attempts_exhausted

verification

object

obligatorio

Mostrar atributos secundarios

verification.id

string

obligatorio

verification.status

string

obligatorio

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

verification.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.

verification.to

object

obligatorio

Mostrar atributos secundarios

verification.to.email_address

string

The recipient's email address. Case does not matter; the address is lowercased before use.

verification.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).

verification.channels

array of object

obligatorio

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.

Mostrar atributos secundarios

verification.channels.channel

string

obligatorio

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

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.

Possible values (may grow over time): email, sms, whatsapp

verification.metadata

object

The key/value pairs attached when the verification was created.

verification.expires_at

string

obligatorio

When the verification expires if no correct passcode is submitted first. After this time its status reports expired.

verification.verified_at

nullable string

When the verification was completed, or null if it is not yet verified.

verification.created_at

string

obligatorio

verification.updated_at

string

obligatorio

attempts_remaining

nullable integer

The number of check attempts left while the verification is still pending, or null once it has reached a final state.

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"
  }'