CallScaler

Calls API

List, filter, and export call data with full attribution, AI analysis, and transcriptions.

List Calls

GET /api/v1/calls

Returns a paginated list of calls for your business. Supports 20+ filters for building custom queries.

curl -H "Authorization: Bearer cs_key_..." \
  "https://callscaler.com/api/v1/calls?limit=10&status=completed&qualified=true"

Pagination Parameters

Control how many results are returned and how to page through them.

  • •limit — Results per page. Default: 50. Max: 500 with API key.
  • •offset — Skip this many results (for offset pagination).
  • •cursor — Cursor token from a previous next_cursor (for cursor pagination). Takes precedence over offset.

Date Filters

Filter calls by when they occurred or when they were last updated.

For CRM syncs, use updated_since with cursor pagination. Store the timestamp of your last sync and pass it on the next run to get only new and updated calls.

  • •start_date — Calls on or after this date (YYYY-MM-DD).
  • •end_date — Calls before this date (YYYY-MM-DD, exclusive).
  • •updated_since — Calls updated after this timestamp (ISO 8601). Use this for incremental syncing — it catches calls where transcription or AI analysis was added after the call ended.

Call Filters

Filter by call properties.

  • •status — completed, no-answer, voicemail, busy, or failed
  • •direction — inbound or outbound
  • •source — Traffic source (e.g. google, facebook, direct)
  • •number_id — Filter by tracking number UUID
  • •call_flow_id — Filter by call flow UUID
  • •number_group_id — Filter by number group UUID
  • •min_duration — Minimum duration in seconds
  • •max_duration — Maximum duration in seconds
  • •search — Search across caller number, tracking number, destination, and number name

AI & Quality Filters

Filter calls by AI analysis results. These are especially useful for building lead quality reports.

  • •min_ai_score — Minimum AI quality score (0–100)
  • •max_ai_score — Maximum AI quality score (0–100)
  • •ai_category — AI-assigned category: lead, existing_customer, spam, wrong_number, or voicemail
  • •qualified — true for qualified leads, false for unqualified
  • •has_transcription — true for calls with a transcription
  • •caller_name — Search by caller name (partial match)
  • •keyword — Filter by a spotted keyword from your keyword list

Sorting

Control the order of results.

  • •sort_by — date (default), duration, status, or ai_score
  • •sort_order — desc (default) or asc

Including Extra Fields

By default, the call list omits large text fields to keep responses fast. Use the include parameter to add them.

Without include, you can still check has_transcription: true and fetch individual transcriptions via GET /calls/:id/transcription.

  • •include=transcription — Include the full transcription text
  • •include=summary — Include the AI-generated call summary
  • •include=transcription,summary — Include both
curl -H "Authorization: Bearer cs_key_..." \
  "https://callscaler.com/api/v1/calls?limit=5&include=transcription,summary"

Response Fields

Each call in the response includes these fields:

  • •id — Unique call ID (UUID)
  • •caller_number — The caller's phone number
  • •tracking_number — Your CallScaler tracking number
  • •destination_number — Where the call was forwarded
  • •call_flow_name — Name of the call flow that handled this call
  • •direction — inbound or outbound
  • •status — completed, no-answer, voicemail, busy, or failed
  • •duration_seconds — Call duration in seconds
  • •source — Traffic source (e.g. google, direct)
  • •recording_url — URL to the call recording (null if not recorded)
  • •recording_duration — Recording length in seconds
  • •has_transcription — Whether a transcription exists
  • •ai_score — AI quality score (0–100, null if not processed)
  • •ai_category — AI category (lead, existing_customer, spam, etc.)
  • •qualified_ai — Whether AI marked the call as a qualified lead
  • •qualification_reason — Why AI qualified or disqualified the call
  • •keywords_spotted — Array of keywords detected in the call
  • •caller_name — Caller name (from CNAM lookup)
  • •value_cents — Assigned call value in cents
  • •cost_cents — Call cost in cents
  • •robo_score — Robocall likelihood score

Attribution Fields

Every call includes full marketing attribution data when available:

  • •utm_source, utm_medium, utm_campaign, utm_term, utm_content — Standard UTM parameters
  • •gclid — Google Ads click ID
  • •fbclid — Facebook click ID
  • •msclkid — Microsoft Ads click ID
  • •landing_page_url — Page the caller was on when they called
  • •referrer_url — Referring URL
  • •created_at — When the call occurred (ISO 8601)

Response Envelope

The response includes pagination metadata alongside the call data:

{
  "data": {
    "calls": [...],
    "total": 342,
    "has_more": true,
    "next_cursor": "eyJ0IjoiMjAyNi...",
    "limit": 50,
    "offset": 0
  }
}

Example: Qualified Leads from Google

Get qualified leads from Google with an AI score above 70, sorted by score:

curl -H "Authorization: Bearer cs_key_..." \
  "https://callscaler.com/api/v1/calls?source=google&qualified=true&min_ai_score=70&sort_by=ai_score&sort_order=desc&limit=20"

Example: Incremental Sync

Sync only calls that changed since your last sync. This catches new calls and calls where transcription or AI analysis was added after the initial call record was created.

# First sync — get everything
curl -H "Authorization: Bearer cs_key_..." \
  "https://callscaler.com/api/v1/calls?limit=500"

# Subsequent syncs — only updated records
curl -H "Authorization: Bearer cs_key_..." \
  "https://callscaler.com/api/v1/calls?updated_since=2026-03-30T10:00:00Z&limit=500"

Get Call Details

GET /api/v1/calls/:id

Returns the full record for a single call, including all fields listed above plus transcription and summary.

curl -H "Authorization: Bearer cs_key_..." \
  https://callscaler.com/api/v1/calls/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Batch Lookup

POST /api/v1/calls/batch

Retrieve up to 100 calls by ID in a single request. Useful for enriching data you already have.

curl -X POST -H "Authorization: Bearer cs_key_..." \
  -H "Content-Type: application/json" \
  -d '{"ids": ["uuid-1", "uuid-2", "uuid-3"]}' \
  https://callscaler.com/api/v1/calls/batch

Download Recording

GET /api/v1/calls/:id/recording

Returns the call recording as an audio stream. The response is an audio file, not JSON. Use this to download or play recordings programmatically.

Only available for calls where recording was enabled. Returns 404 if no recording exists.

# Download to a file
curl -H "Authorization: Bearer cs_key_..." \
  https://callscaler.com/api/v1/calls/UUID/recording \
  -o recording.mp3

Get Transcription

GET /api/v1/calls/:id/transcription

Returns the AI transcription for a single call.

curl -H "Authorization: Bearer cs_key_..." \
  https://callscaler.com/api/v1/calls/UUID/transcription

Export CSV

GET /api/v1/calls/export

Export calls as a CSV file. Supports the same filters as the list endpoint. The response is a CSV download, not JSON.

curl -H "Authorization: Bearer cs_key_..." \
  "https://callscaler.com/api/v1/calls/export?start_date=2026-03-01&end_date=2026-03-31" \
  -o calls.csv

Related

API Overview

API

Analytics API

API

Webhooks

API

← Previous

API Overview

Next →

Analytics API