Skip to main content

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.

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"
  }'
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.
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

​
x-access-key
string
required
Your Antryk access key used for authentication.
​
x-secret-key
string
required
Your Antryk secret key used to authorize the request securely.
​
to
string
required
The phone number (in E.164 format, e.g. +919876543210) that received the OTP.
​
serviceId
string
required
UUID v4 identifier of your configured SMS verification service.
​
otp
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

​
x-access-key
string
required
Example: YOUR_ACCESS_KEY
​
x-secret-key
string
required
Example: YOUR_SECRET_KEY
​
to
string
required
Example: +919876543210
​
serviceId
string
required
Example: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
​
otp
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.