Verify OTP POST
Checks the OTP code the user entered against the otpId from Request OTP. Every verification outcome is returned as HTTP 200 — read valid and status.code.
Authorization
API Key (Authentication) in the header Authorization: Bearer <API_KEY>.
HTTP Request
http
POST https://public-api.smsup-plus.com/OTP/verifyotpContent Type
application/json (JSON only)
Parameter Description
| Property | Type | Required | Description |
|---|---|---|---|
otpid | string | Required | otpId from Request OTP |
otpcode | string | Required | The code the user entered (including the prefix if the OTP config sets one) |
Response Description
| Property | Type | Description |
|---|---|---|
valid | boolean | true = code is correct |
otpId | string | The otpid you sent |
expired | boolean | true when the OTP has expired or is not found (omitted when false) |
maxAttemptsReached | boolean | true when all wrong attempts are used up (omitted when false) |
remainingAttempts | number | Attempts left |
status.code | string | See below |
status.message | string | See below |
status.description | string | See below |
Outcomes
status.code | status.message | status.description | Meaning |
|---|---|---|---|
200 | VERIFIED | OTP verified successfully | Code is correct (valid: true) — this OTP cannot be verified again |
401 | INVALID_CODE | Invalid OTP code. 2 attempts remaining | Wrong code; the number is the attempts left — or this OTP was already verified (0 left) |
410 | EXPIRED | OTP has expired | OTP expired, or the otpid is unknown (expired: true) |
429 | MAX_ATTEMPTS | Maximum verification attempts reached | Wrong code entered as many times as the OTP config allows (default 3); this OTP can no longer be used (maxAttemptsReached: true) |
TIP
- Every verification call (right or wrong) counts as one attempt
- After
MAX_ATTEMPTSorEXPIRED, have the user request a new OTP — Resend OTP does not restore attempts or extend the lifetime
Request Example
bash
curl -X POST 'https://public-api.smsup-plus.com/OTP/verifyotp' \
-H 'Authorization: Bearer <API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
"otpid": "7f3c9a1e-2b4d-4c6e-8a0f-1e3d5b7c9a2f",
"otpcode": "482913"
}'js
const res = await fetch('https://public-api.smsup-plus.com/OTP/verifyotp', {
method: 'POST',
headers: { Authorization: 'Bearer <API_KEY>', 'Content-Type': 'application/json' },
body: JSON.stringify({
otpid: '7f3c9a1e-2b4d-4c6e-8a0f-1e3d5b7c9a2f',
otpcode: '482913',
}),
})
console.log(await res.json())Response Example
Correct code:
json
{
"valid": true,
"otpId": "7f3c9a1e-2b4d-4c6e-8a0f-1e3d5b7c9a2f",
"remainingAttempts": 2,
"status": {
"code": "200",
"message": "VERIFIED",
"description": "OTP verified successfully"
}
}Wrong code:
json
{
"valid": false,
"otpId": "7f3c9a1e-2b4d-4c6e-8a0f-1e3d5b7c9a2f",
"remainingAttempts": 2,
"status": {
"code": "401",
"message": "INVALID_CODE",
"description": "Invalid OTP code. 2 attempts remaining"
}
}Expired:
json
{
"valid": false,
"otpId": "7f3c9a1e-2b4d-4c6e-8a0f-1e3d5b7c9a2f",
"expired": true,
"remainingAttempts": 0,
"status": {
"code": "410",
"message": "EXPIRED",
"description": "OTP has expired"
}
}Possible Errors
See Error Codes for the overview.
| HTTP | Response | Cause |
|---|---|---|
| 400 | {"error":{"code":"400","message":"BAD_REQUEST","description":"Invalid request body"}} | Body is not valid JSON, or otpid / otpcode is missing |
| 404 | {"error":{"code":"404","message":"OTP_NOT_FOUND","description":"OTP not found for this account"}} | The otpid belongs to another account (does not count as an attempt) |
| 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 verify OTP"}} | Temporary failure while verifying |
