Call Census API and CLI guide

CLI or API: which should I use?

Both use the same permissions, location access, retained data, limits, and results. The CLI is a simpler way to use the API; it is not a separate data source.

Before you start

1. In Call Census, open Developer → API keys.
2. Create a key and choose the locations it may access.
3. Choose its permissions:
   • locations:read lists locations and connected sources.
   • metrics:read reads reports, calls, transcripts, recordings, and import progress.
   • imports:write starts, confirms, pauses, resumes, or cancels historical imports.
4. Copy the key when it is shown. Call Census does not show the full key again.

Quick start with the CLI

Install the current beta:

npm install --global @callcensus/cli@beta

Sign in. Paste the Developer API key only when the hidden prompt appears:

cc auth login

Confirm that the key and its dataset are ready:

cc auth status
cc doctor

If you do not want a global installation, use npx --package @callcensus/cli@beta before a command.

Find calls

Without dates, a search covers the latest 30 days in the Account timezone:

cc calls list

Find calls containing part of a phone number:

cc calls list --phone 7911123

Phone matching ignores spaces and punctuation. It searches caller, destination, and tracking numbers.

Find calls classified as converted during August 2026:

cc calls list \
  --classification converted \
  --from 2026-08-01 \
  --to 2026-08-31

The first and last dates are both included. Filters can be combined.

Add --json when another application needs structured output.

Open a call, transcript, or recording

A call search returns a public ID beginning with call_. Use that ID here:

cc calls get call_0123456789abcdef01234567
cc calls transcript call_0123456789abcdef01234567
cc calls recording call_0123456789abcdef01234567

The transcript command returns the Call Census transcript by default. Use --source provider to read a retained provider transcript separately.

The recording command returns a short-lived playback link. Older audio may need to be restored first; the CLI waits briefly and tells you if you need to retry.

Read reporting totals

cc locations
cc metrics summary --from 2026-08-01 --to 2026-08-31

Metric requests may cover up to 92 days at a time and use the Account timezone. Call-level searches can cover any call history retained by the Account when explicit dates are supplied.

AI estimates and confirmed human outcomes are separate figures. Missing Google Ads data means unavailable, not zero.

Import older calls

A historical import deliberately separates planning from processing:

1. Scan: stores metadata and calculates an estimate. It does not download audio or consume Call Census processed minutes.
2. Confirm: starts the selected recording, transcription, and recommendation work.

List connected CallRail and WhatConverts sources:

cc sources

Copy a src_... ID, then scan the latest 30 days:

cc imports scan src_0123456789abcdef01234567

Or scan a custom range or all provider-supported history:

cc imports scan src_0123456789abcdef01234567 \
  --from 2026-01-01 \
  --to 2026-08-31

cc imports scan src_0123456789abcdef01234567 --all-available

Check the scan and its estimate:

cc imports list
cc imports get imp_0123456789abcdef01234567

Confirm the default selection:

cc imports confirm imp_0123456789abcdef01234567

Customers can choose to skip shorter calls to reduce usage:

cc imports confirm imp_0123456789abcdef01234567 --minimum-duration 30

This example excludes recordings shorter than 30 seconds. The import pauses before exceeding the remaining monthly processed-minute allowance or the authorised provider-request cap. Call Census does not silently raise either limit.

Manage a running import:

cc imports pause imp_0123456789abcdef01234567
cc imports resume imp_0123456789abcdef01234567
cc imports cancel imp_0123456789abcdef01234567

Cancellation is permanent, but imported metadata is preserved. Historical recommendations remain review-only and are never automatically sent to Google Ads.

Connect directly to the API

The API origin is https://api.callcensus.com. Send the Developer API key in the Authorization header:

export CALL_CENSUS_API_TOKEN='your-key-from-call-census'

curl --fail-with-body 'https://api.callcensus.com/v1/developer/status' \
  -H "Authorization: Bearer $CALL_CENSUS_API_TOKEN"

Wait until dataset.status is ready. HTTP 425 means the initial projected dataset is still being prepared.

Search calls through the API

curl --fail-with-body \
  'https://api.callcensus.com/v1/developer/calls?classification=converted&phone=7911' \
  -H "Authorization: Bearer $CALL_CENSUS_API_TOKEN"

List responses include data, total, next_cursor, applied_filters, freshness, and request_id. Repeat the same request with cursor until next_cursor is null.

Start a metadata-only historical scan

curl --fail-with-body -X POST \
  'https://api.callcensus.com/v1/developer/historical-imports' \
  -H "Authorization: Bearer $CALL_CENSUS_API_TOKEN" \
  -H 'Idempotency-Key: your-unique-value' \
  -H 'Content-Type: application/json' \
  --data '{"source_id":"src_0123456789abcdef01234567","range":{"mode":"recent"}}'

Creation, confirmation, pause, resume, and cancellation require a unique Idempotency-Key. This prevents an accidental retry from creating the same operation twice.

API endpoint map

Download the complete OpenAPI contract for request and response schemas.

Common errors

• 400: A date, filter, cursor, or request body is invalid.
• 401: The key is missing, expired, rotated, or revoked.
• 403: The key lacks permission or the request came from a blocked network.
• 404: The requested call, source, import, or location is not available to this key.
• 425: The projected dataset or recording is still preparing. Follow Retry-After.
• 429: Too many requests. Wait for Retry-After.
• 503: The service or a safe data snapshot is temporarily unavailable.

Every API error includes a request_id. Include it when contacting support.