Sign inGet Started
Inizia ora
Guide
Riferimento API
SDK
CLI
Knowledge Base
Changelog

Create a verification passcode check

POST
/v1/verify/verifications/check
const result = await bird.verify.verifications.check({
  to: { phone_number: "+15551234567" },
  code: "123456",
});
console.log(result.success);
Risposta200
{
  "success": false,
  "reason": "incorrect_code",
  "verification": {
    "id": "vrf_01krdgeqcxet5s7t44vh8rt9mg",
    "status": "pending",
    "reason": null,
    "to": {
      "email": "user@example.com"
    },
    "channels": [
      {
        "channel": "email"
      }
    ],
    "last_channel": "email",
    "expires_at": "2026-05-20T09:24:52Z",
    "created_at": "2026-05-20T09:14:52Z",
    "updated_at": "2026-05-20T09:14:52Z"
  },
  "attempts_remaining": 2
}

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 returns 200 OK with success: false and a reason such as incorrect_code or expired. success: true means the verification is complete. Each verification reports its final outcome once and cannot be checked again.

An error status is returned only when the check cannot be evaluated. A 404 E13000 means no active verification matched the recipient: either none exists for it, or the most recent one is already resolved as verified, expired, or out of attempts. One code covers all of those, so a 404 is not evidence the recipient failed to verify. Treat your own record of an earlier success: true as the outcome, and create a new verification only if the recipient still needs to verify. A 422 indicates an invalid recipient. A 429 means passcodes for a recipient are being checked too quickly.

Payload della richiesta

to
object
obbligatorio

The recipient to verify. Provide an email, 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.

Mostra parametri secondari
to.email
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
obbligatorio

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. It does not return an error.

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 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:

  • incorrect_code: The passcode was wrong and attempts remain.
  • expired: The validity window elapsed.
  • attempts_exhausted: Too many incorrect attempts were submitted.

null when success is true. Treat unrecognized values as reasons added later.

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

verification
object
obbligatorio
Mostra attributi secondari
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.

Risorse correlate

Continua con la documentazione, le guide e gli esempi per questo argomento.

Prova l'esercitazione e ottieni un brief di implementazione