# Send a one-time code to a phone number or an email address

`POST /verify/services/{id}/verifications` · Rivier · voice

Send a one-time code to a phone number or an email address. channel auto uses the service's order and falls back by itself when a channel fails. Rate limits, fraud guards, opt-outs and the plan's allowance are checked first; a refusal says which rule and what to do. The code itself is never returned (only in the mock, where nothing is sent).

- Scope: voice:write
- Mcp: rivier_verify_start
- Graphql: Mutation.voiceVerifyStartCreate
- Sdk: verify.start
- Cli: verify start

## Parameters

- `id` (path, required), string

## Request body

`application/json`

```json
{
  "type": "object",
  "properties": {
    "to": {
      "type": "string",
      "minLength": 3,
      "maxLength": 320,
      "description": "A phone number (E.164, or national with the service's default country) or an email address"
    },
    "channel": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "sms",
            "whatsapp",
            "call",
            "email"
          ]
        },
        {
          "type": "string",
          "const": "auto"
        }
      ],
      "default": "auto"
    },
    "locale": {
      "type": "string",
      "minLength": 2,
      "maxLength": 10
    },
    "customCode": {
      "type": "string",
      "minLength": 4,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9]+$",
      "description": "A code you made, when the service allows custom codes"
    },
    "ip": {
      "type": "string",
      "maxLength": 64,
      "description": "The caller's network address, for rate limits and fraud checks"
    },
    "userId": {
      "type": "string",
      "maxLength": 120
    },
    "deviceId": {
      "type": "string",
      "maxLength": 120
    },
    "tags": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "maxLength": 120
      }
    },
    "amount": {
      "type": "string",
      "maxLength": 40
    },
    "payee": {
      "type": "string",
      "maxLength": 120
    }
  },
  "required": [
    "to"
  ],
  "additionalProperties": false
}
```

## Responses

- `201`: Success
- `400`: The request was malformed
- `401`: No valid credential
- `403`: The credential lacks the scope, origin or address
- `429`: Over the key's rate limit; see Retry-After

## Example

```sh
curl -X POST 'https://api.rivier.ai/verify/services/{id}/verifications' \
  -H 'Authorization: Bearer $KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "to": "string"
}'
```