List CallRail accounts accessible to this API key.

Most users have one account per agency. The returned id is used as account_id in all other tools (auto-resolved if omitted).

List companies (client businesses) under a CallRail account.

Args: account_id: CallRail account ID. Auto-resolves if omitted. per_page: Page size (max 250). status: Filter by status. Defaults to None (returns all). Common values: 'active' (excludes disabled/soft-deleted), 'disabled'.

List tracking phone numbers (trackers). Each tracker maps a pool of phone numbers to a traffic source (Google Ads, Organic, Direct, etc.).

Args: account_id: Auto-resolves if omitted. company_id: Filter to one company. per_page: Page size (max 250). page: 1-indexed. status: Filter by status. Defaults to None (returns all, including soft-deleted/disabled). Common values: 'active', 'disabled'.

Get full detail for a specific tracker.

Args: tracker_id: 'TRK...' id. account_id: Auto-resolves if omitted.

⚠️ Create a new tracking phone number (tracker). THIS COSTS MONEY.

CallRail charges per provisioned number — typical pricing as of 2026:

• Local numbers: ~$3/month each

• Toll-free (8XX): ~$3-5/month each

• Session pools: charged per number × pool_size (so pool_size=8 = 8x)

• Plus per-minute usage (~$0.05/min on answered calls)

Most plans bundle 5–10 numbers; provisioning beyond your bundle adds overage charges. Some plans prorate partial-month usage, so creating and immediately deleting can still produce a small charge depending on your contract.

You must pass confirm_billing=True to actually create. This guards against accidental provisioning when an AI is exploring tools.

Args: name: Display name for the tracker (e.g. "Google Ads Call Extension"). company_id: 'COM...' id of the company this tracker belongs to. destination_number: Where calls forward to, e.g. "+14129548337". confirm_billing: REQUIRED — set True to acknowledge the per-number cost. Returns an error envelope if False (default). type: 'source' (single number tied to one traffic source) or 'session' (DNI pool that swaps numbers per visitor). Default 'source'. source_type: For type='source', which traffic source. Must be one of: 'all', 'direct', 'offline', 'google_my_business', 'google_ad_extension' (this is what Google Ads call-extension uses). Ignored for type='session' (use 'all'). area_code: 3-digit area code to provision the local number from (e.g. '412'). Ignored if toll_free=True. toll_free: If True, provision an 8XX toll-free number instead. pool_size: For type='session' only — how many numbers in the DNI pool (CallRail's "pool_size" required field). Typical 4-10. Each pool number is billed separately. whisper_message: Spoken to the agent answering the call so they know which marketing source it came from. recording_enabled: Record the call audio. Default True. greeting_text: Optional automated greeting text-to-speech. sms_enabled: Allow this number to receive/send SMS. Default True. account_id: Auto-resolves if omitted.

Returns the created tracker including its newly-provisioned tracking_numbers.

Update a tracker's mutable settings: name, destination, whisper, greeting, SMS.

Args: tracker_id: 'TRK...' id. account_id: Auto-resolves if omitted. name: New display name. destination_number: Where calls forward (e.g. "+14129548337"). Updates the call_flow's destination too. whisper_message: New whisper text. greeting_text: New automated greeting. If supplied, you must also supply destination_number — CallRail's PUT /trackers replaces the entire call_flow object, so updating only greeting_text would silently zero out the destination, breaking the tracker. sms_enabled: Toggle SMS on/off.

Field-level rules: - name, destination_number, whisper_message, greeting_text must be non-empty strings if provided. Pass None (the default) to leave a field unchanged.

NOTE: Setting status via this PUT is silently ignored by CallRail. To disable a tracker, use delete_tracker(tracker_id) (soft-delete / disabled, keeps history). To permanently remove, contact CallRail support.

Delete (disable) a tracker. Soft-removes it from active trackers; the tracker keeps its call history but stops receiving new calls. The underlying phone number is released.

Args: tracker_id: 'TRK...' id. account_id: Auto-resolves if omitted.

Returns: An object with deleted: True, tracker_id, and response (CallRail's body, which on success contains the disabled tracker record including disabled_at timestamp). Empty object if CallRail returned 204.

List calls. Paginated. Filterable by company, date window, source, answered status.

Args: account_id: Auto-resolves if omitted. company_id: Filter to one company. Omit for all companies. days: Lookback in days (default 7). Ignored if start_date provided. start_date: 'YYYY-MM-DD'. end_date: 'YYYY-MM-DD' (defaults to today). source: Filter (e.g. 'google_paid', 'google_organic', 'direct', 'bing_paid'). answered: 'true' or 'false'. per_page: Max 250. page: 1-indexed. fields: Comma-separated additional fields to include, e.g. 'company_name,source_name,keywords,landing_page_url,device, first_call,value,tags,note,gclid,fbclid,utm_source,utm_medium, utm_campaign,utm_content,utm_term,referrer_domain'.

Get full detail for a specific call.

Args: call_id: CallRail call id (prefix 'CAL...'). account_id: Auto-resolves if omitted. fields: Comma-separated extra fields (see list_calls for common names).

Summarize calls over a date window.

Returns counts: total, answered/missed, first-time/repeat callers, total duration, and breakdowns by source and source_name. Useful for weekly/monthly rollups without pulling every call into context.

Note: requires days>=1 or an explicit start_date — without a window this would paginate the entire account history (potentially 50+ pages of 250 calls each), which is rarely what callers want.

List form submissions captured by CallRail's Form Tracking.

List SMS/text message conversations.

List users on the account.

Get the recording URL for a call (if recording is enabled on the company).

Get the AI transcript for a call (requires CallRail Conversation Intelligence).

Find calls from/to a specific phone number. Matches on the last 10 digits of the stored customer_phone_number so any format works.

Args: phone_number: Any format — will be normalized to digits-only. Must contain at least 7 digits to avoid false positives. account_id: Auto-resolves. company_id: Optional company filter. days: Lookback window (default 90).

Update an existing call: notes, tags, spam flag, customer name, lead status.

Args: call_id: 'CAL...' id of the call to update. account_id: Auto-resolves if omitted. note: Replace the call's note text. tags: REPLACE the call's tag list with this set of tag names. (Use add_call_tags/remove_call_tags for additive changes.) spam: True to mark as spam, False to unmark. Note: spam-flagged calls are HIDDEN from default GET endpoints — re-reads will 404. Tag the call BEFORE flagging spam if you need both. customer_name: Override the auto-detected caller name. lead_status: e.g. 'good_lead', 'not_a_lead', 'unknown'.

Note: value is intentionally NOT exposed here. CallRail's API returns a 500 server error when value is included in the PUT body to /calls (verified via live testing 2026-04-24). It IS supported on form submissions — see update_form_submission.

Empty-string fields (e.g. note="") are rejected because CallRail interprets them as "clear this field" — almost always a mistake. To intentionally clear a field, set it to None and use a separate UI operation, or contact CallRail support.

Length caps (rejected pre-network): - note: 4000 chars - customer_name: 200 chars - tags: 100 entries max

Append tags to a call without replacing existing ones.

Empty/whitespace-only tag names are silently filtered out so that a request like add_call_tags(['', 'lead']) won't 400 — only 'lead' is sent. Returns an error if no valid tags remain after cleaning.

Remove specific tags from a call (case-sensitive on tag name).

Idempotent — removing a tag that isn't attached succeeds silently. Empty/whitespace-only entries in the input list are ignored.

Update an existing form submission: notes, tags, value, spam, lead status.

Args: submission_id: CallRail form-submission id (prefix 'FOR...'). account_id: Auto-resolves if omitted. note, tags, value, spam, lead_status: same semantics as update_call.

Empty-string fields (e.g. note="") are rejected to prevent accidental field-clearing — see update_call docstring.

Length caps (rejected pre-network): - note: 4000 chars - tags: 100 entries max

List all tags in the account, or filtered to one company.

Create a new tag scoped to one company.

Args: name: Tag display name. company_id: Required — tags are per-company in CallRail. account_id: Auto-resolves if omitted. color: One of the 10 CallRail-supported colors: 'red1', 'red2', 'orange1', 'yellow1', 'green1', 'blue1', 'purple1', 'pink1', 'gray1', 'gray2'. If omitted, CallRail defaults to 'gray1'.

Rename or recolor a tag.

Args: tag_id: Numeric tag id. account_id: Auto-resolves if omitted. name: New display name. color: One of: 'red1', 'red2', 'orange1', 'yellow1', 'green1', 'blue1', 'purple1', 'pink1', 'gray1', 'gray2'.

Delete a tag. Removes it from any calls/form submissions it was on.

Per-company cost-attribution summary for the current cycle.

Aggregates active trackers + per-company call minutes and projects what each client is contributing to the agency's CallRail bill. Useful for:

• Deciding which client to renegotiate / upsell / drop

• Sanity-checking the upcoming invoice

• Quarterly reviews

Pricing assumes Call Tracking Starter ($50 base + 5 numbers + 250 mins bundled; $3/local number, $5/toll-free number, $0.05/local minute, $0.08/toll-free minute over bundle). Edit PRICING_* constants in server.py if you're on a different plan.

Args: account_id: Auto-resolves if omitted. days: Lookback window in days (default 30 = roughly one cycle). Ignored if start_date provided. start_date: 'YYYY-MM-DD'. end_date: 'YYYY-MM-DD' (defaults to today).

Returns: - agency: plan + totals + bundle utilization + cycle estimate - by_company[]: each company's minutes, active numbers, cost share (sorted by cost-share descending) - biggest_cost_driver: name of top company - partial_failures[]: per-company API errors. Each entry carries partial_calls_before_failure, partial_minutes_before_failure, partial_local_numbers, partial_tollfree_numbers so an under- reporting agency_total is observable, not silent. - notes: caveats about the cost model (toll-free minute pricing not yet differentiated; SMS not included).

Cost shares sum exactly to agency.estimated_cycle_total via largest- remainder rounding.

Audit whether a specific call is/was eligible to count as a Google Ads conversion. Useful for "where did my conversion go" debugging.

Checks:

1. Did the call have a gclid? (Required for CallRail to upload to Google Ads as a UPLOAD_CLICKS Phone Call conversion.)

2. Was the call answered? (Most integrations skip unanswered.)

3. Did duration meet Google Ads' minimum? (Default 60s; configurable per conversion action in Google Ads UI.)

4. Is the call from a Google source? Detection uses CallRail's internal source slug (e.g. google_paid, google_my_business)

   • presence of gclid — NOT the user-editable source_name display string (which can mislead, e.g. "Bing Ads (Google legacy import)" would substring-match as Google but is clearly Bing).

Args: call_id: 'CAL...' id. google_ads_min_duration_seconds: Threshold to check duration against. Defaults to 60 (Google's UI default). Override if you've lowered it on a specific conversion action. account_id: Auto-resolves if omitted.

Returns: Verdict + each criterion's pass/fail + suggested remediation when eligibility fails.

Compare current N-day window vs the previous N-day window.

Returns per-company minute / call deltas + agency-wide totals. Useful for "is Malick growing?", "did we lose Stewart traffic this month?", catching invoice surprises before they hit.

Args: days: Window length on each side (default 30 = roughly one cycle). Cap: 365 (don't ask for "5-year delta" — likely a typo). account_id: Auto-resolves if omitted.

Returns: A breakdown showing current vs previous totals, % deltas, and per-company growth/shrink. Sorted by absolute minute change.

Implementation: pulls call data for both windows in one tool call. Tracker counts use current-snapshot for both periods (CallRail doesn't expose historical tracker counts) — only minute deltas reflect actual period-over-period change.

Apply the same update to every call matching a filter.

Useful for: "tag every Bing call this month as low-priority", "mark all <30s unanswered calls from this number as spam", "add a note to every call from a specific landing page". Replaces dozens of sequential update_call invocations with one tool call.

Safety: dry_run=True by default — returns a preview of which calls WOULD be updated without actually writing. Pass dry_run=False to commit. Hard cap of 500 calls per invocation to prevent runaway bulk operations.

Args: company_id, days, source, answered: filter — same semantics as list_calls. At least one must be provided to avoid "update everything ever". set_tags_add: tag names to ADD to each matched call (preserves existing tags). Mutually compatible with other set_* fields. set_note: note text to set on each matched call (replaces existing). set_lead_status: e.g. 'good_lead', 'not_a_lead'. set_spam: True to mark spam, False to unmark. dry_run: If True (default), return preview only. False = commit. account_id: Auto-resolves if omitted.

Returns: - If dry_run: {"matched": N, "would_update": [...]} - Else: {"matched": N, "updated": M, "failed": [...]} per call

Performance note: when set_tags_add is used, the commit phase issues 1 extra GET per call to fetch fresh tags before merging (race protection against concurrent tag writes). For a max bulk of 500 calls, this is ~2× the latency vs other set_* fields. Other update fields (note, lead_status, spam) skip the extra GET.

Heuristically identify likely-spam calls and (optionally) tag them.

Spam scoring (additive): +2 if duration < 10 seconds +1 if not answered +1 if first_call AND duration < 30 seconds +1 if same caller appears >=3 times in window (likely auto-dialer) A call scoring >= 3 is flagged as likely spam.

Args: company_id: Restrict to one company (recommended). days: Lookback window (1-90; 90 is hard-capped to avoid memory blowup on high-volume clients — full call list is materialized for scoring before truncating the response). auto_tag: If True, ADD tag_name to each likely-spam call after the scan. Default False (preview only). Note: we deliberately do NOT mark calls as spam=True automatically — CallRail HIDES spam-flagged calls from default GET endpoints, so self-reviewing them later becomes painful. Tag first, manually spam-flag if confirmed. tag_name: The tag to add when auto_tag=True. Default 'auto_detected_spam'. Auto-creates the tag at company level if it doesn't exist (CallRail's behavior). account_id: Auto-resolves if omitted.

Returns: - score breakdown by call - histogram of caller phone numbers (so you can spot a single dialer hammering you) - if auto_tag: count tagged + failures

Get full detail for one company.

Args: company_id: 'COM...' id. account_id: Auto-resolves if omitted.

Note: Returns the disabled record (with status: "disabled", disabled_at timestamp) for soft-deleted companies — NOT 404. Check the status field if you need to distinguish.

Create a new company (client) under the account.

Useful for new-client onboarding. CallRail bills per number, not per company — creating a company is free; provisioning trackers under it is what costs money (see create_tracker).

Args: name: Display name (e.g. "Smith & Co Roofing"). Required. time_zone: IANA TZ. Default 'America/New_York' (matches your existing companies). Common: 'America/Los_Angeles', 'America/Chicago', 'America/Denver'. callscore_enabled: CallRail CallScore™ AI scoring (paid feature). Pass None (default) to inherit account-level default. lead_scoring_enabled: Manual lead-status workflow. None=inherit. swap_exclude_jquery: Skip jQuery-driven phone swaps. None=inherit. callscribe_enabled: Conversation Intelligence transcripts (paid). None=inherit. keyword_spotting_enabled: Real-time keyword detection in calls. None=inherit. form_capture: Enable CallRail Form Tracking. None=inherit. account_id: Auto-resolves if omitted.

Note: Optional booleans default to None (inherit account-level defaults) rather than False. Sending False for a paid feature on an account that has it enabled would actively DISABLE it — almost never the caller's intent on a fresh-create.

Update mutable settings on a company. Pass None to leave unchanged.

Empty-string name / time_zone are rejected (almost always a mistake).

Soft-delete a company. Status flips to 'disabled', records retained.

Mirrors delete_tracker semantics: CallRail's DELETE on companies is a soft-delete. Use list_companies(status="active") to filter out disabled companies after deletion.

Returns: {"deleted": True, "company_id": ..., "response": ...}.

Get full detail for one user.

Args: user_id: 'USR...' id.

Invite a new user. CallRail emails them an account-creation link.

Args: email: Recipient email. CallRail sends an invite. first_name, last_name: Display name. role: Default 'reporting' (read-only). Common values: 'admin', 'manager', 'reporting', 'analyst'. Other plan-specific roles may exist; we don't reject unknown values, just warn. company_ids: List of 'COM...' company IDs the user can access. Empty/None = account-wide (admins typically). account_id: Auto-resolves if omitted.

Note: This sends an invitation email. Don't run experimentally.

Update mutable user fields. Pass None to leave unchanged.

Args: user_id: 'USR...' id. company_ids: REPLACES the user's company access list (additive modification not exposed; for additive use the CallRail UI).

Remove a user from the account.

CallRail's DELETE on users is typically a hard-remove (unlike companies/trackers which soft-delete). The user loses access immediately.

Returns: {"deleted": True, "user_id": ..., "response": ...}.

Get full detail for one form submission.

Args: submission_id: 'FOR...' id.

Get full detail for one SMS conversation, including all messages.

Args: conversation_id: Short alphanumeric conversation id (e.g. '8hw3p'). Returned by list_text_messages as id on each conversation.

List webhook subscriptions on the account or one company.

Args: company_id: Filter to webhooks attached to one company. per_page: Page size (max 250). page: 1-indexed. account_id: Auto-resolves if omitted.

Get full detail for one webhook subscription.

Args: webhook_id: Webhook id (CallRail-assigned).

Get full detail for one tag.

Args: tag_id: Numeric tag id. account_id: Auto-resolves if omitted.

List integrations attached to one company (GMB, Google Ads, Facebook, Slack, Webhooks, etc.).

Args: company_id: 'COM...' id. Required — the integrations endpoint returns 400 without it (account-level listing isn't supported). per_page: Page size (max 250). page: 1-indexed. account_id: Auto-resolves if omitted.

Get full detail for one integration.

Args: integration_id: Numeric integration id (from list_integrations). account_id: Auto-resolves if omitted.

Manually create a form submission (e.g. backfill an offline lead).

Useful when you receive a lead through a non-CallRail-tracked channel (paper form, in-person, etc.) and want it visible in CallRail with proper attribution + lead-status workflow.

Args: company_id: 'COM...' id. Required. referrer / referring_url / landing_page_url: All three required (CallRail enforces "either session_id or all 3 of these"). Use the original web context if known, or "(direct)" / "https://offline" placeholders for in-person leads. form_url: URL of the form page if applicable. form_data: Dict of form-field values (e.g. {"name": "Kevin", "email": "k@x.com", "phone": "412-555-1234"}). customer_phone_number / name / email: Set on the submission directly (overrides form_data if both are set). note, tags, value, lead_status: Standard lead-management fields. account_id: Auto-resolves if omitted.

⚠️ Place an outbound call. THIS ACTUALLY DIALS A REAL PHONE.

CallRail will dial from_number first; once that's answered, it bridges to to_number. Both legs cost minutes against your bundle. Misuse can constitute unlawful telemarketing — verify consent.

You must pass confirm_dialing=True to actually place the call. This is a safety guard against accidental AI-driven cold-calls.

Args: from_number: Your end of the call (typically your tracking number, e.g. +14129548337). E.164 format. to_number: Recipient's number. E.164 format. confirm_dialing: REQUIRED — set True to actually dial. Returns error envelope if False (default). company_id: Optional company scope. account_id: Auto-resolves if omitted.

Returns: The call object CallRail creates (id, etc.).

Create a notification rule (who gets pinged on which event).

Args: name: Display name for this rule. user_id: 'USR...' id of the user being notified. alert_type: Trigger event. Common values: 'all_calls', 'first_time_callers', 'missed_calls', 'voicemails', 'all_texts', 'first_time_texters', 'all_form_submissions'. Plan-specific types may exist. company_id, tracker_id: Optional scope filters. send_email / send_desktop / send_push: Channel toggles. call_enabled / sms_enabled: Trigger toggles for mixed-event rules. email: Override email address (defaults to user's email). account_id: Auto-resolves if omitted.

Update a notification rule. Pass None to leave fields unchanged.

Delete a notification rule.

List notification rules on the account.

Args: company_id, user_id: Optional filters. per_page: Page size (max 250). page: 1-indexed. account_id: Auto-resolves if omitted.