---
title: "Create a verification passcode check"
method: POST
path: "/v1/verify/verifications/check"
tags: ["verify-verifications"]
---

# Create a verification passcode check

`POST /v1/verify/verifications/check`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/verify/verifications/check`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

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.

## Headers

- `Idempotency-Key` string
- `X-Workspace-Id` string
- `X-Organization-Id` string

## Request body

- VerificationCheckRequest
  - `to` VerificationTo, required: 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.
    - `email` string, email: The recipient's email address. Case does not matter; the address is lowercased before use.
    - `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, required: 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.

## Response `200`

The check outcome and the verification's current state.

- VerificationCheckResult
  - `success` boolean, required: 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` string, nullable: 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.
  - `verification` Verification, required
    - `id` string, required
    - `status` 'pending' | 'verified' | 'failed' | 'expired' | 'canceled' | 'blocked', required: The verification's current state: - `pending`: Awaiting a correct passcode. - `verified`: A correct passcode was submitted. - `failed`: The verification cannot be completed. Either too many incorrect passcodes were submitted, or no planned channel could deliver one. Read `reason` to tell those apart. - `expired`: The validity window elapsed before a correct passcode. - `canceled`: The verification was canceled before completion. - `blocked`: A fraud or abuse control stopped the verification.
    - `reason` string: Why a verification session reached its final state without succeeding: `attempts_exhausted` (too many incorrect passcodes), `ttl_elapsed` (the time window elapsed before a correct passcode), or `undeliverable` (no planned channel could deliver a passcode, so the recipient never had one to submit). Open enum: new reasons may be added over time, so treat any unrecognized value as a future reason rather than an error.
    - `to` VerificationTo, required: 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.
      - `email` string, email: The recipient's email address. Case does not matter; the address is lowercased before use.
      - `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`).
    - `channels` VerificationChannelEntry[], required: 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 the phone channels enabled for its destination country, in the order that country's configuration sets.
      - `channel` string, required: 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.
    - `last_channel` string, nullable: 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.
    - `metadata` object: The key/value pairs attached when the verification was created.
    - `expires_at` string, date-time, required: When the verification expires if no correct passcode is submitted first. After this time its status reports `expired`.
    - `verified_at` string, date-time, nullable: When the verification was completed, or `null` if it is not yet verified.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `attempts_remaining` integer, nullable: The number of check attempts left while the verification is still pending, or `null` once it has reached a final state.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/3e2a50466454?raw)