API Overview

Authenticate, understand rate limits, and start using the CallScaler REST API.

Overview

The CallScaler API lets you read call data, manage numbers, and control call flows programmatically. Use it to build custom dashboards, sync calls to your CRM, or automate number provisioning.

The API is RESTful, returns JSON, and uses API key authentication.

Quick Start

Get up and running in under a minute:

1. Go to Settings > API Keys in your dashboard
2. Click Create API Key and give it a name
3. Copy the key (you'll only see it once)
4. Make your first request:

curl -H "Authorization: Bearer cs_key_your_key_here" \
  https://callscaler.com/api/v1/numbers

Base URL

All API requests use the v1 base URL:

https://callscaler.com/api/v1/

Authentication

Include your API key in the `Authorization` header of every request. Keys are created in Settings > API Keys.

Each key is scoped to a single business. You can create up to 10 active keys per business. Only admins can create or revoke keys.

Authorization: Bearer cs_key_your_key_here

Key Security

Your API key grants full read/write access to your business data. Treat it like a password.

•Store keys in environment variables, never in source code
•Use `.env` files locally and secrets managers in production
•Rotate keys periodically. Revoke old ones in Settings > API Keys.
•Each key shows a prefix (e.g. `cs_key_a1b2c3d4`) so you can identify which key is which
•Revoked keys stop working immediately with no cache delay
•If you suspect a key was compromised, revoke it and create a new one

Response Format

Successful responses wrap data in a `data` field. Errors use a structured `error` object with a code and human-readable message.

// Success
{
  "data": {
    "numbers": [...],
    "total": 42
  }
}

// Error
{
  "error": {
    "code": "401",
    "message": "Invalid API key"
  }
}

Pagination

List endpoints return all results for your business. For endpoints that support pagination, use `page` and `per_page` query parameters:

- `page` starts at 1 (default)
- `per_page` controls items per page (default varies by endpoint)
- Response includes a `total` field so you know how many items exist

# Get page 2 with 25 items per page
curl -H "Authorization: Bearer cs_key_..." \
  "https://callscaler.com/api/v1/calls?page=2&per_page=25"

# Response
{
  "data": {
    "calls": [...],
    "total": 342
  }
}

Rate Limits

API requests are rate-limited to 60 requests per minute per business. All keys for the same business share this limit.

Every response includes rate limit headers so you can track your usage and back off before hitting the limit:

X-RateLimit-Limit: 60          # Your limit per minute
X-RateLimit-Remaining: 54      # Requests left in this window
X-RateLimit-Reset: 1679616000  # Unix timestamp when the window resets

Rate Limit Exceeded

If you exceed the limit, you'll get a `429` response. Wait for the `retry_after` seconds before retrying:

// HTTP 429 Too Many Requests
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Limit: 60/min. Try again in 12 seconds.",
  "retry_after": 12
}

HTTP Status Codes

The API uses standard HTTP status codes:

•200 Request succeeded
•400 Bad request (missing or invalid parameters)
•401 Unauthorized (invalid or missing API key)
•403 Forbidden (insufficient permissions)
•404 Resource not found
•429 Rate limit exceeded
•500 Internal server error

Common Patterns

A few patterns you'll see across all endpoints:

•All timestamps are ISO 8601 in UTC (e.g. `2026-03-23T14:30:00Z`)
•IDs are UUIDs (e.g. `a1b2c3d4-e5f6-7890-abcd-ef1234567890`)
•Phone numbers include the country code (e.g. `+15735551234`)
•Money values are in cents (e.g. `balance_cents: 2500` = $25.00)
•Boolean filters accept `true` or `false` as query parameters

API Endpoints

API

Webhooks

API

← Previous

Settings