> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send a voice code

> Deliver a verification code through an automated voice call.

## What it is

The Voice API places an automated call and reads a 4-to-6 digit verification
code to the recipient. Use it as a direct voice-code channel or as a fallback
when another verification channel is unavailable.

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

The Voice API delivers the code. Your application remains responsible for code
generation, attempt limits, expiration, and approval.

## Request

`POST /voices`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
  }'
```

Use an opaque `externalId` that helps your system correlate the delivery
without exposing the verification code.

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "VOICE_MESSAGE_ID"
}
```

The response confirms that YCloud accepted the voice request. It does not mean
the recipient answered the call or heard the complete code.

## Delivery status

Use delivery updates or list voice records to distinguish accepted, completed,
and failed calls. Keep delivery status separate from verification approval:
hearing a code does not prove that the correct user submitted it.

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

<CardGroup cols={2}>
  <Card title="Send voice code API" icon="volume-high" href="/api-reference/voices/send-a-voice-code">
    Inspect language, callback, and response fields.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.