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'. page: 1-indexed. Agencies with more than per_page companies need this to reach the rest. Previously there was no way to fetch page 2 via this tool.

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. One of VALID_SOURCE_TYPES: 'all', 'landing_url', 'landing_params', 'offline', 'web_referrer', 'direct', 'search', 'google_ad_extension' (what Google Ads call extensions use), 'mobile_ad_extension', 'google_my_business', plus the production-observed 'facebook_all' and 'bing_all'. Ignored for type='session'. 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 requires 4-50; each pool number is billed separately, so this multiplies your monthly cost. 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, and answer 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). answer_status: Server-side filter. One of 'answered', 'missed', 'voicemail'. This is CallRail's real filter parameter. answered: DEPRECATED alias kept for backwards compatibility. 'true' maps to answer_status='answered', 'false' to 'missed'. (CallRail has no answered query param; passing it used to be silently ignored, so results were unfiltered.) source: CallRail has NO server-side source filter, so this is applied CLIENT-SIDE to the current page only: the calls array is filtered by exact, case-insensitive match on each call's source field. total_records/total_pages in the response still describe the UNFILTERED query. See source_filter in the response for what was actually applied. For source breakdowns prefer call_stats(group_by='source'). 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_type, 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. Paginated. Filterable by company and date window.

Args: account_id: CallRail 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). per_page: Page size (max 250). page: 1-indexed. fields: Comma-separated additional fields to include, e.g. 'company_name,form_data,referrer,landing_page_url,source, utm_source,utm_medium,utm_campaign,utm_content,utm_term, gclid,fbclid,form_url,form_name'.

Returns: JSON string with page, per_page, total_pages, total_records, and form_submissions[]. Each submission has id ('FOR...'), submitted_at, customer details (if captured), and a form_data dict keyed by form field name.

List SMS/text message conversations sent to or received via CallRail trackers. Paginated. Filterable by company and date window.

Receiving SMS works on standard accounts. Outbound SMS sending requires CallRail's A2P SMS API permission (returns 403 otherwise); see create_text_message notes if available on your plan.

Args: account_id: CallRail 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). per_page: Page size (max 250). page: 1-indexed.

Returns: JSON string with page, per_page, total_pages, total_records, and conversations[]. Each conversation has a list of inbound + outbound messages, customer phone number, the tracking number used, and timestamps.

List all users on the account. Returns a single page of up to MAX_PER_PAGE users (no pagination support; adequate for small and medium agency accounts).

Args: account_id: CallRail account ID. Auto-resolves if omitted.

Returns: JSON string with users[]. Each user has id ('USR...'), email, first_name, last_name, role ('admin' | 'manager' | 'reporting'), accepted_at, time_zone, and company_ids[] the user has access to.

Get the recording URL for a call. Returns a short-lived signed URL. Fetch and use it within a few minutes before it expires.

Recording must be enabled on the company (CallRail UI > Settings > Account). Calls placed BEFORE recording was enabled have no recording even if it's enabled now; CallRail does not retroactively record.

Args: call_id: 'CAL...' id. account_id: CallRail account ID. Auto-resolves if omitted.

Returns: JSON string with url (signed audio URL, typically MP3) plus recording metadata. Empty url typically means recording was disabled at call time, or the user opted out via the call-flow recording disclaimer.

Get the AI transcript for a call. Requires CallRail Conversation Intelligence (CallScribe) to be enabled on the company at the time the call was placed.

If CallScribe was enabled AFTER the call, no transcript exists; CallRail does not retroactively transcribe.

⚠️ As of CallRail's 2026-05-21 API change, transcript data requires a Premium Conversation Intelligence subscription; without it, the endpoint 404s (and the transcription field on calls returns null) even when a transcript exists. A 404 here therefore means EITHER "no transcript for this call" OR "plan doesn't include transcript API access"; the error envelope includes a hint.

Args: call_id: 'CAL...' id. account_id: CallRail account ID. Auto-resolves if omitted.

Returns: JSON string with the transcription including segments (text per speaker turn), per-segment confidence scores, and durations.

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, 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", which is 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.

Reads the call's current tags first, merges the new ones in, then PUTs the combined list. Use this when you want to add labels (e.g. 'lead', 'spam', 'follow-up') without losing prior tags. To fully replace tags, use update_call(tags=[...]) instead.

Auto-creates company-level tags for any name not already in the system (CallRail's default behavior). Empty/whitespace-only entries are silently filtered, so add_call_tags(['', 'lead']) won't 400 (only 'lead' is sent).

Args: call_id: 'CAL...' id. tags: Tag names to add. Strings only; non-strings are dropped with a warning. De-duplicated. Max 100 tags per request. account_id: CallRail account ID. Auto-resolves if omitted.

Returns: JSON string with the updated call object (showing the merged tag list). Errors 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 24 CallRail-supported colors (see VALID_TAG_COLORS): gray1-2, blue1-2, cyan1-2, purple1-2, pink1-4, red1-2, orange1-4, yellow1-2, green1-4. 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 the 24 CallRail-supported colors (see VALID_TAG_COLORS): gray1-2, blue1-2, cyan1-2, purple1-2, pink1-4, red1-2, orange1-4, yellow1-2, green1-4.

Delete a tag definition from the account. Removes it from any calls or form submissions that had it applied.

This is a HARD delete; the tag is gone permanently along with its historical applications. To preserve history, prefer renaming or disabling via update_tag instead.

Args: tag_id: Numeric tag ID. CallRail tag IDs are integers (NOT the string-prefixed format other entities use). Must match ^[0-9]+$ (string or numeric forms accepted). account_id: CallRail account ID. Auto-resolves if omitted.

Returns: JSON string {"deleted": True, "tag_id": ...} on success.

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, so this tool 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: filter (same semantics as list_calls). At least one filter must be provided to avoid "update everything ever". answer_status: server-side filter. One of 'answered', 'missed', or 'voicemail'. answered: DEPRECATED alias ('true' -> answered, 'false' -> missed). Before v1.2.0 this was forwarded as an answered query param that CallRail does not implement: the filter was silently dropped, so a commit run updated EVERY call in the window. source: applied CLIENT-SIDE (exact, case-insensitive match on each call's source field) because CallRail has no server-side source filter. Matching happens before the 500-cap is applied. 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. NOTE: CallRail does not support un-marking spam via the API, so set_spam=False is rejected. dry_run: If True (default), return preview only. False = commit. account_id: Auto-resolves if omitted.

Returns: - If dry_run: {"dry_run": true, "matched": N, "would_update_calls": [...], "set_fields": {...}} - Else: {"dry_run": false, "matched": N, "updated": M, "failed_count": K, "failures": [...]}

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 a field unchanged; only fields with explicit values are sent in the PUT body.

CRITICAL: Any boolean toggle you set will OVERRIDE current state. If a company has CallScribe enabled and you call update_company(name='New Name') without passing callscribe_enabled, CallScribe stays on. But passing callscribe_enabled=False will DISABLE CallScribe (a paid feature). Be deliberate with bool args.

Empty-string name / time_zone are rejected (almost always a mistake; pass None to leave them alone).

Args: company_id: 'COM...' id. name: New display name. Empty string rejected. Max 255 chars. time_zone: IANA tz string (e.g. 'America/New_York'). callscore_enabled: Lead-scoring AI feature. PAID add-on. lead_scoring_enabled: Older lead-scoring system. swap_exclude_jquery: Skip jQuery initialization in DNI script. callscribe_enabled: Conversation Intelligence (transcripts + keyword spotting). PAID feature. keyword_spotting_enabled: DEPRECATED by CallRail. Accepted for compatibility but has no effect. swap_exclude_jquery: DEPRECATED by CallRail (the DNI script no longer needs jQuery). Accepted but has no effect. form_capture: Enable CallRail Form Tracking on this company. Sent as CallRail's external_form_capture PUT field. account_id: CallRail account ID. Auto-resolves if omitted.

Returns: JSON string with the updated company object.

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 on the account.

Args: user_id: 'USR...' id. account_id: CallRail account ID. Auto-resolves if omitted.

Returns: JSON string with the user object: id, email, first_name, last_name, role ('admin' | 'manager' | 'reporting'), accepted_at (null if invitation pending), time_zone, and company_ids[] the user can access.

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, including all submitted field data.

Useful for retrieving the original form payload after seeing a submission ID via list_form_submissions or in a webhook callback.

Args: submission_id: 'FOR...' id. account_id: CallRail account ID. Auto-resolves if omitted.

Returns: JSON string with the form submission: submitted_at, customer details, source/UTM attribution, landing page URL, referrer, and form_data dict keyed by form field name.

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.

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 REAL PHONES.

CallRail dials business_phone_number FIRST; once that leg is answered it dials customer_phone_number and bridges the two. Both legs cost minutes against your bundle. Misuse can constitute unlawful telemarketing, so verify consent.

US and Canadian numbers only (CallRail does not support outbound to the UK or Australia via this endpoint).

You must pass confirm_dialing=True to actually place the call.

Args: caller_id: The number shown to the recipient. Must be one of your CallRail tracking numbers or a verified Outbound Caller ID. E.164 format. business_phone_number: The FIRST leg CallRail dials (your agent's phone). E.164 format. customer_phone_number: The SECOND leg, bridged in once the business leg answers. E.164 format. confirm_dialing: REQUIRED. Set True to actually dial. Returns an error envelope if False (default). recording_enabled: Record this call. outbound_greeting_text: Text-to-speech greeting played to the customer. outbound_greeting_recording_url: Public URL of an audio greeting, used instead of outbound_greeting_text. account_id: Auto-resolves if omitted.

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

NOTE (v1.2.0): earlier versions sent {"from", "to"}, which are not fields CallRail accepts, so every call failed. The parameter names above match the documented request body.

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 a field unchanged; only fields with explicit values are sent in the PUT body.

Notification rules trigger emails / desktop pushes / SMS when calls or form submissions match conditions. Use this to rewire targets, change triggering events, or silence a noisy rule without deleting it (set all send_* to False).

Args: notification_id: Notification rule ID. name: Display name for the rule. alert_type: Common values: 'all_calls', 'first_time_callers', 'missed_calls', 'voicemails', 'all_texts', 'first_time_texters', 'all_form_submissions' (same set as create_notification). Plan-specific: unknown values warn but do not reject. send_email: Send email notification. send_desktop: Send desktop browser push. send_push: Send mobile push notification. call_enabled: Trigger on call events. sms_enabled: Trigger on SMS events. email: Override target email (defaults to user's primary). Validated as RFC-822-ish. account_id: CallRail account ID. Auto-resolves if omitted.

Returns: JSON string with the updated notification rule.

Delete a notification rule. The rule is gone. To keep but mute it, prefer update_notification(send_email=False, send_desktop=False, send_push=False).

Args: notification_id: Notification rule ID. account_id: CallRail account ID. Auto-resolves if omitted.

Returns: JSON string {"deleted": True, "notification_id": ..., "response": ...}. The response mirrors CallRail's body (often empty on 204).

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.

List leads (unique people) across calls, forms, and texts.

A lead is CallRail's deduplicated person record: one entry per customer regardless of how many times they called / submitted / texted. Use get_lead_timeline for a lead's full cross-channel history.

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

Returns: JSON string with page, per_page, total_pages, total_records, and leads[]. Each lead has id ('PER...'), name, phone, email, company_id, company_name, created_at.

Get a lead's full cross-channel activity timeline: every call, form submission, and text thread from that person in one response, with first-touch/last-touch attribution.

This replaces the manual "search calls by number + search forms by email" dance when reconstructing a customer's history.

Args: lead_id: 'PER...' lead id (from list_leads). account_id: Auto-resolves if omitted. per_page: Timeline page size (max 250). page: 1-indexed.

Returns: JSON string with lead (the person record) and timeline[] (chronological interaction entries, paginated).

List SMS threads. Unlike list_text_messages (conversation transcripts), threads carry the lead-management surface: notes, value, tags, lead_qualification, state. Threads are UPDATABLE via update_sms_thread.

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

Returns: JSON string with sms_threads[]. Each thread has id, customer_name / customer_phone_number, current + initial tracker/tracking-number, notes, value, tags, lead_qualification, state.

Get one SMS thread's lead-management record (notes, value, tags, lead_qualification, state). For the message transcript itself use get_text_message with the conversation id.

Args: thread_id: Thread id (from list_sms_threads). account_id: Auto-resolves if omitted.

Update an SMS thread's lead-management fields. This is the texting equivalent of update_call. Closes the gap where texting leads couldn't be tagged / noted / qualified via API.

Args: thread_id: Thread id (from list_sms_threads). notes: Note text (max 4000 chars). Empty string rejected. value: Numeric lead value. tags: Tag names to apply (max 100). append_tags: If True (default), tags are ADDED to existing ones (CallRail's append_tags flag). If False, tags REPLACES the thread's tag list. lead_qualification: e.g. 'good_lead', 'not_a_lead'. Values are plan-configurable so unknown strings are passed through. account_id: Auto-resolves if omitted.

Server-side call aggregation via CallRail's /calls/summary.json.

One request instead of paginating every call. Prefer this over call_summary (which fetches and counts calls client-side) when you only need grouped totals. call_summary remains useful for metrics this endpoint doesn't expose (first-time vs repeat split, per-source-name breakdown, exact duration sums).

Args: group_by: Dimension to group by. One of: 'source', 'keywords', 'campaign', 'referrer', 'landing_page', 'company'. days: Lookback (default 30). Ignored if start_date given. start_date / end_date: 'YYYY-MM-DD'. Explicit dates win. company_id: Filter to one company. fields: Comma-separated metrics, e.g. 'total_calls,missed_calls,answered_calls,first_time_callers, average_duration,leads'. Default: total_calls only. account_id: Auto-resolves if omitted.

Returns: JSON string with start_date, end_date, time_zone, total_results and grouped_results[] ({key, }).

Call volume over time via CallRail's /calls/timeseries.json. One request for a trend line instead of client-side bucketing.

CallRail refuses any request whose result set would exceed 200 data points. With the default daily interval that caps the window at ~200 days; use interval='week' or 'month' for longer ranges. This tool checks the limit before sending so you get a clear message instead of a raw 400.

Args: days: Lookback (default 30). Ignored if start_date given. start_date / end_date: 'YYYY-MM-DD'. Explicit dates win. company_id: Filter to one company. fields: Comma-separated metrics. Valid: total_calls, missed_calls, answered_calls, abandoned_calls, first_time_callers, average_duration, formatted_average_duration, leads. interval: Bucket size. One of 'hour', 'day', 'week', 'month', 'year'. Defaults to CallRail's own choice (daily) when omitted. account_id: Auto-resolves if omitted.

Returns: JSON string with total_results and data[], one entry per bucket ({key/date, }).

Server-side form-submission totals via /forms/summary.json.

Args: days: Lookback (default 30). Ignored if start_date given. start_date / end_date: 'YYYY-MM-DD'. Explicit dates win. company_id: Filter to one company. account_id: Auto-resolves if omitted.

Returns: JSON string with start_date, end_date, time_zone, and total_results (e.g. {"total_forms": N}).

Get the visitor's page-view history behind a call: which pages they browsed (with timestamps) before and around dialing. Pairs with call_eligibility_check for conversion debugging: shows the actual session journey that led to the call.

Args: call_id: 'CAL...' id. account_id: Auto-resolves if omitted. per_page: Page size (max 250). page: 1-indexed.

Returns: JSON string with page_views[] (paginated).