Verify OTP

Verify a one-time password (OTP) sent to a user’s phone number for secure authentication and validation. This endpoint is used to confirm OTPs during login, signup, multi-factor authentication (MFA), and transaction verification flows. It ensures that the OTP entered by the user matches the one issued and is still valid. Authentication is handled via secure headers, ensuring your credentials remain protected and are never exposed in the request body.

curl --request POST \
  --url https://ses.antryk.com/api/v1/sms/verify-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",
    "otp": "USER_OTP"
  }'

fetch("https://ses.antryk.com/api/v1/sms/verify-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",
    otp: "USER_OTP",
  }),
});

// 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 verifyOtp() {
  const result = await client.sms.verifyOtp({
    to: "+1XXXXXXXXXX",
    serviceId: "YOUR_SERVICE_ID",
    otp: "USER_OTP",
  });

  console.log(result.data);
}

verifyOtp();

# pip install requests
import requests

url = "https://ses.antryk.com/api/v1/sms/verify-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",
    "otp": "USER_OTP"
}

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

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

For Node.js applications, it is recommended to use the official @antryk/sdk. The SDK simplifies OTP verification by handling authentication, validation, and error handling internally.

Authentication is handled via headers (x-access-key, x-secret-key). The request body should only include OTP verification data such as phone number, service ID, and the OTP code.

New OTP Verification Approach (Recommended)

This is the recommended and modern approach for verifying OTPs:

Authentication is passed via headers instead of request body.
Request body contains only verification-related fields.
Improved security and cleaner API design.
Easier integration across backend services.

⚠️ The older approach (sending accessKey and secretKey in the request body) may still work for backward compatibility, but it is strongly recommended to migrate to header-based authentication.

Request Parameters

string

required

Your Antryk access key used for authentication.

string

required

Your Antryk secret key used to authorize the request securely.

string

required

The phone number (in E.164 format, e.g. +919876543210) that received the OTP.

string

required

UUID v4 identifier of your configured SMS verification service.

string

required

The OTP code entered by the user. Must be a 4–10 digit numeric value.

Always validate OTP input on the client side (length and numeric format) before sending the request to reduce unnecessary API calls.

OTPs are time-sensitive. Expired or incorrect OTPs will result in validation failure. Limit retry attempts to prevent abuse or brute-force attacks.

Examples

string

required

Example: YOUR_ACCESS_KEY

string

required

Example: YOUR_SECRET_KEY

string

required

Example: +919876543210

string

required

Example: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx

string

required

Example: 482193

Additional Notes

OTP verification is a critical step in authentication workflows.
Ensure that verification is performed securely on the backend.
Avoid exposing sensitive validation logic on the frontend.
Use retry limits and session-based controls to enhance security.
SDK usage is recommended for simplified integration and consistent error handling.

Response

Returns a JSON object indicating whether the OTP is valid and verified

{
  "success": true,
  "message": "Otp Verified Successfully!",
  "data": {
    "valid": true,
    "to": "+1XXXXXXXXXX",
    "status": "verified"
  }
}

Error Scenarios

400 otp_invalid – Incorrect or invalid OTP entered
404 otp_not_found – No pending OTP found for the given number and service
401 invalid_credentials – Invalid x-access-key or x-secret-key
410 otp_expired – OTP exists but has expired
429 rate_limited – Too many verification attempts in a short time

Invalid OTP example

{
  "success": true,
  "message": null,
  "data": {
    "valid": false,
    "status": "pending",
    "to": "+1XXXXXXXXXX"
  }
}

Limit verification retries per user session to prevent brute-force attempts. Lock the service after repeated otp_invalid responses.

Introduction

Storage Service

Email Service

SMS Service

New OTP Verification Approach (Recommended)

Request Parameters

Examples

Additional Notes

Response

Error Scenarios

Invalid OTP example

​New OTP Verification Approach (Recommended)

​Request Parameters

​Examples

​Additional Notes

​Response

​Error Scenarios

​Invalid OTP example

New OTP Verification Approach (Recommended)

Request Parameters

Examples

Additional Notes

Response

Error Scenarios

Invalid OTP example