verify-verifications

Create a verification passcode check

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.

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

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Request body

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

Example request

{
  "to": {
    "phone_number": "+15551234567"
  },
  "code": "123456"
}

Response

The check outcome and the verification's current state.

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

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

attempts_remaininginteger nullable

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

Example response

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

Changes

No recorded changes to this operation across all 2 revisions of this API.