Skip to content

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/verifyotp

Content Type ​

application/json (JSON only)

Parameter Description ​

PropertyTypeRequiredDescription
otpidstringRequiredotpId from Request OTP
otpcodestringRequiredThe code the user entered (including the prefix if the OTP config sets one)

Response Description ​

PropertyTypeDescription
validbooleantrue = code is correct
otpIdstringThe otpid you sent
expiredbooleantrue when the OTP has expired or is not found (omitted when false)
maxAttemptsReachedbooleantrue when all wrong attempts are used up (omitted when false)
remainingAttemptsnumberAttempts left
status.codestringSee below
status.messagestringSee below
status.descriptionstringSee below

Outcomes ​

status.codestatus.messagestatus.descriptionMeaning
200VERIFIEDOTP verified successfullyCode is correct (valid: true) — this OTP cannot be verified again
401INVALID_CODEInvalid OTP code. 2 attempts remainingWrong code; the number is the attempts left — or this OTP was already verified (0 left)
410EXPIREDOTP has expiredOTP expired, or the otpid is unknown (expired: true)
429MAX_ATTEMPTSMaximum verification attempts reachedWrong 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_ATTEMPTS or EXPIRED, 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.

HTTPResponseCause
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