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

# Send OTP

> Send a one-time passcode over SMS, WhatsApp, voice, or email with the Dojah Messaging API, then validate it with the returned reference_id.

<div className="dj-endpoint">
  <span className={`dj-method dj-method-post`}>POST</span>
  <code>/api/v1/messaging/otp</code>
</div>

Send a one-time passcode over SMS, WhatsApp, voice, or email. The response returns a reference\_id you’ll pass to Validate OTP to confirm the code the user enters.

## Headers

| Header          | Required | Description                        |
| --------------- | -------- | ---------------------------------- |
| `Authorization` | Yes      | Your app's secret key, sent as-is. |
| `AppId`         | Yes      | The App ID from your dashboard.    |
| `Content-Type`  | Yes      | `application/json`                 |

## Body parameters

| Parameter     | Type    | Required | Description                                                              |
| ------------- | ------- | -------- | ------------------------------------------------------------------------ |
| `sender_id`   | string  | Yes      | A registered Sender ID to send from.                                     |
| `destination` | string  | Yes      | Recipient phone number (for SMS, WhatsApp, voice).                       |
| `channel`     | string  | Yes      | Delivery channel: `sms`, `whatsapp`, `voice`, or `email`.                |
| `email`       | string  | No       | Recipient email address — required when `channel` is `email`.            |
| `length`      | integer | No       | Number of digits in the code, 4–10. Default `6`.                         |
| `expiry`      | integer | No       | Minutes before the code expires. Default `10`.                           |
| `priority`    | boolean | No       | Send in priority mode. Default `false`.                                  |
| `otp`         | integer | No       | Supply your own code (4–10 digits) instead of having Dojah generate one. |

## Response

Returns `200 OK` with an `entity` object. Store the `reference_id` — it’s the only way to validate the code later.

| Field          | Type   | Description                                                   |
| -------------- | ------ | ------------------------------------------------------------- |
| `reference_id` | string | Unique ID for this OTP. Pass it to Validate OTP.              |
| `destination`  | string | The phone number or email the code was sent to.               |
| `status`       | string | Human-readable delivery status, e.g. `SMS sent successfully`. |

## Errors

| Code  | Meaning                                                                                                                   |
| ----- | ------------------------------------------------------------------------------------------------------------------------- |
| `400` | Bad request — a required field is missing or malformed.                                                                   |
| `401` | Unauthorized — check your `Authorization` key and `AppId`.                                                                |
| `402` | Payment required — your wallet balance is too low. [Fund your wallet](/dashboard-guide/getting-started/fund-your-wallet). |
| `422` | Unprocessable — e.g. an unregistered `sender_id` or invalid `channel`.                                                    |
| `429` | Too many requests — slow your request rate and retry.                                                                     |

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.dojah.io/api/v1/messaging/otp" \
    -H "Authorization: {{secret_key}}" \
    -H "AppId: {{app_id}}" \
    -H "Content-Type: application/json" \
    -d '{
      "sender_id": "Dojah",
      "destination": "2348012345678",
      "channel": "sms",
      "length": 6,
      "expiry": 10
    }'
  ```

  ```js Node.js theme={null}
  const res = await fetch("https://api.dojah.io/api/v1/messaging/otp", {
    method: "POST",
    headers: {
      Authorization: process.env.DOJAH_SECRET_KEY,
      AppId: process.env.DOJAH_APP_ID,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      sender_id: "Dojah",
      destination: "2348012345678",
      channel: "sms",
      length: 6,
      expiry: 10,
    }),
  });
  const data = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  res = requests.post(
      "https://api.dojah.io/api/v1/messaging/otp",
      headers={
          "Authorization": os.environ["DOJAH_SECRET_KEY"],
          "AppId": os.environ["DOJAH_APP_ID"],
      },
      json={
          "sender_id": "Dojah",
          "destination": "2348012345678",
          "channel": "sms",
          "length": 6,
          "expiry": 10,
      },
  )
  data = res.json()
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.dojah.io/api/v1/messaging/otp");
  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
      "Authorization: " . getenv("DOJAH_SECRET_KEY"),
      "AppId: " . getenv("DOJAH_APP_ID"),
      "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
      "sender_id"   => "Dojah",
      "destination" => "2348012345678",
      "channel"     => "sms",
      "length"      => 6,
      "expiry"      => 10,
    ]),
  ]);
  $data = json_decode(curl_exec($ch), true);
  ```
</RequestExample>

<ResponseExample>
  ```json POST /api/v1/messaging/otp theme={null}
  {
    "entity": {
      "reference_id": "edd37ab5-48ec-4481-8cf9-ba5chu7c41f7",
      "destination": "2348012345678",
      "status": "SMS sent successfully"
    }
  }
  ```
</ResponseExample>