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

# Send OTP

Send a one-time password (OTP) to a user's phone number for secure authentication and verification.

This endpoint is designed for multi-factor authentication (MFA), login verification, onboarding flows, and transaction confirmations. It ensures reliable OTP delivery using Antryk’s scalable SMS infrastructure.

Authentication is handled via secure headers, keeping your credentials protected and separate from the request payload.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://ses.antryk.com/api/v1/sms/send-otp \
    --header "Content-Type: application/json" \
    --header "x-access-key: YOUR_ACCESS_KEY" \
    --header "x-secret-key: YOUR_SECRET_KEY" \
    --data '{
      "to": "+1XXXXXXXXXX",
      "serviceId": "YOUR_SERVICE_ID"
    }'
  ```

  ```javascript JavaScript theme={null}
  fetch("https://ses.antryk.com/api/v1/sms/send-otp", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-access-key": "YOUR_ACCESS_KEY",
      "x-secret-key": "YOUR_SECRET_KEY",
    },
    body: JSON.stringify({
      to: "+1XXXXXXXXXX",
      serviceId: "YOUR_SERVICE_ID",
    }),
  });
  ```

  ```javascript NodeJs theme={null}
  // npm i @antryk/sdk
  import { AntrykClient } from "@antryk/sdk";

  const client = new AntrykClient({
    accessKey: process.env.ANTRYK_ACCESS_KEY,
    secretKey: process.env.ANTRYK_SECRET_KEY,
  });

  async function sendOtp() {
    const result = await client.sms.sendOtp({
      to: "+1XXXXXXXXXX",
      serviceId: "YOUR_SERVICE_ID",
    });

    console.log(result.data);
  }

  sendOtp();
  ```

  ```python python theme={null}

  # pip install requests
  import requests

  url = "https://ses.antryk.com/api/v1/sms/send-otp"

  headers = {
      "Content-Type": "application/json",
      "x-access-key": "YOUR_ACCESS_KEY",
      "x-secret-key": "YOUR_SECRET_KEY"
  }

  data = {
      "to": "+1XXXXXXXXXX",
      "serviceId": "YOUR_SERVICE_ID"
  }

  response = requests.post(url, headers=headers, json=data)

  print(response.status_code)
  print(response.json())

  ```
</CodeGroup>

<Note>
  {" "}

  For Node.js applications, it is recommended to use the official
  [`@antryk/sdk`](https://www.npmjs.com/package/@antryk/sdk). The SDK simplifies
  OTP delivery by handling authentication, validation, retries, and error
  handling internally.{" "}
</Note>

<Note>
  {" "}

  Authentication is handled via headers (`x-access-key`, `x-secret-key`). The
  request body should only include OTP-related fields such as recipient number
  and service ID.{" "}
</Note>

### New OTP Sending Approach (Recommended)

This is the recommended and modern approach for sending OTPs:

* Authentication is passed via headers instead of the request body.
* Request body contains only OTP-related parameters.
* Improved security by isolating credentials from payload.
* Cleaner and more maintainable API integration.

<Note>
  {" "}

  ⚠️ The older approach (passing `accessKey` and `secretKey` in the request
  body) may still work for backward compatibility, but it is **strongly
  recommended to migrate to header-based authentication**.{" "}
</Note>

## Request Parameters

<ParamField header="x-access-key" type="string" required>
  {" "}

  Your Antryk access key used to authenticate API requests.{" "}
</ParamField>

<ParamField header="x-secret-key" type="string" required>
  {" "}

  Your Antryk secret key used to securely authorize the request.{" "}
</ParamField>

<ParamField body="to" type="string" required>
  {" "}

  Recipient phone number in E.164 format (e.g. `+1XXXXXXXXXX`). Only one number
  is supported per request.{" "}
</ParamField>

<ParamField body="serviceId" type="string" required>
  {" "}

  Unique identifier (UUID v4) of your configured SMS verification service.{" "}
</ParamField>

<Tip>
  Always store phone numbers in E.164 format (e.g. `+919876543210`) to ensure
  compatibility and successful OTP delivery.{" "}
</Tip>

<Warning>
  Invalid phone numbers or incorrectly formatted `serviceId` values will result
  in request failure. Ensure inputs are validated before sending requests.{" "}
</Warning>

## Examples

<ParamField header="x-access-key" type="string" required>
  {" "}

  Example: YOUR\_ACCESS\_KEY{" "}
</ParamField>

<ParamField header="x-secret-key" type="string" required>
  {" "}

  Example: YOUR\_SECRET\_KEY{" "}
</ParamField>

<ParamField body="to" type="string" required>
  {" "}

  Example: +919876543210{" "}
</ParamField>

<ParamField body="serviceId" type="string" required>
  {" "}

  Example: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx{" "}
</ParamField>

<Note>
  ### Additional Notes

  * Supports secure OTP delivery for login, signup, and transaction verification.
  * Each OTP is time-bound and automatically expires after a defined duration.
  * Avoid exposing API keys in client-side applications.
  * Use server-side integrations or the SDK for better security and reliability.
</Note>

## Successful Response

Returns a JSON object confirming that the OTP has been successfully sent.

```json theme={null}
{
  "success": true,
  "message": "Otp Sent Successfully!",
  "data": {
    "to": "+1XXXXXXXXXX",
    "serviceId": "YOUR_SERVICE_ID",
    "status": "pending"
  }
}
```

The OTP expires five minutes after issuance. Subsequent verification attempts with the same code after this window return `410 otp_expired`.

## Error Scenarios

* **401 invalid\_credentials – Incorrect x-access-key or x-secret-key**
* **400 invalid\_recipient – Missing or improperly formatted phone number**
* **409 otp\_pending – A previously sent OTP is still active**
* **429 rate\_limited – Too many OTP requests in a short time**
* **401 invalid\_request – Invalid or missing serviceId**
* **500 provider\_unavailable – Temporary SMS gateway failure**

### Invalid Service ID Example

```json theme={null}
{
  "success": false,
  "errors": [
    {
      "message": "Invalid Request",
      "code": 401
    }
  ]
}
```