---
title: "Start a verification"
method: POST
path: "/verify/verifications"
tags: ["Verify"]
---

# Start a verification

`POST /verify/verifications`

Starts a verification by sending an SMS, voice, or email message to the recipient.
This verification is charged once the message is sent successfully.

## Request body

- VerificationSendRequest
  - `channel` 'sms' | 'voice' | 'email_code' | 'whatsapp', required — Supports several independent channels for verification: - `sms`: Sends an SMS message with a verification code. - `voice`: Makes a voice call with a verification code. - `email_code`: Sends an email with a verification code. - `whatsapp`: Sends a WhatsApp message with a verification code.
  - `to` string, required — The recipient's phone number or email address depending on `channel`. - Phone number: In [E.164](https://en.wikipedia.org/wiki/E.164) format. Applicable when `channel` is `sms` or `voice`. - Email address: For example, `tom@example.com`. Applicable when `channel` is `email_code`.
  - `code` string — Verification code to be sent. This field is optional. If not provided, we will automatically generate a code.
  - `senderId` string — [Sender ID](https://helpdocs.ycloud.com/help-center/integrations/channels/global-sms/sms-features/sender-id) to be used.
  - `signature` string — This parameter is only required for Chinese mainland SMS messages. You must specify an approved signature such as `Brand`. It will be added to the beginning of SMS body and wrapped with `【】`, e.g. `【Brand】Your verification code is 123456`.
  - `language` string — [ISO 639 Language Code](https://www.iso.org/iso-639-language-codes.html). If not specified, language will be set as `en` by default. Notably, in certain countries or regions, language will be automatically set as the local language due to the regional restrictions. Applicable languages: `ar`: Arabic `de`: German `en`: English `es`: Spanish `fr`: French `id`: Indonesian `it`: Italian `pt_BR`: Portuguese `ru`: Russian `tr`: Turkish `vi`: Vietnamese `zh_CN`: Simplified Chinese `zh_HK`: Traditional Chinese
  - `externalId` string — A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems. If present, this value will also be attached to the `externalId` of message objects.

## Response `200`

The request is successfully accepted.

- Verification
  - `id` string, required — ID of the verification.
  - `status` 'pending' | 'approved' | 'blocked' | 'expired' | 'undelivered' — Status of the verification. - `pending`: The verification message (SMS, Voice, etc.) is sent, waiting to be checked. This happens when you call the 'Start a verification' API successfully. - `approved`: The verification has been successfully checked. A `pending` verification status changes to `approved` when you call the 'Check a verification' API and receive a response with the `valid` parameter is `true`. An approved verification cannot be checked anymore. - `blocked`: The verification is blocked by user-defined rules such as denylist, and geographical permission restrictions. A blocked verification cannot be checked. - `expired`: The verification has expired and cannot be checked anymore. - `undelivered`: Our system has received a delivery receipt indicating that the verification message was not delivered. An undelivered verification cannot be checked anymore.
  - `to` string — Recipient of the verification.
  - `channel` 'sms' | 'voice' | 'email_code' | 'whatsapp' — Supports several independent channels for verification: - `sms`: Sends an SMS message with a verification code. - `voice`: Makes a voice call with a verification code. - `email_code`: Sends an email with a verification code. - `whatsapp`: Sends a WhatsApp message with a verification code.
  - `sendTime` string, date-time — The time at which this verification was sent, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`.
  - `totalPrice` number, double — Total price of this verification.
  - `currency` string — Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217).
  - `smsFallbackEnabled` boolean — Whether sms fallback is enabled or not. Applicable when `channel` is `whatsapp`. If enabled, we will try to send the verification code via sms when the WhatsApp message is failed.
  - `smsFallback` VerificationFallback — Contains information about verification fallback. For example, you can enable sms fallback for WhatsApp verification messages.
    - `supported` boolean — Whether this fallback you requested is supported. If `false` is returned, it means that there are errors for this fallback, and this fallback will not be triggered.
    - `unsupportedReason` string — The reason why the fallback is unsupported, e.g, `PARAM_INVALID`, `SMS_SIGNATURE_UNAVAILABLE`, `SENDER_ID_UNAVAILABLE`, or `MESSAGING_REGION_UNSUPPORTED`.
    - `unsupportedDetail` string — The detail message why the fallback is unsupported.
  - `externalId` string — A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.

---

[API](https://skmtc.dev/ycloud/apis/ycloud-api.md) · [All operations](https://skmtc.dev/ycloud/apis/ycloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ycloud/ycloud-api/revisions/4e13d3ca9df8/schema)