CallRail MCP

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.

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": [...]}`…

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.

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, <metrics>}).

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.

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, <metrics>}).

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.

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.

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.

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.

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 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'.

⚠️ 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. whispe…

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.

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": ...}`.

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).

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.

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.

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": ...}`.

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 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).

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).

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.

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.

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 integration. Args: integration_id: Numeric integration id (from list_integrations). account_id: Auto-resolves if omitted.

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).

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.

Get full detail for one tag. Args: tag_id: Numeric tag id. account_id: Auto-resolves if omitted.

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 a specific tracker. Args: tracker_id: 'TRK...' id. account_id: Auto-resolves if omitted.

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.

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 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'.

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

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.

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

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

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 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'.

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.

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.

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).

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

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

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.