Request OTP

Use this endpoint to generate and deliver a one-time password (OTP) to a recipient. The response contains a session identifier that must be supplied when verifying the OTP.

Endpoint

POST /v1/messaging/otp/request

Authentication

Authorization: Bearer YOUR_API_KEY

Request Body

Field	Type	Required	Description
`dest`	string	Yes	Recipient phone number in international format.
`src`	string	Yes	Sender Name used to deliver the OTP.
`purpose`	string	Yes	Business purpose associated with the OTP request.
`messageTemplate`	string	No	Custom SMS template used for OTP delivery.

Supported Purposes

LOGIN
PASSWORD_RESET
TRANSACTION
DEVICE_VERIFICATION
EMAIL_VERIFICATION
ACCOUNT_RECOVERY
KYC_VERIFICATION

Example Request

{
  "dest": "+233202007745",
  "src": "ZECKTA",
  "purpose": "LOGIN"
}

Successful Response

{
  "success": true,
  "message": "OTP sent successfully",
  "data": {
    "sessionId": "feab6011-2469-4804-ace5-ee9dcb5b9ef2",
    "expiresInSeconds": 300,
    "attemptsLeft": 5,
    "reused": false
  }
}

Response Fields

Field	Description
`sessionId`	Unique OTP session identifier.
`expiresInSeconds`	Remaining OTP validity period in seconds.
`attemptsLeft`	Remaining verification attempts available.
`reused`	Indicates whether an existing OTP session was reused.

OTP Reuse

When OTP reuse is enabled, Zeckta may reuse an active OTP session if a valid OTP already exists for the same destination and purpose. In this scenario:

No new OTP is generated
No additional SMS is sent
The existing OTP remains valid until expiration

Example:

{
  "success": true,
  "message": "Active OTP already exists. No new SMS sent.",
  "data": {
    "sessionId": "feab6011-2469-4804-ace5-ee9dcb5b9ef2",
    "expiresInSeconds": 143,
    "attemptsLeft": 5,
    "reused": true
  }
}

When reused is true, clients should continue using the existing OTP and session identifier.

Validation Rules

Destination Number

Must be supplied in international E.164 format. Example:

+233202007745

Sender Name

Must be a valid Sender Name available to your workspace. Example:

ZECKTA

Message Template

Optional custom message template. If omitted, Zeckta uses the default OTP template.

Default Configuration

Validity Period: 5 Minutes
Maximum Verification Attempts: 5
OTP Length: 6 Digits

Workspace Isolation

OTP sessions are isolated by workspace. A workspace can only:

Request OTPs using its own API key
Verify OTPs generated within its own workspace
Access sessions associated with its own credentials

Cross-workspace access is not permitted.

Next Step

Verify OTP

Validate a received OTP using the session identifier returned from this endpoint.

Introduction

Authentication

Messaging

OTP Service

Workspace

Errors

FAQs

Endpoint

Authentication

Request Body

Supported Purposes

Example Request

Successful Response

Response Fields

OTP Reuse

Validation Rules

Destination Number

Sender Name

Message Template

Default Configuration

Workspace Isolation

Next Step

Verify OTP

​Endpoint

​Authentication

​Request Body

​Supported Purposes

​Example Request

​Successful Response

​Response Fields

​OTP Reuse

​Validation Rules

​Destination Number

​Sender Name

​Message Template

​Default Configuration

​Workspace Isolation

​Next Step

Verify OTP

Endpoint

Authentication

Request Body

Supported Purposes

Example Request

Successful Response

Response Fields

OTP Reuse

Validation Rules

Destination Number

Sender Name

Message Template

Default Configuration

Workspace Isolation

Next Step