OTP Service

Two-Factor

Built-in One-Time Password (OTP) generation and verification. Send verification codes via SMS and validate them with a simple two-step API flow.

How It Works

Step 1: Send OTP

Generate and send a verification code to a phone number. Returns the messageId needed for verification.

Step 2: Verify OTP

Submit the code entered by the user along with the messageId to check if it matches.

Send OTP

POST

Generate a one-time password and send it via SMS to the specified phone number.

POST

https://api.smsgateway.com/api/v1/sms/otp

Request Body

Parameter	Type	Required	Description
to	string	Required	Recipient phone in E.164 format.
message	string	Optional	Message template. Use `{{code}}` as a placeholder for the generated code. Default: `Your verification code is {{code}}. It expires in 5 minutes.`
code	string	Optional	Custom 4–8 digit code. If omitted, a random code is generated.
senderId	string	Optional	Approved sender ID, max 15 characters.
expiresIn	integer	Optional	OTP expiry time in seconds. Range: 60–3600. Default: 300 (5 minutes).

Examples

Send OTP with cURL

1curl -X POST https://api.smsgateway.com/api/v1/sms/otp \
2  -H "Authorization: Bearer sg_live_xxxxxxxxxxxx" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "to": "+251911234567",
6    "message": "Your login code is {{code}}. Do not share it.",
7    "expiresIn": 600
8  }'

Response

Success response (201 Created)

1{
2  "success": true,
3  "data": {
4    "messageId": "otp_m9k8j7h6g5",
5    "code": "482901",
6    "to": "+251911234567",
7    "expiresAt": "2026-07-20T14:40:00.000Z",
8    "status": "SENT"
9  }
10}

Note: The code field is included in the response for server-side verification flows. If you need the code to be known only by the end user (e.g., client-side input), you can omit returning it by using the verify endpoint exclusively.

Verify OTP

POST

Verify a code submitted by the user against the previously generated OTP.

POST

https://api.smsgateway.com/api/v1/sms/verify-otp

Request Body

Parameter	Type	Required	Description
messageId	string	Required	The `messageId` returned from the Send OTP endpoint.
code	string	Required	The verification code entered by the user.

Examples

Verify OTP with cURL

1curl -X POST https://api.smsgateway.com/api/v1/sms/verify-otp \
2  -H "Authorization: Bearer sg_live_xxxxxxxxxxxx" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "messageId": "otp_m9k8j7h6g5",
6    "code": "482901"
7  }'

Response

Successful verification (200 OK)

1{
2  "success": true,
3  "data": {
4    "verified": true,
5    "status": "VERIFIED",
6    "messageId": "otp_m9k8j7h6g5"
7  }
8}

Failed verification (200 OK)

1{
2  "success": true,
3  "data": {
4    "verified": false,
5    "status": "INVALID_ATTEMPTS",
6    "messageId": "otp_m9k8j7h6g5",
7    "attemptsRemaining": 2
8  }
9}

Verification Statuses

Status	Description
VERIFIED	The code matches and the OTP is successfully verified.
EXPIRED	The OTP has passed its expiry time. Request a new one.
INVALID_ATTEMPTS	The code is incorrect. After 5 failed attempts the OTP is locked.

Rate Limits

Send OTP

30 req/min

Per organization

Verify OTP

50 req/min

Per organization