ZensCall

ZensCall REST API

The ZensCall API allows you to programmatically manage calls, campaigns, audio files, and billing. All endpoints require authentication via Bearer token (JWT) or API key.

Base URL: https://your-domain.com/api/v1

Authentication

All API requests must include an authentication header. You can use either a JWT access token or an API key:

# Using JWT token
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# Using API key
Authorization: Bearer zc_live_YourApiKeyHere

Generate API keys from the API Keys page. JWT tokens are obtained through the /api/v1/auth/login endpoint.

Rate Limiting

API requests are rate limited to prevent abuse. Current limits:

100 requests/minute per API key for general endpoints
10 requests/minute for call creation endpoints
Rate limit headers (X-RateLimit-Remaining) are included in all responses

Code Examples

Make a Single Call

Initiate an outbound call to a Pakistani phone number using a pre-uploaded audio file.

curl -X POST https://your-domain.com/api/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "03001234567",
    "audio_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

List Calls

Retrieve a paginated list of your call records with optional status filtering.

curl -X GET "https://your-domain.com/api/v1/calls?page=1&per_page=20&status=COMPLETED" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a Campaign

Create a new campaign by uploading a CSV file containing phone numbers.

curl -X POST https://your-domain.com/api/v1/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "name=March Promotion" \
  -F "audio_id=550e8400-e29b-41d4-a716-446655440000" \
  -F "csv_file=@phone_numbers.csv" \
  -F "max_retries=3" \
  -F "concurrent_limit=10"

Get Campaign Status

Check the current status and statistics of a running campaign.

curl -X GET https://your-domain.com/api/v1/campaigns/CAMPAIGN_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Check Balance

Retrieve your current account balance and rate information.

curl -X GET https://your-domain.com/api/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Responses

All errors follow a consistent JSON format with an error code and human-readable message:

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your balance is too low to make this call. Current balance: PKR 0.00",
    "details": {}
  }
}

Common HTTP status codes: 400 (bad request), 401 (unauthorized), 403 (forbidden), 404 (not found), 422 (validation error), 429 (rate limited), 500 (server error).