Start Verification

Endpoint

POST /v1/verify/start

Headers

Header	Required	Description
Authorization	yes	Bearer token: `Bearer tvx_sk_live_...`
X-Tenant-ID	yes	Your tenant ID: `acc_...`
Content-Type	yes	Must be `application/json`

Request body

Parameter	Type	Required	Default	Description
to	string	yes	—	Phone number in E.164 format (e.g., `+919876543210`) or email address
channel	string	yes	—	Delivery channel: `sms`, `voice`, `whatsapp`, or `email`
code_length	integer	no	6	OTP code length (4–8 digits)
locale	string	no	en	Language code for voice/SMS templates (e.g., `en`, `es`, `fr`)
custom_message	string	no	—	Custom message template (must include the `code` placeholder)
app_name	string	no	—	Application name for default message templates

Response

Success (200 OK)

{
  "data": {
    "verification_id": "ver_abc123",
    "to": "+919876543210",
    "channel": "sms",
    "status": "pending",
    "created_at": "2026-04-09T10:00:00Z",
    "expires_at": "2026-04-09T10:10:00Z"
  }
}

Response fields

Field	Type	Description
verification_id	string	Unique identifier for this verification (use in check endpoint)
to	string	The phone number or email that received the code
channel	string	The delivery channel used
status	string	Current status: `pending`
created_at	string	ISO 8601 timestamp when verification was created
expires_at	string	ISO 8601 timestamp when code expires (10 minutes from creation)

Examples

Send SMS OTP

curl -X POST https://api.tryvox.io/v1/verify/start \
  -H "Authorization: Bearer tvx_sk_live_..." \
  -H "X-Tenant-ID: acc_123" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "channel": "sms",
    "app_name": "MyApp"
  }'

Send voice call with custom code length

curl -X POST https://api.tryvox.io/v1/verify/start \
  -H "Authorization: Bearer tvx_sk_live_..." \
  -H "X-Tenant-ID: acc_123" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "channel": "voice",
    "code_length": 8,
    "locale": "en"
  }'

Send WhatsApp with custom message

curl -X POST https://api.tryvox.io/v1/verify/start \
  -H "Authorization: Bearer tvx_sk_live_..." \
  -H "X-Tenant-ID: acc_123" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "channel": "whatsapp",
    "custom_message": "Your verification code for MyApp is: {{code}}. Valid for 10 minutes.",
    "code_length": 6
  }'

Send email OTP

curl -X POST https://api.tryvox.io/v1/verify/start \
  -H "Authorization: Bearer tvx_sk_live_..." \
  -H "X-Tenant-ID: acc_123" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "channel": "email",
    "app_name": "MyApp"
  }'

Channel details

SMS

Sends a text message containing the OTP code to the specified phone number. Uses default template or custom message if provided.

Default template: Your <app_name> verification code is: <code>

Voice

Makes an outbound phone call to the specified number and speaks the OTP code using text-to-speech. The code is repeated twice for clarity.

Behavior: The call will speak each digit individually (e.g., "1, 2, 3, 4, 5, 6") followed by the complete code repeated once.

Sends a WhatsApp message containing the OTP code. Requires WhatsApp Business API integration.

Note: The recipient phone number must have WhatsApp installed and must have previously opted in to receive messages from your business.

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invalid phone number format. Use E.164 format (e.g., +919876543210)"
  }
}

RATE_LIMITED (429)

Too many OTP requests for this phone number or email.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Maximum 5 OTP requests per hour per phone number."
  }
}

INVALID_CHANNEL (400)

Unsupported channel specified.

{
  "error": {
    "code": "INVALID_CHANNEL",
    "message": "Channel must be one of: sms, voice, whatsapp, email"
  }
}

Rate limits

5 OTP requests per phone number/email per hour
10 concurrent verifications per tenant

Rate limits reset on a rolling window basis.

Best practices

Store the verification_id: You'll need it to check the code and query status
Handle rate limits gracefully: Show appropriate error messages to users
Use appropriate code length: 6 digits is recommended for most use cases
Localize messages: Set locale to match your user's language preference
Monitor expiration: Codes expire after 10 minutes - consider showing a countdown timer
Test with real numbers: Use test mode credentials for development testing