OTP

Let SMSRay generate, send and check verification codes. You never store the code, and abuse limits are enforced for you.

On this page

POST /sms/otp/send · POST /sms/otp/verify

Send an OTP

POST/sms/otp/send

https://api.smsray.in/api/sms/v1/sms/otp/send

Generate a 6-digit code, send it as a branded one-segment SMS, and store only its SHA-256 hash. The code is valid for 5 minutes.

Request

Headers

Send an OTP request headers
Name	Type	Required	Rules
`x-api-key`	string	required	Your secret key, `ls_live_` followed by 48 hex characters.
`content-type`	string	required	`application/json`
`Idempotency-Key`	string	optional	1–200 printable ASCII characters. Safe retries for 24 h. See Idempotency.

Body parameters (JSON)

Send an OTP body parameters
Name	Type	Required	Rules
`to`	string	required	Nepal mobile number (`98XXXXXXXX`, `97…`, `96…`, `977`-prefixed accepted).
`purpose`	string	optional	Up to 50 characters. Defaults to `default`. Codes are scoped to (your client, `to`, `purpose`), so `login` and `reset-password` never collide.
`ip`	string	optional	Your end user's IP address, up to 64 characters. Enables the per-IP limit (10 OTPs per 10 minutes).
`senderId`	string	optional	Optional; same meaning as on `/sms/send`.

Example request

curl https://api.smsray.in/api/sms/v1/sms/otp/send \
  -H "x-api-key: $SMSRAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "to": "9779801234567", "purpose": "login", "ip": "203.0.113.7" }'

Response

200

200 application/json

{
  "success": true,
  "otpId": "9d5c0b7e-3a1f-4e62-8b1d-6a4f2c9e0d17",
  "messageId": "4f8a2c61-0b9e-4d3a-a7c5-1e6f9b2d8c40",
  "expiresInSeconds": 300
}

429Resend too soon

429 application/json

{
  "error": "Please wait before requesting another code",
  "code": "rate_limited"
}

Errors

Every error uses the same shape: { "error", "code", "details"? }. Branch on code, not on the message.

Send an OTP errors
HTTP	code	When
400	`invalid_request`	Validation failed, or the number is not a Nepal mobile.
402	`insufficient_balance`	Not enough balance for one OTP-rate segment.
401	`unauthorized`	The `x-api-key` header is missing ("Missing x-api-key") or the key is unknown ("Invalid API key").
403	`client_disabled`	The API client that owns this key has been disabled in the dashboard.
403	`forbidden`	OTP messages are not allowed for your workspace.
403	`workspace_pending`	Your workspace has not been activated by Lacspace yet, so it cannot send.
403	`workspace_suspended`	Your workspace is suspended.
409	`idempotency_conflict`	The same `Idempotency-Key` was used with a different body, or the first request is still running (`Retry-After: 1`).
429	`rate_limited`	Resend cooldown (60 s per number and purpose), 3 OTPs per number per 10 minutes, 10 per end-user IP per 10 minutes, 60 requests per minute per calling IP, or your per-client TPS. `Retry-After` is set whenever it is known.
503	`unavailable`	No sending route is available right now.
500	`server_error`	Something went wrong on our side. The body never contains a stack trace.

Notes

The SMS reads: <App>: 482913 is your verification code. Valid for 5 minutes. Do not share it. <App> is your API client's brand name (GSM-7, up to 30 characters, set in the dashboard).
The message is billed at your workspace's OTP rate and always fits in one GSM-7 segment.
The code is never stored or shown in plain text. In the dashboard and in GET /sms/messages/:id the text appears as (OTP hidden).
The per-number limit counts across every SMSRay customer, so one phone number cannot be flooded with codes from many apps.
OTPs skip pacing deferral: if every SIM is paced, the code moves to the next route at once rather than waiting.

Verify an OTP

POST/sms/otp/verify

https://api.smsray.in/api/sms/v1/sms/otp/verify

Check the code your user typed against the latest active code for the same number and purpose. Codes are single use.

Request

Headers

Verify an OTP request headers
Name	Type	Required	Rules
`x-api-key`	string	required	Your secret key, `ls_live_` followed by 48 hex characters.
`content-type`	string	required	`application/json`
`Idempotency-Key`	string	optional	1–200 printable ASCII characters. Safe retries for 24 h. See Idempotency.

Body parameters (JSON)

Verify an OTP body parameters
Name	Type	Required	Rules
`to`	string	required	The same number you sent the code to.
`code`	string	required	The 6 digits your user entered.
`purpose`	string	optional	Must match the `purpose` used on send. Defaults to `default`.

Example request

curl https://api.smsray.in/api/sms/v1/sms/otp/verify \
  -H "x-api-key: $SMSRAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "to": "9779801234567", "purpose": "login", "code": "482913" }'

Response

200Correct code

200 application/json

{ "success": true, "verified": true }

200Wrong code

200 application/json

{ "success": true, "verified": false, "reason": "invalid_code" }

Response fields

Verify an OTP response fields
Name	Type	Required	Rules
`verified`	boolean	required	`true` once, for the correct code. The code is then consumed.
`reason`	string	optional	Present when `verified` is false: `invalid_code`, `too_many_attempts` (5 wrong tries) or `no_active_otp` (none sent, expired or already used).

Errors

Every error uses the same shape: { "error", "code", "details"? }. Branch on code, not on the message.

Verify an OTP errors
HTTP	code	When
400	`invalid_request`	A required field is missing or malformed.
401	`unauthorized`	The `x-api-key` header is missing ("Missing x-api-key") or the key is unknown ("Invalid API key").
403	`client_disabled`	The API client that owns this key has been disabled in the dashboard.
403	`workspace_pending`	Your workspace has not been activated by Lacspace yet, so it cannot send.
403	`workspace_suspended`	Your workspace is suspended.
409	`idempotency_conflict`	The same `Idempotency-Key` was used with a different body, or the first request is still running (`Retry-After: 1`).
429	`rate_limited`	You exceeded your per-client request rate (default 20 requests per second). Honour `Retry-After`.
500	`server_error`	Something went wrong on our side. The body never contains a stack trace.

Notes

A wrong code is not an HTTP error. Always read verified; never treat a 200 as success on its own.
Each wrong code counts as an attempt. After 5 wrong attempts the code is locked and every further check returns too_many_attempts — send a new code.
Codes expire 5 minutes after they are sent and are deleted automatically afterwards.