Skip to content

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 ​

http
POST https://public-api.smsup-plus.com/OTP/requestotp

Content Type ​

application/json (JSON only)

Parameter Description ​

PropertyTypeRequiredDescription
otcidstringRequiredID 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
mobilestringRequiredThai mobile number, same format as to in Send SMS, e.g. 0812345678
notifyUrlstringOptionalAccepted for backward compatibility; currently has no effect
notifyContentTypestringOptionalAccepted for backward compatibility; currently has no effect
callbackDatastringOptionalAccepted for backward compatibility; currently has no effect
vpstringOptionalAccepted for backward compatibility; currently has no effect (the OTP lifetime comes from the OTP config)

OTP behaviour ​

ItemValue
OTP codeDigits, length from the OTP config (default 6, minimum 4), preceded by the prefix if one is set
Reference code6 uppercase letters, e.g. KQZPWD; stays the same after Resend OTP
LifetimeFrom the OTP config (default 300 seconds, minimum 30), counted from the request
Wrong attempts allowedFrom the OTP config (default 3)
Resends allowed3 per otpId
SMS textFrom 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 limitAt most 3 requests per number per account within 10 minutes
CreditPrepaid 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.

PropertyTypeDescription
otcIdstringThe otcid you sent
otpIdstringID of this OTP (UUID), used with Verify OTP and Resend OTP
referenceCodestring6-letter reference code
success.codestring"200"
success.messagestringSUCCESS
success.descriptionstringOTP has been sent successfully

Request Example ​

bash
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"
  }'
js
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 ​

json
{
  "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.

HTTPResponseCause
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