OTP

Get All OTPs

Retrieve a paginated list of all OTP records for your account. Filter by phone number or status to narrow results.

GET

/v1/otp/otps

Authorization

Header

X-Emisri-Api-Key: your_secret_key

Required

yes

Query parameters

Field	Type	Required	Description
page	number	no	Page number to retrieve. Defaults to 1.
size	number	no	Number of records per page. Defaults to 20.
phone	string	no	Filter OTPs by recipient phone number in international format (e.g. 2348012345678). Matches against the destination field on each OTP.
status	string	no	Filter by OTP status. Accepted values: PENDING, VERIFIED, EXPIRED, REVOKED.

Response · 200 OK

application/json

Field	Type	Required	Description
success	boolean	—	true when the request completed successfully.
data	object	—	The response payload.
meta	object	—	Request metadata.

OTP object

Field	Type	Required	Description
otpId	string	—	Unique ID assigned to the OTP.
destination	string	—	The phone number this OTP was sent to.
sender	string	—	The Sender ID the OTP was dispatched from.
channel	string	—	Delivery channel used to send the OTP (e.g. sms).
codeLength	number	—	Number of digits in the generated OTP code.
status	string	—	Current status of the OTP. See Status Values table below.
expiresAt	string	—	ISO 8601 timestamp of when the OTP expires.
verifiedAt	string \| null	—	ISO 8601 timestamp of when the OTP was verified, or null if not yet verified.
revokedAt	string \| null	—	ISO 8601 timestamp of when the OTP was revoked, or null if not revoked.
createdAt	string	—	ISO 8601 timestamp of when the OTP was created.

Status values

Use any of these values with the status query parameter to filter results.

Value	Description
PENDING	OTP has been sent and is awaiting verification.
VERIFIED	OTP was successfully verified by the user.
EXPIRED	OTP passed its expiry window without being verified.
REVOKED	OTP was manually invalidated via the revoke endpoint.

Request Samples

Request · basic

const response = await fetch(
  'https://BASE_URL/v1/otp/otps?page=1&size=20',
  {
    headers: {
      'X-Emisri-Api-Key': 'your_secret_key',
    },
  }
)
const data = await response.json()

Response Samples

Response · 200 OK

{
  "success": true,
  "data": {
    "otps": [
      {
        "otpId": "otp_1ea2c8dbf2bf425c8d",
        "destination": "234812345689",
        "sender": "SENDERNAME",
        "channel": "sms",
        "codeLength": 8,
        "status": "Expired",
        "expiresAt": "2026-07-03T12:44:00.627Z",
        "verifiedAt": null,
        "revokedAt": null,
        "createdAt": "2026-07-03T12:39:00.658Z"
      },
      {
        "otpId": "otp_4774079a93b3432bbe",
        "destination": "234812345689",
        "sender": "SENDERNAME",
        "channel": "sms",
        "codeLength": 8,
        "status": "Expired",
        "expiresAt": "2026-07-03T09:52:41.746Z",
        "verifiedAt": null,
        "revokedAt": null,
        "createdAt": "2026-07-03T09:47:41.790Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 2,
      "totalPages": 1
    }
  },
  "meta": {
    "requestId": "req_ULN10gMJmj2a_qct"
  }
}