Request OTP POST
Generates an OTP code and sends it by SMS to the user's number. The response returns an otpId (used with Verify OTP and Resend OTP) and a referenceCode (show it on screen so the user can match it with the SMS). The OTP code itself is never returned in the response.
Authorization
API Key (Authentication) in the header Authorization: Bearer <API_KEY>.
Supports an optional Idempotency-Key header so a retry does not send a second OTP — same rules as Send SMS: characters A-Z a-z 0-9 _ -, 1–128 long; a successful result is stored for 24 hours; a repeat gets the same response with the header Idempotent-Replayed: true; if the first request fails (including an HTTP 200 reply that carries error), the key can be reused immediately.
HTTP Request
POST https://public-api.smsup-plus.com/OTP/requestotpContent Type
application/json (JSON only)
Parameter Description
| Property | Type | Required | Description |
|---|---|---|---|
otcid | string | Required | ID of your account's OTP config, created in the OTP menu of the SMSUP Plus web app — it defines the sender name, message, code length, lifetime and allowed attempts |
mobile | string | Required | Thai mobile number, same format as to in Send SMS, e.g. 0812345678 |
notifyUrl | string | Optional | Accepted for backward compatibility; currently has no effect |
notifyContentType | string | Optional | Accepted for backward compatibility; currently has no effect |
callbackData | string | Optional | Accepted for backward compatibility; currently has no effect |
vp | string | Optional | Accepted for backward compatibility; currently has no effect (the OTP lifetime comes from the OTP config) |
OTP behaviour
| Item | Value |
|---|---|
| OTP code | Digits, length from the OTP config (default 6, minimum 4), preceded by the prefix if one is set |
| Reference code | 6 uppercase letters, e.g. KQZPWD; stays the same after Resend OTP |
| Lifetime | From the OTP config (default 300 seconds, minimum 30), counted from the request |
| Wrong attempts allowed | From the OTP config (default 3) |
| Resends allowed | 3 per otpId |
| SMS text | From the template in the OTP config — {Code OTP} is replaced by the code, {Ref Code} by the reference code, any other {...} is removed (default Your OTP code is {Code OTP}. Ref: {Ref Code}) |
| Request limit | At most 3 requests per number per account within 10 minutes |
| Credit | Prepaid accounts need at least 1 credit — each OTP SMS is charged by message length like Send SMS |
OTP SMS are not blocked by the general opt-out list or by consent requirements.
Response Description
HTTP 200 is returned both on success and for some failures — check whether the body has success or error.
| Property | Type | Description |
|---|---|---|
otcId | string | The otcid you sent |
otpId | string | ID of this OTP (UUID), used with Verify OTP and Resend OTP |
referenceCode | string | 6-letter reference code |
success.code | string | "200" |
success.message | string | SUCCESS |
success.description | string | OTP has been sent successfully |
Request Example
curl -X POST 'https://public-api.smsup-plus.com/OTP/requestotp' \
-H 'Authorization: Bearer <API_KEY>' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: 5a0e2d4c-1f3b-4e6a-8c9d-7b2a1e0f3c4d' \
-d '{
"otcid": "c2a4e6f8-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
"mobile": "0812345678"
}'const res = await fetch('https://public-api.smsup-plus.com/OTP/requestotp', {
method: 'POST',
headers: {
Authorization: 'Bearer <API_KEY>',
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
otcid: 'c2a4e6f8-1b3d-4f5a-9c7e-0d2b4f6a8c1e',
mobile: '0812345678',
}),
})
console.log(await res.json())Response Example
{
"otcId": "c2a4e6f8-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
"otpId": "7f3c9a1e-2b4d-4c6e-8a0f-1e3d5b7c9a2f",
"referenceCode": "KQZPWD",
"success": {
"code": "200",
"message": "SUCCESS",
"description": "OTP has been sent successfully"
}
}Possible Errors
OTP errors use the shape {"error":{"code","message","description"}} (except Idempotency-Key, rate-limit and authentication errors). See Error Codes for the overview.
| HTTP | Response | Cause |
|---|---|---|
| 200 | {"error":{"code":"500","message":"INTERNAL_SERVER_ERROR","description":"Failed to process OTP request"}} | Invalid number, more than 3 requests in 10 minutes for this number, or a temporary system failure — no OTP was created |
| 400 | {"error":{"code":"400","message":"BAD_REQUEST","description":"Invalid request body"}} | Body is not valid JSON, or otcid / mobile is missing |
| 400 | {"error":"invalid Idempotency-Key"} | Idempotency-Key has invalid characters or is longer than 128 |
| 402 | {"error":{"code":"402","message":"INSUFFICIENT_CREDIT","description":"insufficient credit: required 1.00, available 0.00"}} | Prepaid account has less than 1 credit |
| 403 | {"error":{"code":"403","message":"ACCOUNT_INACTIVE","description":"account is inactive"}} | Account is inactive |
| 403 | {"error":{"code":"403","message":"ACCOUNT_HELD","description":"account is on credit hold"}} | Account is on credit hold |
| 403 | {"error":{"code":"403","message":"SERVICE_NOT_ALLOWED","description":"OTP is not enabled for this account"}} | OTP is not enabled for the account |
| 404 | {"error":{"code":"404","message":"OTP_CONFIG_NOT_FOUND","description":"OTP config not found for this account"}} | otcid not found or not owned by your account |
| 409 | {"error":"request with this Idempotency-Key is in progress"} | A request with the same key is still running |
| 429 | {"error":{"statusCode":"429","description":"rate limit exceeded: max 50 requests per second per account","message":"TOO_MANY_REQUESTS"}} | Too many requests — wait as told by Retry-After |
| 500 | {"error":{"code":"500","message":"INTERNAL_SERVER_ERROR","description":"Failed to validate OTP request"}} | Temporary failure while checking the request |
