Skip to main content
Use this endpoint to validate an OTP that was previously generated by the OTP Service. Verification requires:
  • The sessionId returned from the OTP request
  • The OTP code received by the user
A successful verification marks the OTP session as used and prevents future reuse.

​
Endpoint

POST /v1/messaging/otp/verify

​
Authentication

Authorization: Bearer YOUR_API_KEY

​
Request Body

FieldTypeRequiredDescription
sessionIdstringYesOTP session identifier returned during OTP creation.
codestringYesOTP code received by the user.

​
Example Request

{
  "sessionId": "feab6011-2469-4804-ace5-ee9dcb5b9ef2",
  "code": "123456"
}

​
Successful Verification

HTTP 200 
{
  "success": true,
  "message": "OTP verification successful",
  "data": {
    "sessionId": "feab6011-2469-4804-ace5-ee9dcb5b9ef2",
    "status": "APPROVED",
    "verified": true,
    "message": "OTP verified successfully"
  }
}

​
Response Fields

FieldTypeDescription
sessionIdstringOTP session identifier.
statusstringVerification status.
verifiedbooleanIndicates whether verification succeeded.
messagestringHuman-readable verification result.

​
Verification Statuses

StatusHTTP StatusDescription
APPROVED200OTP verified successfully.
INVALID400Incorrect OTP code supplied.
EXPIRED410OTP validity period has expired.
MAX_ATTEMPTS_REACHED423Verification attempt limit exceeded.
ALREADY_USED409OTP has already been successfully verified.
NOT_FOUND404OTP session could not be found.

​
Invalid OTP

HTTP 400 
{
  "success": false,
  "message": "Invalid OTP",
  "data": {
    "sessionId": "feab6011-2469-4804-ace5-ee9dcb5b9ef2",
    "status": "INVALID",
    "verified": false,
    "message": "Invalid OTP"
  }
}

​
Expired OTP

HTTP 410 
{
  "success": false,
  "message": "OTP expired",
  "data": {
    "sessionId": "feab6011-2469-4804-ace5-ee9dcb5b9ef2",
    "status": "EXPIRED",
    "verified": false,
    "message": "OTP expired"
  }
}

​
Maximum Attempts Reached

HTTP 423 
{
  "success": false,
  "message": "Maximum verification attempts reached",
  "data": {
    "sessionId": "feab6011-2469-4804-ace5-ee9dcb5b9ef2",
    "status": "MAX_ATTEMPTS_REACHED",
    "verified": false,
    "message": "Maximum verification attempts reached"
  }
}

​
OTP Already Used

HTTP 409 
{
  "success": false,
  "message": "OTP already used",
  "data": {
    "sessionId": "feab6011-2469-4804-ace5-ee9dcb5b9ef2",
    "status": "ALREADY_USED",
    "verified": false,
    "message": "OTP already verified"
  }
}

​
Session Not Found

HTTP 404 
{
  "success": false,
  "message": "OTP session not found",
  "data": {
    "sessionId": "feab6011-2469-4804-ace5-ee9dcb5b9ef2",
    "status": "NOT_FOUND",
    "verified": false,
    "message": "OTP session not found"
  }
}

​
Security Considerations

  • Always use HTTPS.
  • OTP sessions are single-use.
  • Successfully verified OTPs cannot be reused.
  • Verification attempts are limited.
  • Expired OTPs must be re-requested.
  • Store API credentials securely.

​
Workspace Isolation

OTP sessions are isolated by workspace. A workspace can only verify OTP sessions generated within that same workspace. Cross-workspace verification is not permitted.

OTP Service Overview

Learn how the OTP service works.

Request OTP

Generate and deliver an OTP.