Verify OTP

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

Field	Type	Required	Description
`sessionId`	string	Yes	OTP session identifier returned during OTP creation.
`code`	string	Yes	OTP 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

Field	Type	Description
`sessionId`	string	OTP session identifier.
`status`	string	Verification status.
`verified`	boolean	Indicates whether verification succeeded.
`message`	string	Human-readable verification result.

Verification Statuses

Status	HTTP Status	Description
`APPROVED`	`200`	OTP verified successfully.
`INVALID`	`400`	Incorrect OTP code supplied.
`EXPIRED`	`410`	OTP validity period has expired.
`MAX_ATTEMPTS_REACHED`	`423`	Verification attempt limit exceeded.
`ALREADY_USED`	`409`	OTP has already been successfully verified.
`NOT_FOUND`	`404`	OTP 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.

Introduction

Authentication

Messaging

OTP Service

Workspace

Errors

FAQs

Endpoint

Authentication

Request Body

Example Request

Successful Verification

Response Fields

Verification Statuses

Invalid OTP

Expired OTP

Maximum Attempts Reached

OTP Already Used

Session Not Found

Security Considerations

Workspace Isolation

OTP Service Overview

Request OTP

​Endpoint

​Authentication

​Request Body

​Example Request

​Successful Verification

​Response Fields

​Verification Statuses

​Invalid OTP

​Expired OTP

​Maximum Attempts Reached

​OTP Already Used

​Session Not Found

​Security Considerations

​Workspace Isolation

​Related Resources

OTP Service Overview

Request OTP

Endpoint

Authentication

Request Body

Example Request

Successful Verification

Response Fields

Verification Statuses

Invalid OTP

Expired OTP

Maximum Attempts Reached

OTP Already Used

Session Not Found

Security Considerations

Workspace Isolation

Related Resources