🚀 Quick Start

Basic OTP Request

curl -X POST "https://api.airtexts.com/otp/send" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "appid": "your_app_id",
    "recipient": "+5511999888777",
    "channel": "sms",
    "from": "YourApp"
  }'

WhatsApp OTP Request

curl -X POST "https://api.airtexts.com/otp/send" \
  -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "appid": "your_app_id",
    "recipient": "+5511999888777",
    "channel": "whatsapp",
    "from": "YourCompany"
  }'

📋 Request Parameters

Required Parameters

Parameter	Type	Description	Example
`appid`	string	Application ID for API identification	`"myapp_123"`
`recipient`	string	Phone number in international format	`"+258845888195"`

Optional Parameters

Parameter	Type	Description	Default	Example
`channel`	string	Delivery channel: `sms` or `whatsapp`	`"sms"`	`"whatsapp"`
`from`	string	Sender ID (also accepts `sender`)	`"OTP"`	`"YourApp"`
`otp_length`	integer	OTP code length (4-8 digits)	`6`	`4`
`templateId`	integer	Custom template ID	`null`	`123`
`lang`	string	Language code for template	`"en"`	`"pt"`

Alternative Parameter Names

recipient can also be sent as phone or to
from can also be sent as sender
otp_code can also be sent as code

📱 Channel Options

SMS Channel

Fast delivery - Usually delivered within seconds
Universal support - Works on all mobile devices
Cost effective - Lower cost per message
High reliability - 99%+ delivery rate

WhatsApp Channel

Rich messaging - Support for formatting and emojis
Higher engagement - Better user interaction
Free for recipients - No SMS charges for users
Business presence - Builds brand recognition

Template Variables

Template messages support these variables:

{{otp}} or {{code}} - The OTP code
{{app_name}} or {{appname}} - Application name
{{expires_at}} or {{expires_time}} - Expiration time (HH:MM)
{{expires_full}} - Full expiration datetime
{{expiry_minutes}} - Minutes until expiration
{{recipient}} or {{phone}} - Recipient phone number
{{channel}} - Delivery channel
{{lang}} - Language code
Custom variables from custom_vars object

✅ Success Response

{
  "status": "success",
  "message": "OTP sent successfully",
  "verification_id": "otp_67890abcdef12345",
  "recipient": "+5511999888777",
  "channel": "sms",
  "expires_at": "2025-08-19T20:15:00Z"
}

Response Fields

verification_id - Unique ID for this OTP (use for verification)
recipient - Phone number that received the OTP
channel - Delivery channel used (sms/whatsapp)
expires_at - When the OTP expires (ISO 8601 format)

❌ Error Responses

Missing App ID

{
  "error": "appid is required"
}

Invalid Phone Number

{
  "error": "Invalid phone number format"
}

Rate Limited

{
  "error": "Rate limit exceeded. Try again in 60 seconds",
  "retry_after": 60
}

Insufficient Balance

{
  "error": "Insufficient balance to send OTP",
  "balance": 2.50,
  "cost": 0.05
}

🔒 Authentication Examples

API Key Headers

curl -X POST "https://api.airtexts.com/otp/send" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{"appid": "your_app_id", "recipient": "+5511999888777"}'

Basic Authentication

curl -X POST "https://api.airtexts.com/otp/send" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -H "Content-Type: application/json" \
  -d '{"appid": "your_app_id", "recipient": "+258845888195"}'

Bearer Token

curl -X POST "https://api.airtexts.com/otp/send" \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{"appid": "your_app_id", "recipient": "+5511999888777"}'

Per Company Limits

20 OTPs per minute - Company-wide rate limit
Burst protection - Automatic throttling during high usage

Failed Attempts

3 failed verification attempts in 30 minutes - Temporary block

🎯 Implementation Examples

PHP Example

<?php
$data = [
    'appid' => 'your_app_id',
    'recipient' => '+5511999888777',
    'channel' => 'sms',
    'from' => 'YourApp'
];

$ch = curl_init('https://api.airtexts.com/otp/send');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: your_api_key',
    'X-API-Secret: your_api_secret',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$result = json_decode($response, true);
curl_close($ch);

if ($result['status'] === 'success') {
    echo "OTP sent! Verification ID: " . $result['verification_id'];
} else {
    echo "Error: " . $result['error'];
}
?>

💡 Best Practices

Security

Never log OTP codes - Keep verification codes out of logs
Use HTTPS only - Always use secure connections
Validate phone numbers - Check format before sending
Set appropriate expiration - 5-15 minutes recommended

User Experience

Clear instructions - Tell users what to expect
Retry mechanism - Allow users to request new codes
Multiple channels - Offer SMS and WhatsApp options
Error handling - Provide helpful error messages

Performance

Cache verification IDs - Store for verification process
Handle rate limits - Implement exponential backoff
Monitor delivery - Track success rates
Use webhooks - Get real-time delivery updates

🔄 Next Steps

After sending an OTP, you'll typically want to:

Store the verification_id - Save it for the verification step
Show user interface - Display code input form
Implement verification - Use /otp/verify endpoint
Handle expiration - Allow resending via /otp/resend
Track analytics - Monitor success rates and delivery