Send OTP — API Reference

Endpoint

POST /v1/auth/send-otp

Request Body

{
  "phone": "+919876543210",
  "channel": "sms",
  "otp_length": 6,
  "expiry_seconds": 300,
  "sender_name": "MyApp",
  "locale": "en",
  "metadata": {
    "user_id": "usr_123",
    "action": "login"
  }
}

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | phone | string | ✅ | — | Phone number in E.164 format | | channel | string | ❌ | "sms" | Delivery channel: "sms", "whatsapp", "auto" | | otp_length | number | ❌ | 6 | OTP digit count: 4, 6, or 8 | | expiry_seconds | number | ❌ | 300 | OTP validity period: 60–600 | | sender_name | string | ❌ | App name | Brand name in OTP message | | locale | string | ❌ | "en" | Message language: "en", "hi" | | metadata | object | ❌ | — | Custom metadata (returned in verify response and webhooks) |

Response

Success (200)

{
  "success": true,
  "request_id": "auth_abc123def456",
  "channel": "sms",
  "phone": "+919876543210",
  "expires_at": "2026-01-15T10:35:00Z",
  "message": "OTP sent successfully"
}

Error (4xx)

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many OTP requests for this number. Try again in 120 seconds.",
    "retry_after": 120
  }
}

Error Codes

| Code | HTTP | Description | |------|------|-------------| | INVALID_PHONE | 400 | Invalid phone number format | | UNSUPPORTED_COUNTRY | 400 | Phone number’s country not supported | | RATE_LIMITED | 429 | Too many OTP requests (5/10 min per number) | | CHANNEL_UNAVAILABLE | 400 | Selected channel not available for this number | | INSUFFICIENT_CREDITS | 402 | Not enough SMS credits |

Channel Behavior

SMS Channel ("sms")

Sends OTP via SMS using StartMessaging’s pre-registered non-DLT route. No DLT registration needed.

Message format:

123456 is your MyApp verification code. Valid for 5 minutes.

WhatsApp Channel ("whatsapp")

Sends OTP via WhatsApp using an approved authentication template. Free for first 1,000/month.

Auto Channel ("auto")

1. Checks if the phone number is on WhatsApp
2. If yes → sends via WhatsApp (free)
3. If no → falls back to SMS (₹0.25)

The response indicates which channel was used:

{
  "success": true,
  "request_id": "auth_abc123",
  "channel": "whatsapp",
  "fallback_used": false
}

Rate Limiting

| Limit | Value | Configurable | |-------|-------|-------------| | Per phone number | 5 requests / 10 minutes | Enterprise only | | Per API key | 100 requests / second | Enterprise only | | Global daily | Based on plan | ✅ |

FAQ

Can I customize the OTP message text? The message format is standardized for security and deliverability. You can customize the sender_name parameter to show your brand name.

Does the auto channel add latency? The WhatsApp number lookup adds ~200ms. If speed is critical, specify "sms" directly.