CallRail

CallRail

CallRail is a call tracking and analytics platform for marketers and agencies. It attributes inbound phone calls, texts, and form submissions to the marketing sources that drove them — enabling ROI analysis across paid, organic, offline, and referral channels.

Entity Hierarchy

• Account — top-level container. Discover your account ID first, as every other endpoint requires it in the URL path.
• Company — a business entity within an account. Tracking numbers, integrations, tags, and reports are scoped to a company. Agencies typically create one company per client.
• Tracker — a phone number that routes calls and (optionally) SMS to the business.
  • Source tracker: a single number tied to one marketing channel (billboard, Google Ads, etc.).
  • Session tracker: a pool of numbers served to website visitors for per-session attribution.
• Call — an inbound or outbound phone call with metadata (caller info, duration, recording, attribution).
• Conversation / SMS Thread — a text-message thread between a customer and a tracking number. SMS threads provide notes, tags, value, and lead qualification per thread.
• Form Submission — a website form capture with customer data, attribution source, and marketing campaign info. Forms can be summarized by source, campaign, or company.
• Lead — a person identified from calls, texts, or forms. Lead timelines show every interaction and attribution milestone (first touch, lead creation, qualification, last touch).
• Tag — a label applied to calls, texts, or forms for categorization. Tags can be company-level or account-wide.
• Notification — an alert configuration that sends email, desktop, or push notifications when calls or texts arrive.
• Summary Email — a periodic report subscription (daily/weekly/monthly) with configurable sections (statistics, top sources, keywords, call log).
• Message Flow — an automated SMS response workflow triggered by inbound texts, with schedule-based branching, auto-replies, and tagging steps.
• Outbound Caller ID — an external phone number registered and verified for use as caller ID on outbound calls.
• User — a person with access to the account (admin, manager, or reporting role).

Pagination

All collection endpoints use offset pagination with page (1-indexed) and per_page (default 100, max 250). The calls endpoint also supports relative pagination for large datasets.

Date Filtering

Call and conversation endpoints accept date_range presets (recent, today, last_7_days, this_month, etc.) or explicit start_date/end_date in ISO 8601 format. Data retention is 25 months — requests outside that window are rejected.

Field Selection

Many endpoints return a default field set. Pass a fields parameter (comma-separated) to request additional data like source, tags, transcription, call_summary, milestones, and keywords_spotted on calls.

Key Workflows

• Discover structure: get accounts → get companies → get trackers to understand the tracking setup.
• Analyze performance: get call summary grouped by source, campaign, or company to see which channels convert. Use time series for trend charts over date ranges.
• Audit calls: get calls with filters (date range, call type, lead status) and extra fields (transcription, tags, milestones) for quality review. View page views for a call to see the visitor's website journey before calling.
• Manage tags: create, update, or delete tags, then apply them to calls via update call.
• Outbound engagement: create outbound calls to connect a business agent with a customer, or send text messages.
• Provisioning: create/update companies, trackers (source or session), and users to set up new clients or campaigns.
• Form tracking: list and create form submissions, update with tags/notes/lead status, and summarize form data grouped by source or campaign.
• Lead intelligence: list all leads and retrieve full lead timelines with every interaction (calls, texts, forms, chats) and attribution milestones.
• SMS management: list SMS threads, view full message history, update thread notes/tags/value. Build message flows for automated text responses with schedule-based branching.
• Alerts: create, update, and delete notification rules for email, push, or desktop alerts on calls and texts.
• Reporting: manage summary email subscriptions (daily/weekly/monthly) with configurable report sections.
• Outbound caller ID: register and verify external phone numbers for use as caller ID on outbound calls.

Rate Limits

1,000 requests/hour, 10,000 requests/day for general API calls. SMS: 150/hour, 1,000/day. Outbound calls: 100/hour, 2,000/day. HTTP 429 is returned when limits are hit.

Gotchas

• Tracker creation requires both a call_flow object and a source configuration — omitting either causes a 400 error.
• Session tracker pool_size can only be increased, never decreased.
• Disabling a company deactivates all its tracking numbers and the swap.js script.
• The last active company in an account cannot be disabled.
• Text messages require 10DLC compliance registration. The content field is limited to 140 characters.
• Marking a call as spam=true is irreversible via API.
• IDs are string-prefixed (ACC, COM, TRK, CAL, USR, PER) — always pass them as strings.