--- title: "Create the next verification channel attempt" method: POST path: "/v1/verify/verifications/next-channel" tags: ["verify-verifications"] --- # Create the next verification channel attempt `POST /v1/verify/verifications/next-channel` ## Request - Base URL: `https://us1.platform.bird.com` - URL: `https://us1.platform.bird.com/v1/verify/verifications/next-channel` - Auth: one of: - HTTP bearer - API key in cookie `bird_session` Advances an in-progress verification to the next channel in its plan and sends a fresh passcode there. Identify the verification by the same `to` recipient used to create it; no verification ID is required. The send bypasses the resend cooldown and does not draw on the recipient's hourly send cap; what bounds it is the channel plan, since each call advances by at most one channel. Passcodes sent earlier remain valid. The response sets `last_channel` to the most recent completed send. Concurrent requests each advance the plan by at most one channel and return committed state. A recipient with no in-progress verification returns `404 E13000`, whether none was ever created or the most recent one is already resolved. A recipient who has already verified is in that set, so a `404` here is not evidence they still need verifying, and creating another verification would send a passcode they no longer need. A plan with no further channel returns `422 NoNextChannel`; create the verification again to resend on the current channel. If every remaining channel fails, the operation returns `422 NoAvailableChannel`. Requests that exceed the send rate limit return `429`. ## Headers - `Idempotency-Key` string - `X-Workspace-Id` string - `X-Organization-Id` string ## Request body - VerificationNextChannelRequest - `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`). ## Response `200` Verification state after the advance. `last_channel` identifies the most recent completed send. - Verification - `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 ## Other responses - `400`: Bad request - `401`: Authentication required - `402`: Insufficient balance - `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/6dfce1179799?raw)