API Overview
Authentication, role requirements, rate limits, pagination, and response conventions for the CallScaler REST API.
What the API Covers
The CallScaler API gives you programmatic access to calls, analytics, numbers, call flows, voicemails, SMS, forms, webhooks, and billing-related resources.
Use it to sync call data to your CRM, build custom reporting, and automate operational workflows.
Quick Start
1. Open Settings → API Keys.
2. Click Create API Key and enter a descriptive name (for example, "HubSpot Sync").
3. Copy the key immediately. The full secret is shown once.
4. Make a test request:
curl -H "Authorization: Bearer cs_key_your_key_here" \
https://callscaler.com/api/v1/calls?limit=5Base URL
All API requests use the v1 base URL:
https://callscaler.com/api/v1/Authentication
Send your API key in the Authorization header on every request:
- •Each key is scoped to a single business
- •You can create up to 10 active keys per business
- •Only users with the admin or owner role can create or revoke keys
- •Keys are created in Settings → API Keys
Authorization: Bearer cs_key_your_key_hereBusiness Scope and Roles
API key requests run in the business tied to that key. Data from other businesses in your account is not returned.
Read endpoints are available to Viewer and above, but API key management endpoints require Admin or Owner permissions.
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
.envfiles locally and secrets managers in production - •Rotate keys periodically, revoke old ones in Settings → API Keys
- •Each key shows a prefix (for example
cs_key_a1b2c3d4) so you can identify keys safely - •Revoked keys stop working immediately
Response Format
Most successful responses are wrapped in a data envelope. Error responses include an error field and a human-readable message.
A few legacy endpoints may return a top-level payload without a data wrapper. Build your client to handle both shapes safely.
// Success (200)
{
"data": {
"calls": [...],
"total": 342,
"has_more": true
}
}
// Error (4xx / 5xx)
{
"error": {
"code": "401",
"message": "unauthorized"
}
}Pagination: Offset
List endpoints support limit and offset for simple pagination.
limit controls items per page (default 50, max 500 with an API key). offset skips that many results. The response includes a total field so you know how many items exist.
Offset pagination is simple but can slow down at high offsets. For larger sync jobs, use cursor pagination.
# Get items 51-100
curl -H "Authorization: Bearer cs_key_..." \
"https://callscaler.com/api/v1/calls?limit=50&offset=50"Pagination: Cursor
For reliable pagination through large datasets, use cursor-based pagination. Pass the next_cursor from the previous response as the cursor parameter.
Cursor pagination is stable, new calls arriving between requests will not cause skipped rows.
Keep paginating until has_more is false.
# First request
curl -H "Authorization: Bearer cs_key_..." \
"https://callscaler.com/api/v1/calls?limit=100"
# Response includes next_cursor
{
"data": {
"calls": [...],
"has_more": true,
"next_cursor": "eyJ0IjoiMjAyNi0wMy0xNVQxMDozMDowMFoiLCJpIjoiYWJjLTEyMyJ9"
}
}
# Next page
curl -H "Authorization: Bearer cs_key_..." \
"https://callscaler.com/api/v1/calls?limit=100&cursor=eyJ0IjoiMjAyNi0wMy0xNVQxMDozMDowMFoiLCJpIjoiYWJjLTEyMyJ9"Rate Limits
API-key requests are rate-limited to 60 requests per minute per business. All keys for the same business share one bucket.
Responses include rate-limit headers:
Session (cookie) requests from the web app are not counted against this API-key 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 resetsRate Limit Exceeded
If you exceed the limit, the API returns 429 with a Retry-After header and a retry_after field in the body. Wait that many 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 role permissions)
- •404 — Resource not found
- •429 — Rate limit exceeded
- •500 — Internal server error
Conventions
Patterns used across endpoints:
- •All timestamps are ISO 8601 in UTC (for example
2026-03-23T14:30:00Z) - •IDs are UUIDs
- •Phone numbers use E.164 format (for example
+15735551234) - •Money values are in cents
- •Optional fields may return
null - •Date filters use
YYYY-MM-DD
On this page