Sign inGet Started
Commencer
Guides
Référence API
SDK
CLI
Base de connaissances
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);
Réponse200
{
  "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.

Corps de la requête

to
object
obligatoire

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.

Afficher les paramètres enfants
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
obligatoire

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.

Contenu de la réponse

success
boolean
obligatoire

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
obligatoire
Afficher les attributs enfants
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.

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.

Essayez la pratique et obtenez un guide d'implémentation