Overview
Generate and send a one-time password (OTP) to a phone number for verification purposes. This endpoint creates a secure OTP and sends it via SMS, returning a request ID that can be used to verify the code later.Endpoint
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
lang | string | ✅ | Language for the OTP message: ar or en |
length | integer | ✅ | Length of the OTP code: 4 or 6 |
expiration | integer | ✅ | Expiration time in minutes (range: 1–10) |
sender | string | ✅ | The sender ID (up to 11 characters) |
payment_type | string | ✅ | Payment method: wallet or subscription |
receiver | string | ✅ | The recipient’s phone number in international format |
Parameter Details
lang
lang
The language for the OTP message template.
en: English message templatear: Arabic message template- Default templates: Pre-defined secure message formats
length
length
The number of digits in the OTP code.
4: 4-digit code (e.g., 1234)6: 6-digit code (e.g., 123456)- Security: 6-digit codes provide better security
expiration
expiration
How long the OTP remains valid.
- Range: 1 to 10 minutes (inclusive)
- Guidance: Shorter durations (1–5) increase security; longer durations (6–10) improve UX
sender
sender
The sender ID that will appear on the recipient’s device.
- Length: Maximum 11 characters
- Format: Alphanumeric characters only
- Examples:
Lamah,Verify,Security
payment_type
payment_type
Specifies how the OTP SMS cost will be charged.
wallet: Deduct from your account balancesubscription: Use your subscription plan credits
receiver
receiver
The recipient’s phone number in international format.
- Format: Must include country code (e.g.,
+218912345678or00218912345678) - Validation: Number will be validated before sending
Response
Success Response (200 OK)
Response Fields
| Field | Type | Description |
|---|---|---|
request_id | string | UUID for this OTP request |
cost | number | Number of SMS parts charged for this send |
Error Responses
400 Bad Request - Invalid Parameters
400 Bad Request - Invalid Expiration
400 Bad Request - Invalid Phone Number
401 Unauthorized
402 Payment Required
429 Too Many Requests
Message Templates
English Template (lang: “en”)
Arabic Template (lang: “ar”)
Rate Limits
Rate Limit Details
- Per phone number: 10 requests per minute
- Per project: 1000 requests per minute
- Cooldown period: 60 seconds after rate limit is hit
Security Best Practices
Use 6-digit codes
6-digit codes provide better security than 4-digit codes
Short expiration
Use 1-5 minute expiration for sensitive operations
Rate limiting
Implement client-side rate limiting to prevent abuse
Secure storage
Never log or store the actual OTP codes
Implementation Example
Next Steps
After initiating an OTP, you’ll need to verify the code that the user receives. Use the Verify OTP endpoint with therequest_id returned from this endpoint.
Common Use Cases
User Registration
Verify phone numbers during account creation
Login Verification
Two-factor authentication for secure login
Password Reset
Verify identity before allowing password changes
Transaction Confirmation
Confirm high-value transactions or sensitive operations