Send a voice code

​

What it is

​

Before you begin

• Activate Voice for your YCloud account.
• Collect the recipient’s phone number in E.164 format.
• Generate a short-lived 4-to-6 digit code.
• Choose a supported language.
• Decide whether status arrives through a callback URL or configured webhook.

​

How it works

1. Generate and securely store the verification challenge.
2. Send the code through the Voice API.
3. Store the returned voice record ID and your externalId.
4. Receive delivery updates through the callback or webhook.
5. Validate the code in your application and expire the challenge.

​

Request

curl --request POST https://api.ycloud.com/v2/voices \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "+16315551111",
    "verificationCode": "123456",
    "language": "en",
    "externalId": "login-7f10b6",
    "callbackUrl": "https://example.com/webhooks/voice"
  }'

​

Response

{
  "id": "VOICE_MESSAGE_ID"
}

​

Delivery status

​

Protect the verification flow

• Expire codes quickly.
• Limit send and check attempts by user, destination, IP, and device.
• Never log the verification code.
• Prevent a code from being reused after approval.
• Avoid revealing whether a phone number belongs to an account.

​

Limits and troubleshooting

• verificationCode must contain 4 to 6 digits.
• Phone numbers must use E.164 format.
• Language availability can vary by country or region.
• Use externalId and the YCloud record ID to investigate delivery.
• Prefer the Verify API when you want YCloud to manage both delivery and code checking as one verification lifecycle.