OTP API

OTP API Reference

Generate and verify one-time passwords for user authentication, password resets, and account verification.

Send OTP

Generate and send a one-time password to a recipient.

POST /api/v1/otp

Parameter	Type	Required	Description
to	string	Required	Recipient phone number in E.164 format
length	integer	Optional	OTP length: 4-8 digits (default: 6)
expiry_minutes	integer	Optional	Validity period: 1-30 minutes (default: 5)
template	string	Optional	Custom message template with {code} placeholder
reference	string	Optional	Your reference ID

Send an OTP

curl -X POST "https://api.yourdomain.com/api/v1/otp" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+265888123456",
    "length": 6,
    "expiry_minutes": 5,
    "template": "Your verification code is {code}. Valid for {expiry} minutes."
  }'

200 OK

{
  "success": true,
  "otp_id": "otp_abc123",
  "status": "sent",
  "expires_in": 300,
  "cost": 0.08
}

Verify OTP

Verify a code entered by the user.

POST /api/v1/sms/verify-otp

Parameter	Type	Required	Description
to	string	Required	Recipient phone number
code	string	Required	The OTP code to verify

Verify an OTP

curl -X POST "https://api.yourdomain.com/api/v1/sms/verify-otp" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+265888123456",
    "code": "123456"
  }'

Success Response

200 OK — Valid OTP

{
  "success": true,
  "valid": true,
  "message": "OTP verified successfully"
}

Invalid OTP Response

200 OK — Invalid OTP

{
  "success": true,
  "valid": false,
  "message": "Invalid or expired OTP",
  "attempts_remaining": 2
}

SDK Example: Python

otp_example.py

import requests

BASE_URL = "https://api.yourdomain.com"

# Authenticate (see Authentication docs)
token = "YOUR_ACCESS_TOKEN"

# Send OTP
send_response = requests.post(
    f"{BASE_URL}/api/v1/otp",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "to": "+265888123456",
        "length": 6,
        "expiry_minutes": 5
    }
).json()

print(f"OTP sent: {send_response}")

# Verify OTP (user enters the code)
verify_response = requests.post(
    f"{BASE_URL}/api/v1/sms/verify-otp",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "to": "+265888123456",
        "code": "123456"  # User-entered code
    }
).json()

if verify_response["valid"]:
    print("OTP verified! Proceed with login.")
else:
    print(f"Invalid OTP: {verify_response['message']}")