NAV

Getting Started

Welcome to CallRail API V2

Welcome to the documentation for V2 of the CallRail API. If you need to view documentation for API V1, please visit our CallRail API V1 documentation.

CallRail helps data-driven marketers measure the performance of their campaigns by providing multi-channel call attribution. These call analytics give users the insight they need to optimize their advertising campaigns, increase sales effectiveness, and improve customer retention.

The CallRail REST API provides a method to programmatically access and modify the data within your CallRail account. It is intended for developers and customers looking to integrate custom software directly with CallRail. Getting started is simple, and with this guide you can make your first API request in a matter of minutes!

If you’d like to share something you’ve built using CallRail’s API, or if you’d like advice from other developers, check out CallRail’s Community.

Terminology

CallRail has its own nomenclature that is used to describe our call tracking technology. This section is a brief glossary of terms that are useful in understanding our platform. For a more thorough overview of CallRail, check out our Getting To Know CallRail support articles.

Dynamic Number Insertion (DNI) - CallRail can dynamically change the telephone number your website visitors see based on how they came to the site. When a visitor navigates to your website through one of the sources you’re tracking, CallRail’s JavaScript will detect the phone numbers on your web page and swap them with the correct tracking number. We’ll then store the visitor’s source in a cookie so they’ll continue to see the same tracking number each time they return to your website (unless our JavaScript is removed).

Source Tracker - Source trackers associate a single tracking number to a certain set of your customers based on how they found the number. For example, a single source tracker might be used to identify website visitors who came from facebook.com, who found your site from a paid Google search, or via an offline source such as a billboard or TV advertisement.

Keyword (Session) Tracker - Session trackers serve one number from a pool of tracking numbers to website visitors, allowing you to associate calls to individual visitors. You can also see the keywords they searched for before arriving via search engine, as well as their browsing history on your site.

Destination Number - The destination number is where the phone will ring when customers dial your tracking number. This is typically your primary business phone number.

Tracker - This is a generic term applied to any source tracker or keyword pool.

Swap Target - The swap target is the telephone number CallRail looks for on your website to dynamically replace with a tracking number. By default, the swap target is the destination number, but you can specify a different swap target for each tracker on the number configuration page.

Source Type - The online or offline source the tracking number(s) is configured to track. Our company-specific dynamic number insertion script displays tracking numbers based on the source type of the tracker in question.

Authorization

CallRail uses API keys to authenticate and authorize requests being made to the API. These API keys are scoped to individual users, and have access to the same data as the user who created the key. API responses will only include data pertaining to the user’s API key. For example, a request to retrieve a list of tracked phone calls will only return calls the user could see in CallRail’s interface. Calls placed to accounts or companies where the user has no access will not be returned. Similarly, anyone who has your API key can use that key to access or modify any data you have control over.

The CallRail API authenticates via the HTTP Authorization header: Authorization: Token token="YOUR_API_KEY". All requests to all API endpoints require and API key to be provided.

Conventions

The CallRail API adheres to REST architectural principles. REST (Representational State Transfer) takes advantage of HTTP methods to create, read, update, and delete (CRUD) resources on cloud applications like CallRail.

The CallRail API sends and receives data in JSON format. JSON (JavaScript Object Notation) is completely language independent and uses human-readable text to send data objects consisting of key-value pairs.

Supported HTTP Methods

HTTP Method Description
GET Requests data from a target resource. Requests using GET always retrieve data.
POST Submits data to create a resource. Requests using POST always create data.
PUT Submits data to update a target resource. Requests using PUT always update data.
DELETE Deletes the target resource. Requests using DELETE always delete data.

Each API endpoint in this guide is documented with the correct HTTP method, endpoint URL, end-point specific request parameters, and sample requests and responses. Additional tables that describe the response in detail are also provided.

Additional Resources

Pagination

A paginated JSON response will include these fields in the response metadata:

{
  "page": 3,
  "per_page": 25,
  "total_pages": 5,
  "total_records": 111
}

All requests to the CallRail API that return more than one object will be paginated. You can paginate through results with the following attributes:

Pagination Parameters

Name Type Required? Description
page integer optional Page number that should be returned for this request (The first page is 1. If no page number is specified the first page will be returned.)
per_page integer optional How many objects to return per page to return (The default is 100. Most endpoints support a maximum of 250.)

Example Queries That Include Pagination Parameters

Specifying a Page:

This request will return page 3 from the Users index endpoint.

Specifying the Number of Records Per Page:

This request will return 25 objects per page from the Users index endpoint.

Paginated Response Fields

The fields listed below will be included in the paginated JSON response for endpoints that return a collection of objects.

Field Description
page The page returned in this response.
per_page The number of records being returned per page.
total_pages The total number of pages that fit your query parameters.
total_records The total number of objects that fit your query parameters.

Sorting

A sorted JSON response might look like this:

{
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_records": 3,
  "users": [
    {
      "email": "bob@example.com",
      "id": 223166018,
      "created_at": "2016-01-29T12:43:10.286-05:00",
      "role": "admin",
      "first_name": "Bob",
      "last_name": "Belcher",
      "name": "Bob Belcher"
    },
    {
      "email": "linda@example.com",
      "id": 159539165,
      "created_at": "2016-04-08T10:55:38.632-04:00",
      "role": "manager",
      "first_name": "Linda",
      "last_name": "Belcher",
      "name": "Linda Belcher"
    },
    {
      "email": "teddy@example.com",
      "id": 330833311,
      "created_at": "2015-03-03T12:15:22.954-05:00",
      "role": "reporting",
      "first_name": "Teddy",
      "last_name": "Francisco",
      "name": "Teddy Francisco"
    }
  ]
}

Most endpoints that return a list of objects also support sorting. Depending on the endpoint, you will find various fields enabled for sorting. Sorting is always either alphabetical, or reverse chronological (newest first).

Name Type Required? Description
sort text optional The field by which the returned response will be sorted by. Refer to individual endpoints to determine acceptable sorting fields.
order text optional The order of the returned sort field. If provided, sort is required. Value can be one of asc or desc.

Example Query That Includes The Sorting Parameter

Sorting the Results: Users Index Endpoint

Will return a list of user objects for the target account, sorted by email address in alphabetical order.

Ordering: Users Index Endpoint

Will return a list of user objects for the target account, sorted by email address in reverse alphabetical order.

Field Selection

A JSON response which returns user-selected fields might look like this:

{
    "answered": false,
    "business_phone_number": null,
    "customer_city": "Seattle",
    "customer_country": "US",
    "customer_name": "Jovani Osinski",
    "customer_phone_number": "+15896836609",
    "customer_state": "WA",
    "direction": "inbound",
    "duration": null,
    "id": 444941612,
    "recording": "http://cdn.callrail.com/v2/a/297251749/calls/444941612/recording",
    "recording_duration": null,
    "start_time": "2017-06-04T13:36:24.000Z",
    "tracking_phone_number": "+14045555466",
    "voicemail": true,
    "company_id": 886654469,
    "company_name": "Grand Symphony Resort"
}

Field selection allows for control of the fields included in a response. Field selection is available for endpoints that return a list of objects and endpoints that return a single object. Depending on the endpoint, additional fields can be included with the default response fields. Each endpoint will describe the possible fields for selection.

Name Type Required? Description
fields text optional Specified field(s) that will be returned in the response. Requested field names are are separated by commas.

Example Query That Includes Additional User Requested Fields

Selecting Specific Fields: Calls Show Endpoint

Will return the additional user requested fields for the target call.

Filtering

{
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_records": 1,
  "companies": [
    {
      "id": 196207137,
      "name": "Bob's Burgers",
      "status": "disabled",
      "created_at": "2016-02-23T20:16:38.389Z",
      "disabled_at": "2016-04-13T15:35:29.040Z"
    },
    {
      "id": 635837866,
      "name": "Falafel on a Waffle",
      "status": "disabled",
      "created_at": "2017-02-13T15:10:42.742Z",
      "disabled_at": "2017-02-13T15:39:23.149Z"
    },
    {
      "id": 289003184,
      "name": "Jimmy Pesto's Pizzeria",
      "status": "disabled",
      "created_at": "2015-11-24T17:51:34.908Z",
      "disabled_at": "2015-11-24T17:51:55.133Z"
    }
  ]
}

Filtering allows the list of objects returned for a specific endpoint to be filtered by specific parameters. Filtering is available for many endpoints that return a list of objects. Each endpoint that supports filtering will describe the possible filters.

Name Type Required? Description
parameter text optional The field by which the returned response will be filtered.

Example Query That Includes The Filtering Parameter

Filter the Response: Companies Index Endpoint

Will return a list of company objects in the target account, where the companies are disabled companies.

Filtering Data by Date

The CallRail API accepts date filters in one of two formats: either a standardized date range, or specific start and end dates. In addition, a time zone can be specified to align dates as expected. The following endpoints accept these parameters:

Filtering by Standard Date Range

To choose a standardized date range (such as those seen in the CallRail UI), provide a date_range parameter. This is the default for API requests that don’t specify date parameters. Date interpretation according to the table below will be done according to the specified or default time zone.

ex. date_range=recent

Value Description
recent default Select data from the prior 30 days, including the current date.*
today Select data from today only
yesterday Select data from yesterday only
last_7_days Select data from the previous 7 days, not including the current date
last_30_days Select data from the previous 30 days, not including the current date
this_month Select data from the current month, including the current date
last_month Select data from the previous month
this_year Select data from the this year up to and including the current date
last_year Select data from last year
all_time Select all data, including the current date

*recent is the default view in the CallRail UI, and is the API default when no other date range parameters are specified.

Filtering by Specific Dates

To select data from a specific date range, provide the start_date and end_date parameters with the request. These parameters should be formatted according to ISO 8601. (ex. “2016-10-17”) Specific times of day are also acceptable in ISO 8601 format. (ex. “2015-09-05T14:00”)

Dates and times provided in this manner are inclusive. For example, listing all calls with start_date=2016-10-17 will be interpreted as beginning at midnight on that date, so all calls that occurred on that date will be included. Specifying end_date=2016-10-17 will be interpreted as calls up to 11:59:59pm on that date. To obtain all calls on a specific date, specify the same date for both start_date and end_date.

Date interpretation will be done according to the specified or default time zone.

ex. start_date=2016-10-01&end_date=2016-10-17

Parameter Description
start_date Provide data starting from provided date and time.
ex: “2015-09-05” for all calls after and including September 9, 2015
ex: “2015-09-05T10:00” for all calls after 10 AM September 5, 2015
end_date Provide data before provided date and time.
ex: “2015-10-05” for all calls before and including October 9, 2015
ex: “2015-09-05T10:00” for all calls before 10 AM September 5, 2015

Searching

A JSON response based on a user-specified search term might look like this:

{
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_records": 2,
  "users": [
    {
      "email": "bob@example.com",
      "id": 223166018,
      "created_at": "2016-01-29T12:43:10.286-05:00",
      "role": "admin",
      "first_name": "Bob",
      "last_name": "Belcher",
      "name": "Bob Belcher"
    },
    {
      "email": "linda@example.com",
      "id": 159539165,
      "created_at": "2016-04-08T10:55:38.632-04:00",
      "role": "manager",
      "first_name": "Linda",
      "last_name": "Belcher",
      "name": "Linda Belcher"
    }
  ]
}

Searching is available for many collection endpoints that return a list of objects. Depending on the endpoint, various parameters will be enabled for searching.

Name Type Required? Description
search text optional Results returned will include only objects that match the search term. Multiple search terms are not supported.

Example Query That Searches The Endpoint

Searching for Records: Users Index Endpoint

Will return a list of user objects in the target account that match the name given.

Time Zones

The CallRail API aligns all dates to the time zone specified within the account. This can be overridden for specified API requests by including a time_zone parameter. This parameter accepts any standard time zone from the list of common names below.

ex. time_zone=America/New_York

Value Description
user default
Use the default time zone for the user indicated by the current API key. This setting is configured within the application.
America/New_York Eastern Time Zone
America/Indiana/Indianapolis Indiana Time Zone
America/Chicago Central Time Zone
America/Denver Mountain Time Zone
America/Phoenix Arizona Time Zone
America/Los_Angeles Pacific Time Zone
Time Zone GMT Hourly Offset
Pacific/Pago_Pago -11:00
Pacific/Midway -11:00
Pacific/Apia -11:00
Pacific/Honolulu -10:00
America/Juneau -09:00
America/Los_Angeles -08:00
America/Tijuana -08:00
America/Phoenix -07:00
America/Chihuahua -07:00
America/Mazatlan -07:00
America/Denver -07:00
America/Guatemala -06:00
America/Chicago -06:00
America/Mexico_City -06:00
America/Monterrey -06:00
America/Regina -06:00
America/Bogota -05:00
America/New_York -05:00
America/Indiana/Indianapolis -05:00
America/Lima -05:00
America/Halifax -04:00
America/Caracas -04:00
America/Guyana -04:00
America/La_Paz -04:00
America/Santiago -04:00
America/St_Johns -03:30
America/Sao_Paulo -03:00
America/Argentina/Buenos_Aires -03:00
America/Godthab -03:00
America/Montevideo -03:00
Atlantic/South_Georgia -02:00
Atlantic/Azores -01:00
Atlantic/Cape_Verde -01:00
Africa/Casablanca +00:00
Europe/Dublin +00:00
Europe/London +00:00
Europe/Lisbon +00:00
Europe/London +00:00
Africa/Monrovia +00:00
Etc/UTC +00:00
Europe/Amsterdam +01:00
Europe/Belgrade +01:00
Europe/Berlin +01:00
Europe/Bratislava +01:00
Europe/Brussels +01:00
Europe/Budapest +01:00
Europe/Copenhagen +01:00
Europe/Ljubljana +01:00
Europe/Madrid +01:00
Europe/Paris +01:00
Europe/Prague +01:00
Europe/Rome +01:00
Europe/Sarajevo +01:00
Europe/Skopje +01:00
Europe/Stockholm +01:00
Europe/Vienna +01:00
Europe/Warsaw +01:00
Africa/Algiers +01:00
Europe/Zagreb +01:00
Europe/Athens +02:00
Europe/Bucharest +02:00
Africa/Cairo +02:00
Africa/Harare +02:00
Europe/Helsinki +02:00
Asia/Jerusalem +02:00
Europe/Kaliningrad +02:00
Europe/Kiev +02:00
Africa/Johannesburg +02:00
Europe/Riga +02:00
Europe/Sofia +02:00
Europe/Tallinn +02:00
Europe/Vilnius +02:00
Asia/Baghdad +03:00
Europe/Istanbul +03:00
Asia/Kuwait +03:00
Europe/Minsk +03:00
Europe/Moscow +03:00
Africa/Nairobi +03:00
Asia/Riyadh +03:00
Europe/Moscow +03:00
Europe/Volgograd +03:00
Asia/Tehran +03:30
Asia/Muscat +04:00
Asia/Baku +04:00
Asia/Muscat +04:00
Europe/Samara +04:00
Asia/Tbilisi +04:00
Asia/Yerevan +04:00
Asia/Kabul +04:30
Asia/Yekaterinburg +05:00
Asia/Karachi +05:00
Asia/Tashkent +05:00
Asia/Kolkata +05:30
Asia/Colombo +05:30
Asia/Kathmandu +05:45
Asia/Almaty +06:00
Asia/Dhaka +06:00
Asia/Urumqi +06:00
Asia/Rangoon +06:30
Asia/Bangkok +07:00
Asia/Jakarta +07:00
Asia/Krasnoyarsk +07:00
Asia/Novosibirsk +07:00
Asia/Shanghai +08:00
Asia/Chongqing +08:00
Asia/Hong_Kong +08:00
Asia/Irkutsk +08:00
Asia/Kuala_Lumpur +08:00
Australia/Perth +08:00
Asia/Singapore +08:00
Asia/Taipei +08:00
Asia/Ulaanbaatar +08:00
Asia/Tokyo +09:00
Asia/Seoul +09:00
Asia/Yakutsk +09:00
Australia/Adelaide +09:30
Australia/Darwin +09:30
Australia/Brisbane +10:00
Australia/Melbourne +10:00
Pacific/Guam +10:00
Australia/Hobart +10:00
Australia/Melbourne +10:00
Pacific/Port_Moresby +10:00
Australia/Sydney +10:00
Asia/Vladivostok +10:00
Asia/Magadan +11:00
Pacific/Noumea +11:00
Pacific/Guadalcanal +11:00
Asia/Srednekolymsk +11:00
Pacific/Auckland +12:00
Pacific/Fiji +12:00
Asia/Kamchatka +12:00
Pacific/Majuro +12:00
Pacific/Auckland +12:00
Pacific/Chatham +12:45
Pacific/Tongatapu +13:00
Pacific/Fakaofo +13:00

HTTP Response Codes

The CallRail API returns standard HTTP success or error status codes. For errors, extra information about what went wrong will be encoded in the response as JSON.

The various HTTP status codes that may be returned are listed below.

Error Code Meaning
200 OK – The request has succeeded.
201 Created – The request has been fulfilled and has resulted in a new resource being created.
204 No Content – The server successfully processed the request and is not returning any content.
400 Bad Request – The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, or invalid request parameters)
401 Unauthorized – The request has not been processed because it lacks a valid API key for the target resource.
403 Forbidden – The server understood the request but refuses to authorize it.
404 Not Found – The server did not find the target resource or endpoint.
405 Method Not Allowed – The HTTP method received in the request is known by the origin server but not supported by the target resource.
406 Not Acceptable – Request parameters were supplied in an unacceptable format. For GET requests, verify that parameters are sent as part of the URL. For other requests, verify that parameters are sent as JSON.
422 Unprocessable Entity – The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, or invalid request parameters)
429 Too Many Requests – The User or Agency has sent too many requests in a given amount of time (See Rate Limiting.)
500 Internal Server Error – The server encountered an unexpected condition that prevented it from fulfilling the request. If this error persists, please contact support.
503 Service Unavailable – The CallRail API is temporarily offline for maintenance, or the server is overloaded. Please try again later.

Rate Limiting

CallRail limits the number of requests to the API made by an account on an hourly and daily basis.

The default rate limits are described below. If you expect that your application will require more requests, please contact our support team.

If your application exceeds the rate limit, all endpoints will return the HTTP 429 response code. Applications should detect this code and react by pausing or slowing requests until the 429 clears.

Default Rate Limits

API Type Hourly Limit Daily Limit
General API Requests 100/hour 1000/day
SMS Send 20/hour 480/day
Outbound Call 30/hour 600/day

Your First API Request

A simple way to learn the CallRail API is to make an API request with Postman, a powerful HTTP client to help easily test web services.

For a more detailed overview of Postman, see the Postman Documentation.

Configuring Postman to Make CallRail API Requests

1. Set the correct HTTP verb and URL endpoint

2. Set the Authorization header

Postman Image 1 (Right click on image and select View Image/Open Image In New Tab to expand the image.)

3. Click “Send” to execute your API request.

A successful response will return something similar to the following image.

Postman Image 2 (Right click on image and select View Image/Open Image In New Tab to expand the image.)

Congratulations! You’ve made your first request against the CallRail API. The remaining sections provide documentation for the available endpoints of the API.

API

Accounts

Within CallRail, accounts are the top level object. Once an account has been created, companies can then be created within a given account and relevant actions like creating tracking numbers and adding users can then be accomplished. The Accounts endpoints retrieve data about which CallRail accounts can be accessed by the given API key. For more information on scoped API keys, see the Authroization section.

Listing All Accounts

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a.json"

The above command returns a JSON structured object like this:

{
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_records": 2,
  "accounts": [
    {
      "id": 111222333,
      "name": "Last Mile Metrics",
      "outbound_recording_enabled": true
    },
    {
      "id": 444555666,
      "name": "CallRail",
      "outbound_recording_enabled": true
    }
  ]
}

This endpoint returns a paginated array of all accounts scoped to the provided API key.

API Endpoint

Method URL
GET /v2/a.json

Request Parameters

This endpoint supports Pagination and Sorting.

Sorting is available for the following fields:

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id integer Unique identifier for the account.
name string Name of the account.
outbound_recording_enabled boolean Whether or not the account has recording enabled for outbound calls placed via the CallRail web application.

Retrieving A Single Account

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}.json"

The above command returns a JSON structured object like this:

{
  "id": 111222333,
  "name": "Last Mile Metrics",
  "outbound_recording_enabled": true
}

This endpoint returns a single account object scoped to the provided API key.

API Endpoint

Method URL
GET /v2/a/{account_id}.json

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id integer Unique identifier for the account.
name string Name of the account.
outbound_recording_enabled boolean Whether or not the account has recording enabled for outbound calls placed via the CallRail web application.

Calls

Listing All Calls

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/calls.json"

The above command returns JSON structured like this:

{
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_records": 9,
  "calls": [
    {
      "answered": false,
      "business_phone_number": null,
      "customer_city": "Denver",
      "customer_country": "US",
      "customer_name": "RUEGSEGGER SIMO",
      "customer_phone_number": "+13036231131",
      "customer_state": "CO",
      "direction": "inbound",
      "duration": 4,
      "id": 482140815,
      "recording": "https://api.callrail.com/v2/a/227799611/calls/111222333/recording.json",
      "recording_duration": "27",
      "recording_player": "https://app.callrail.com/calls/111222333/recording?access_key=3b91eb7f7cc08a4d01ed",
      "start_time": "2017-01-24T11:27:48.119-05:00",
      "tracking_phone_number": "+13038163491",
      "voicemail": false,
      "agent_email": "gil@televised.com"
    },
    {
      "answered": false,
      "business_phone_number": null,
      "customer_city": "Blue Ridge",
      "customer_country": "US",
      "customer_name": "BLUE RIDGE, GA",
      "customer_phone_number": "+17064558047",
      "customer_state": "GA",
      "direction": "inbound",
      "duration": 16,
      "id": 800928657,
      "recording": null,
      "recording_duration": null,
      "recording_player": null,
      "start_time": "2017-01-24T19:50:03.456-05:00",
      "tracking_phone_number": "+17708243899",
      "voicemail": false,
      "agent_email": "elbert@bpp.com"
    }
  ]
}

This endpoint returns a paginated list of all calls in the target account.

API Endpoint

Method URL
GET /v2/a/{account_id}/calls.json

Request Parameters

This endpoint supports Pagination, Sorting, Filtering, Field Selection, and Searching.

Name Type Required? Description
company_id number optional If provided, only return calls to tracking numbers belonging to this company.
tracker_id number optional If provided, only return calls to this specific tracking number.

Sorting is available for the following fields:

Note: fields marked with * must be selected to be visible in the response payload as they are not part of the default set of fields.

Filtering is available for the following:

Searching is available for the following fields:

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
answered boolean Whether the call was answered (true) or not answered (false).
business_phone_number string The phone number of the person or business who answered the call from the dialed tracking number.
customer_city string The customer’s city, based on the original assigned location of their phone number.
customer_country string The customer’s country, based on the area code of their phone number.
customer_name string The customer’s name, as reported by Caller ID.
customer_phone_number string The customer’s phone number (in E.164 format).
customer_state string The 2-character abbreviation for the customer’s state, based on the original assigned location of their phone number.
direction string Whether the call was inbound (from a customer to you) or outbound (from you to a customer).
duration integer The duration of the call in seconds.
id integer Unique identifier for the call.
recording string A URL pointing to the calls/recording api endpoint.
recording_duration string The length in seconds of the recording, if available.
recording_player string The URL for a stand-alone recording player for this call, if available.
start_time string The date and time the call started in the current timezone (ISO 8601 format) with an offset.
tracking_phone_number string The business’ tracking phone number for this call (in E.164 format).
voicemail boolean Whether the call ended with a voicemail (true) or not (false).

Additional User Requested Response Fields

Field Selection is available for the following fields.

Name Type Description
company_id integer The numeric id of the company the call belongs to.
company_name string The name of the company the source belongs to .
company_time_zone string The configure time zone of the company in CallRail.
created_at string The date and time the call was created in UTC, in ISO 8601 format.
device_type string Either mobile or desktop, available for calls placed to Keyword (Session) trackers.
first_call boolean Whether or not the call is the caller’s first call to this company.
formatted_customer_location string The customer’s city and state formatted for display.
formatted_business_phone_number string The phone number of the person or business who answered the call from the dialed tracking number, formatted for display.
formatted_customer_name string The customer’s name with certain values stylized for display.
prior_calls integer The number of times this company received a call from this customer prior to this call. If this is the first call from the customer, prior_calls will be 0.
formatted_customer_name_or_phone_number string The name or phone number of the customer as reported by Caller ID, formatted for display.
formatted_customer_phone_number string The customer’s phone number formatted for display.
formatted_duration string The duration of the call formatted for display.
formatted_tracking_phone_number string The business’ tracking phone number for this call formatted for display.
formatted_tracking_source string The name of the call source formatted for display.
formatted_value string The value of the call assigned via the CallRail dashboard, formatted as currency or “–” if not set.
good_lead_call_id integer If provided, the id of the call that was originally scored as a good lead.
good_lead_call_time string If provided, the time of the call that was originally scored as a good lead.
lead_status string The current lead status of this caller (as of this call). One of good_lead, not_a_lead, previously_marked_good_lead, or null.
note string Any text notes to associate with this call.
source_name string The name of the tracking number within CallRail.
tags array Any tags which have been applied to this call.
total_calls integer The total number of calls received from a customer phone number.
value string A number representing the value of this call.
waveforms string Only present if the call was recorded. Contains the URLs of two images representing the volume of the call over time.
tracker_id number If provided, only return calls to this specific tracking number.
speaker_percent object A JSON object containing the values of the percentage of time spent talking by the Agent and Customer on a call.
keywords string The keywords the visitor searched for, if available for calls placed to Keyword (Session) trackers. Keywords only provided from paid ad sources.
medium string “PPC” or “Organic”, available for calls placed to Keyword (Session) trackers.
referring_url string The URL that referred the caller to your website, available for calls placed to Keyword (Session) trackers.
landing_page_url string The URL the caller first landed on, available for calls placed to Keyword (Session) trackers.
last_requested_url string The URL of the active page at the time the call was placed, available for calls placed to Keyword (Session) trackers.
referrer_domain string The domain that referred the caller to your website, available for calls placed to Keyword (Session) trackers.
utm_source string utm_source as captured from the landing page parameter for Session Trackers, or as specified in the configuration for Source Trackers.
utm_medium string utm_medium as captured from the landing page parameter, or as specified in the configuration for Source Trackers.
utm_term string utm_term as captured from the landing page parameter, available for calls placed to Keyword (Session) trackers.
utm_content string utm_content as captured from the landing page parameter, available for calls placed to Keyword (Session) trackers.
utm_campaign string utm_campaign as captured from the landing page parameter, or as specified in the configuration for Source Trackers.
utma string Google Analytics _utma value, available for calls placed to Keyword (Session) trackers.
utmb string Google Analytics _utmb value, available for calls placed to Keyword (Session) trackers.
utmc string Google Analytics _utmc value, available for calls placed to Keyword (Session) trackers.
utmv string Google Analytics _utmv value, available for calls placed to Keyword (Session) trackers.
utmz string Google Analytics _utmz value, available for calls placed to Keyword (Session) trackers.
ga string Google Universal Analytics _ga value, available for calls placed to Keyword (Session) trackers.
gclid string gclid as captured from the landing page parameter, available for calls placed to Keyword (Session) trackers.
keywords_spotted array Array of keywords spotted, each containing keyword with locations in seconds offset from beginning of recording.
call_highlights array A list of relevant keywords automatically found in the call transcription.
agent_email string Email address for the user who answered the call, when applicable.
campaign string The name of the campaign the call belongs to.

Retrieving a Single Call

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/calls/{call_id}.json"

The above command returns JSON structured like this:

 {
  "answered": false,
  "business_phone_number": null,
  "customer_city": "New York City",
  "customer_country": "US",
  "customer_name": "Jimmy Pesto, Sr.",
  "customer_phone_number": "+13036231131",
  "customer_state": "NY",
  "direction": "inbound",
  "duration": 4,
  "id": 482140815,
  "recording": "https://api.callrail.com/v2/a/227799611/calls/111222333/recording.json",
  "recording_duration": "27",
  "recording_player": "https://app.callrail.com/calls/111222333/recording?access_key=3b91eb7f7cc08a4d01ed",
  "start_time": "2017-01-24T11:27:48.119-05:00",
  "tracking_phone_number": "+13038163491",
  "voicemail": false,
  "agent_email": "gil@televised.com"
}
curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/calls/{call_id}.json?fields=keywords_spotted"

The above command returns JSON structured like this:

 {
  "answered": false,
  "business_phone_number": null,
  "customer_city": "New York City",
  "customer_country": "US",
  "customer_name": "Jimmy Pesto, Sr.",
  "customer_phone_number": "+13036231131",
  "customer_state": "NY",
  "direction": "inbound",
  "duration": 4,
  "id": 482140815,
  "recording": "https://api.callrail.com/v2/a/227799611/calls/111222333/recording.json",
  "recording_duration": "27",
  "recording_player": "https://app.callrail.com/calls/111222333/recording?access_key=3b91eb7f7cc08a4d01ed",
  "start_time": "2017-01-24T11:27:48.119-05:00",
  "tracking_phone_number": "+13038163491",
  "voicemail": false,
  "agent_email": "gil@televised.com",
  "keywords_spotted": [
    {
      "keyword": "test phrase one",
      "locations": [
        {
          "speaker": "caller",
          "start": 7.71
        },
        {
          "speaker": "agent",
          "start": 13.38
        },
        {
          "speaker": "caller",
          "start": 17.96
        }
      ]
    },
    {
      "keyword": "test phrase two",
      "locations": [
        {
          "speaker": "caller",
          "start": 8.44
        }
      ]
    }
  ]
}

This endpoint returns a single call object associated with the target account.

API Endpoint

Method URL
GET /v2/a/{account_id}/calls/{call_id}.json

Request Parameters

This endpoint supports Field Selection.

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
answered boolean Whether the call was answered (true) or not answered (false).
business_phone_number string The phone number of the person or business who answered the call from the dialed tracking number.
customer_city string The customer’s city, based on the original assigned location of their phone number.
customer_country string The customer’s country, based on the area code of their phone number.
customer_name string The customer’s name, as reported by Caller ID.
customer_phone_number string The customer’s phone number (in E.164 format).
customer_state string The 2-character abbreviation for the customer’s state, based on the original assigned location of their phone number.
direction string Whether the call was inbound (from a customer to you) or outbound (from you to a customer).
duration integer The duration of the call in seconds.
id integer Unique identifier for the call.
recording string A URL pointing to the recording of the call, if available. This URL redirects to the actual audio file of the recording in MP3 format.
recording_duration string The length in seconds of the recording, if available.
recording_player string The URL for a stand-alone recording player for this call, if available.
start_time string The date and time the call started in the current timezone (ISO 8601 format) with an offset.
tracking_phone_number string The business’ tracking phone number for this call (in E.164 format).
voicemail boolean Whether the call ended with a voicemail (true) or not (false).

Additional User Requested Response Fields

Field Selection is available for the following fields.

Name Type Description
company_id integer The numeric id of the company the call belongs to.
company_name string The name of the company the source belongs to.
company_time_zone string The configure time zone of the company in CallRail.
created_at string The date and time the call was created in UTC, in ISO 8601 format.
device_type string Either mobile or desktop, available for calls placed to Keyword (Session) trackers.
first_call boolean Whether or not the call is the caller’s first call to this company.
formatted_customer_location string The customer’s city and state formatted for display.
formatted_business_phone_number string The phone number of the person or business who answered the call from the dialed tracking number, formatted for display.
formatted_customer_name string The customer’s name with certain values stylized for display.
prior_calls integer The number of times this company received a call from this customer prior to this call. If this is the first call from the customer, prior_calls will be 0.
formatted_customer_name_or_phone_number string The name or phone number of the customer as reported by Caller ID, formatted for display.
formatted_customer_phone_number string The customer’s phone number formatted for display.
formatted_duration string The duration of the call formatted for display.
formatted_tracking_phone_number string The business’ tracking phone number for this call formatted for display.
formatted_tracking_source string The name of the call source formatted for display.
formatted_value string The value of the call assigned via the CallRail dashboard, formatted as currency or “–” if not set.
good_lead_call_id integer If provided, the id of the call that was originally scored as a good lead.
good_lead_call_time string If provided, the time of the call that was originally scored as a good lead.
lead_status string The current lead status of this caller (as of this call). One of good_lead, not_a_lead, previously_marked_good_lead, or null.
note string Any text notes to associate with this call.
source_name string The name of the tracking number within CallRail.
tags array Any tags which have been applied to this call.
total_calls integer The total number of calls received from a customer phone number.
value string A number representing the value of this call.
waveforms string Only present if the call was recorded. Contains the URLs of two images representing the volume of the call over time.
tracker_id number If provided, only return calls to this specific tracking number.
speaker_percent object A JSON object containing the values of the percentage of time spent talking by the Agent and Customer on a call.
keywords string The keywords the visitor searched for, if available for calls placed to Keyword (Session) trackers. Keywords only provided from paid ad sources.
medium string “PPC” or “Organic”, available for calls placed to Keyword (Session) trackers.
referring_url string The URL that referred the caller to your website, available for calls placed to Keyword (Session) trackers.
landing_page_url string The URL the caller first landed on, available for calls placed to Keyword (Session) trackers.
last_requested_url string The URL of the active page at the time the call was placed, available for calls placed to Keyword (Session) trackers.
referrer_domain string The domain that referred the caller to your website, available for calls placed to Keyword (Session) trackers.
utm_source string utm_source as captured from the landing page parameter for Session Trackers, or as specified in the configuration for Source Trackers.
utm_medium string utm_medium as captured from the landing page parameter, or as specified in the configuration for Source Trackers.
utm_term string utm_term as captured from the landing page parameter, available for calls placed to Keyword (Session) trackers.
utm_content string utm_content as captured from the landing page parameter, available for calls placed to Keyword (Session) trackers.
utm_campaign string utm_campaign as captured from the landing page parameter, or as specified in the configuration for Source Trackers.
utma string Google Analytics _utma value, available for calls placed to Keyword (Session) trackers.
utmb string Google Analytics _utmb value, available for calls placed to Keyword (Session) trackers.
utmc string Google Analytics _utmc value, available for calls placed to Keyword (Session) trackers.
utmv string Google Analytics _utmv value, available for calls placed to Keyword (Session) trackers.
utmz string Google Analytics _utmz value, available for calls placed to Keyword (Session) trackers.
ga string Google Universal Analytics _ga value, available for calls placed to Keyword (Session) trackers.
gclid string gclid as captured from the landing page parameter, available for calls placed to Keyword (Session) trackers.
integration_data array Company integration data collected for a given call, available for calls placed to Keyword (Session) trackers.
keywords_spotted array Array of keywords spotted, each containing keyword with locations in seconds offset from beginning of recording.
call_highlights array A list of relevant keywords automatically found in the call transcription.
transcription string A transcribed copy of the voicemail message, if available. Enabling voicemail transcription is an optional add-on available for a per message fee. See Voicemail Step and Transcriptions.
conversational_transcript string A transcribed copy of the phone call conversation, if available. Phone call transcription is an optional add-on available for a fee. Call recording must be enabled on tracking numbers where you’d like to transcribe calls. See CallScribe.
agent_email string Email address for the user who answered the call, when applicable.
campaign string The name of the campaign the call belongs to.

Creating an Outbound Phone Call

curl -H "Authorization: Token token={api_token}" \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{
          "caller_id": "+17703334455",
          "business_phone_number": "+14045556666",
          "customer_phone_number": "+14044442233",
          "recording_enabled": true,
          "outbound_greeting_recording_url": "http://www.test.com/greeting.mp3",
          "outbound_greeting_text": "These are not the droids you are looking for."
         }' \
         "https://api.callrail.com/v2/a/{account_id}/calls.json"

This endpoint initiates an outbound call from the target account.

The above command initiates an outbound phone call between a customer and a business. The API call should specify a valid tracking number or verified external number, Outbound Caller ID, as the caller_id. Upon making the request, the first leg of the call is placed to the supplied business_phone_number to iniatate the outbound phone call. Once this call is answered by the business, another outbound dial is made to the customer_phone_number and connected to the initial business phone call.

 {
  "answered": null,
  "business_phone_number": "+19044567899",
  "customer_city": "Atlanta",
  "customer_country": "US",
  "customer_name": null,
  "customer_phone_number": "+14703444700",
  "customer_state": "GA",
  "direction": "outbound",
  "duration": null,
  "id": 992697854,
  "recording": null,
  "recording_duration": null,
  "start_time": "2017-02-22T15:02:24.916-05:00",
  "tracking_phone_number": "+19044567899",
  "voicemail": false
}

API Endpoint

Method URL
POST /v2/a/{account_id}/calls.json

Request Body

Name Type Required? Description
caller_id integer required Tracking phone number or verified external phone number used to make an outbound call to the customer. Must be a valid 10 digit US or Canadian number.
customer_phone_number string required The customer’s phone number that will receive the outbound phone call once the business is connected. Must be a valid 10 digit US or Canadian number.
business_phone_number string required The phone number belonging to the business that is initially connected to the call before dialing the customer. Must be a valid 10 digit US or Canadian number.
recording_enabled boolean optional Specifies whether or not to record the call being created.
outbound_greeting_recording_url string optional A URL referencing an audio file that will be played for the customer when the call is answered.
outbound_greeting_text string optional A string of text that will be read to the customer when the call is answered.

Response Fields

When successful, the HTTP response code will indicate 201 CREATED.

Name Type Description
answered boolean Whether the call was answered (true) or not answered (false).
business_phone_number string The phone number of the person or business who answered the call from the dialed tracking number.
customer_city string The customer’s city, based on the original assigned location of their phone number.
customer_country string The customer’s country, based on the area code of their phone number.
customer_name string The customer’s name, as reported by Caller ID.
customer_phone_number string The customer’s phone number (in E.164 format).
customer_state string The 2-character abbreviation for the customer’s state, based on the original assigned location of their phone number.
direction string Whether the call was inbound (from a customer to you) or outbound (from you to a customer).
duration integer The duration of the call in seconds.
id integer Unique identifier for the call.
recording string A URL pointing to the recording of the call, if available. This URL redirects to the actual audio file of the recording in MP3 format.
recording_duration string The length in seconds of the recording, if available.
start_time string The date and time the call started in the current timezone (ISO 8601 format) with an offset.
tracking_phone_number string The business’ tracking phone number for this call (in E.164 format).
voicemail boolean Whether the call ended with a voicemail (true) or not (false).

Updating a Call

curl -H "Authorization: Token token={api_token}" \
     -X PUT \
     -H "Content-Type: application/json" \
     -v \
     -d '{
           "note": "Call customer back tomorrow",
           "tags": ["New Client"],
           "lead_status": "good_lead",
           "value": "$1.00"
         }' \
        "https://api.callrail.com/v2/a/{account_id}/calls/{call_id}.json"

The above command returns JSON structured object like this:

 {
  "answered": false,
  "business_phone_number": null,
  "customer_city": "Denver",
  "customer_country": "US",
  "customer_name": "RUEGSEGGER SIMO",
  "customer_phone_number": "+13036231131",
  "customer_state": "CO",
  "direction": "inbound",
  "duration": 4,
  "id": 482140815,
  "recording": "https://api.callrail.com/v2/a/227799611/calls/213472384/recording.json",
  "recording_duration": "27",
  "start_time": "2017-01-24T11:27:48.119-05:00",
  "tracking_phone_number": "+13038163491",
  "voicemail": false
}

This endpoint updates a call object in the target account. You can use the API to add a Tag or a Note to a call, or to set the call’s lead status.

API Endpoint

Method URL
PUT /v2/a/{account_id}/calls/{call_id}.json

Request Body

When updating a call, the following fields may be included in the request body. If a field is not included, its value will not be changed. If it is included but is null or a blank string, the field will be cleared.

Name Type Required? Description
tags array optional Array of tag names to associate with this call. See the documentation for Tag. New tags will be created if the request contains a tag that doesn’t exist in the company currently.
note string optional Any text notes to associate with this call.
value number optional A number representing the value of this call.
lead_status string optional A string representing a valid lead status. One of "good_lead", "not_a_lead", or null. If a call has a lead status of "previously_marked_good_lead", attempting to set the lead_status to "good_lead" will result in a 400 error.

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
answered boolean Whether the call was answered (true) or not answered (false).
business_phone_number string The phone number of the person or business who answered the call from the dialed tracking number.
customer_city string The customer’s city, based on the original assigned location of their phone number.
customer_country string The customer’s country, based on the area code of their phone number.
customer_name string The customer’s name, as reported by Caller ID.
customer_phone_number string The customer’s phone number (in E.164 format).
customer_state string The 2-character abbreviation for the customer’s state, based on the original assigned location of their phone number.
direction string Whether the call was inbound (from a customer to you) or outbound (from you to a customer).
duration integer The duration of the call in seconds.
id integer Unique identifier for the call.
recording string A URL pointing to the recording of the call, if available. This URL redirects to the actual audio file of the recording in MP3 format.
recording_duration string The length in seconds of the recording, if available.
start_time string The date and time the call started in the current timezone (ISO 8601 format) with an offset.
tracking_phone_number string The business’ tracking phone number for this call (in E.164 format).
voicemail boolean Whether the call ended with a voicemail (true) or not (false).

Summarizing Call Data

curl -H "Authorization: Token token=abc1234" \
  https://api.callrail.com/v2/a/{account_id}/calls/summary.json?group_by=source

The above command returns JSON structured like this:

{
  "start_date": "2016-10-10T00:00:00-0000",
  "end_date": "2016-11-09T23:59:59-0000",
  "time_zone": "UTC",
  "total_results": {
    "total_calls": 160
  },
  "grouped_by": "source",
  "grouped_results": [
    {
      "key": "Bing",
      "total_calls": 130,
      "missed_calls": 20,
      "answered_calls": 110,
      "first_time_callers": 15,
      "average_duration": 179,
      "formatted_average_duration": "2m 59s",
      "leads": 40
    },
    {
      "key": "Billboard Ad",
      "total_calls": 30,
      "missed_calls": 4,
      "answered_calls": 26,
      "first_time_callers": 4,
      "average_duration": 45,
      "formatted_average_duration": "45s",
      "leads": 6
    }
  ]
}

Return summarized Call data for an Agency or for a Company. This Call Summary data can be limited to a specific date range, can be filtered based on a variety of criteria, and can be grouped by source, keywords, campaign, referrer, landing_page, or company. Grouping by company is only available when using the account-level endpoint.

API Endpoints

Method URL
GET /v2/a/{account_id}/calls/summary.json

Request Parameters

Name Type Required? Description
company_id number optional Accepts a Company ID. If provided, show results for calls to a single Company.
group_by string optional If provided, group call summary data by specific characteristic. One of source, keywords, campaign, referrer, landing_page, or company (Note: company is only available for the Agency-level endpoint)
fields string optional Specify which data to return in request. Comma-separated list of the following: total_calls, missed_calls, answered_calls, first_time_callers, average_duration, formatted_average_duration, leads. Defaults to total_calls
device string optional If provided, show results for a specific device type. One of desktop, mobile or all.
min_duration number optional If provided, only include summary data for calls over the specified duration. An integer representing seconds should be passed.
max_duration number optional If provided, only include summary data for calls under the specified duration. An integer representing seconds should be passed.
tags string optional If provided, only return calls that have had the given tag applied. This parameter can be provided as one or more comma-separated values tags=A,B for a single tag, or one or more array parameters tags[]=A&tags[]=B.
tracker_ids number optional If provided, only return calls made to specific Trackers. This parameter can be provided as one or more comma-separated values tracker_ids=295754354,295754355, or one or more array parameters tracker_ids[]=295754354&tracker_ids[]=295754355.
direction string optional If provided, show results for a specific call direction. One of inbound, outbound or all.
answer_status string optional If provided, show results for a specific answer status. One of answered, missed, voicemail, or all.
first_time_callers boolean optional If provided, show results for either all first time callers, or for all non-first time callers.
lead_status string optional Specify results that match a specific Lead Status. One of good_lead, not_a_lead, not_scored.
agent number optional Accepts a User ID. If provided, show results for calls to a specific Agent.

Date Request Parameters

See Filtering by Date for more info

Response Fields

Name Type Description
total_results object A JSON object containing total counts of requested summary data. Summary count fields are listed below in the “Summary Data Response Fields” table.
grouped_by string If provided, this field contains the group_by value passed into the initial request for summary data.
grouped_results array An array of JSON objects containing total counts of requested summary data, grouped by the group_by parameter. Summary count fields are listed below in the “Summary Data Response Fields” table.

Summary Data Response Fields

Name Type Description
total_calls number Total number of calls in summmary criteria range.
missed_calls number Total number of calls that were missed in summmary criteria range.
answered_calls number Total number of calls that were answered in summmary criteria range.
first_time_callers number Total number of calls that were from first time callers in summmary criteria range.
average_duration number Average duration of all calls in summary criteria range, integer.
formatted_average_duration string Average duration of all calls in summary criteria range, formatted.
leads number Total number of calls that were marked as ‘leads’ in summary criteria range.

Summarizing Call Data by Time Series

curl -H "Authorization: Token token=abc1234" \
  https://api.callrail.com/v2/a/{account_id}/calls/timeseries.json?start_date=2016-10-01&end_date=2016-10-04&fields=missed_calls,answered_calls,first_time_callers,average_duration,formatted_average_duration,leads

The above command returns JSON structured like this:

{
  "start_date": "2016-10-01T00:00:00-0000",
  "end_date": "2016-10-04T23:59:59-0000",
  "time_zone": "UTC",
  "total_results": {
    "total_calls": 180,
    "missed_calls": 20,
    "answered_calls": 160,
    "first_time_callers": 54,
    "average_duration": 27,
    "formatted_average_duration": "27s",
    "leads": 12
  },
  "data": [
    {
      "date": "2016-10-01",
      "total_calls": 130,
      "missed_calls": 4,
      "answered_calls": 26,
      "first_time_callers": 4,
      "average_duration": 45,
      "formatted_average_duration": "45s",
      "leads": 6
    },
    {
      "date": "2016-10-02",
      "total_calls": 30,
      "missed_calls": 4,
      "answered_calls": 26,
      "first_time_callers": 4,
      "average_duration": 45,
      "formatted_average_duration": "45s",
      "leads": 6
    },
    {
      "date": "2016-10-03",
      "total_calls": 0,
      "missed_calls": 0,
      "answered_calls": 0,
      "first_time_callers": 0,
      "average_duration": 0,
      "formatted_average_duration": "0s",
      "leads": 0
    },
    {
      "date": "2016-10-04",
      "total_calls": 20,
      "missed_calls": 10,
      "answered_calls": 10,
      "first_time_callers": 1,
      "average_duration": 15,
      "formatted_average_duration": "15s",
      "leads": 0
    }
  ]
}
curl -H "Authorization: Token token=abc1234" \
  https://api.callrail.com/v2/a/{account_id}/calls/timeseries.json?start_date=2016-10-01&end_date=2016-10-04&interval=hour&time_zone=EST

The above command returns JSON structured like this:
*Note that this returned list is a formatting example only; it is not a full representation of the returned results for a full 24 hour data set.

{
  "start_date": "2016-10-01T00:00:00-0500",
  "end_date": "2016-10-02T23:59:59-0500",
  "time_zone": "EST",
  "total_results": {
    "total_calls": 130
  },
  "data": [
    {
      "date": "2016-10-01T00:00:00-0500",
      "total_calls": 0
    },
    {
      "date": "2016-10-01T01:00:00-0500",
      "total_calls": 0
    },
    {
      "date": "2016-10-01T02:00:00-0500",
      "total_calls": 0
    },
    {
      "date": "2016-10-01T03:00:00-0500",
      "total_calls": 0
    },
    {
      "date": "2016-10-01T04:00:00-0500",
      "total_calls": 0
    },
    {
      "date": "2016-10-01T05:00:00-0500",
      "total_calls": 0
    },
    {
      "date": "2016-10-01T06:00:00-0500",
      "total_calls": 5
    },
    {
      "date": "2016-10-01T07:00:00-0500",
      "total_calls": 20
    }
  ]
}

Retrieve aggregate call data for an account or company, grouped by date. This call data can be limited to a specific date range, filtered based on a variety of criteria, and summarized in several ways.

Time series response data is intended to be displayed as a chart, and is limited to 200 data points. For larger time spans (for example: longer than 3 months), it is recommended to specify a larger interval such as week, month, or year. If hourly or daily data is needed for a longer time period, the query must be broken into multiple requests.

API Endpoints

Method URL
GET /v2/a/{account_id}/calls/timeseries.json

Request Parameters

Name Type Required? Description
company_id number optional Accepts a Company ID. If provided, show results for calls to a single Company.
fields string optional Specify which data to return in request. Comma-separated list of the following: total_calls, missed_calls, answered_calls, first_time_callers, formatted_average_duration, leads. Defaults to total_calls.
device string optional If provided, show results for a specific device type. One of desktop, mobile or all.
interval string optional Specify the time interval to group response data. Should be one of hour, day, week, month, or year. Defaults to day.
min_duration number optional If provided, only include time series data for calls over the specified duration. An integer representing seconds should be passed.
max_duration number optional If provided, only include time series data for calls under the specified duration. An integer representing seconds should be passed.
tags string optional If provided, only return calls that have had the given tag applied. This parameter can be provided as one or more comma-separated values tags=A,B for a single tag, or one or more array parameters tags[]=A&tags[]=B.
tracker_ids number optional If provided, only return calls made to specific Trackers. This parameter can be provided as one or more comma-separated values tracker_ids=295754354,295754355, or one or more array parameters tracker_ids[]=295754354&tracker_ids[]=295754355.
direction string optional If provided, show results for a specific call direction. One of inbound, outbound or all.
answer_status string optional If provided, show results for a specific answer status. One of answered, missed, voicemail, or all.
first_time_callers boolean optional If provided, show results for either all first time callers, or for all non-first time callers.
lead_status string optional Specify results that match a specific Lead Status. One of good_lead, not_a_lead, not_scored.
agent number optional Accepts a User ID. If provided, show results for calls to a specific Agent.

Date Request Parameters

See Filtering by Date for more info

Response Fields

Name Type Description
total_results object A JSON object containing total counts of requested time series data. Summary count fields are listed below in the “Summary Data Response Fields” table.
data array An array of JSON objects containing total counts of requested time series data, ordered and grouped by date. The dates are displayed in ISO 8601 format. All time series intervals represent dates as YYYY-MM-DD, except the hour interval which includes the hour, minutes, seconds and timezone as YYYY-MM-DDThh:mm:ssTZD. Summary count fields are listed below in the “Summary Data Response Fields” table.

Additional User Requested Response Fields

Field Selection is available for the following Summary Data Response fields in the table below.

To choose any or all of the below fields, provide a fields parameter. Please refer Field Selection to see an example.

ex. fields=missed_calls,answered_calls,first_time_callers,average_duration,formatted_average_duration,leads

Name Type Description
total_calls number Total number of calls in summary date range. This Summary Data response field is available by default.
missed_calls number Total number of calls that were missed in summary date range.
answered_calls number Total number of calls that were answered in summary date range.
first_time_callers number Total number of calls that were from first time callers in summary date range.
average_duration number Average duration of all calls in time series date range, integer.
formatted_average_duration string Average duration of all calls in time series date range, formatted.
leads number Total number of calls that were marked as ‘leads’ in time series date range.

Retrieving a Single Call Recording

curl -H "Authorization: Token token=abc1234" \
  https://api.callrail.com/v2/a/{account_id}/calls/{call_id}/recording.json

The above command returns JSON structured like this:

{
  "url": "https://calltrk-production.s3.amazonaws.com/calls/recordings/000/000/700/test.mp3"
}

API Endpoint

Method URL
GET /v2/a/{account_id}/calls/{call_id}/recording.json

Request Parameters

None

Response Fields

Includes the following:

Name Type Description
url string A signed, expiring URL pointing to the audio file of the recording in MP3 format.

Call Tags

Call tags are labels that can be applied to help sort and categorize your calls. Call tags are company-dependent within your account and there’s no limit on the number of tags a company can have. More than one tag can be assigned to a single call and these tags will be available on your activity dashboard when a call is received.

Tags can also be added to a call in the following ways:

See our Call Flow feature and Tag Step for more information. For example, you can create a call tag named “Sales Call” to be applied when a caller presses option 1 to speak to Sales. Advanced Call Flows must be configured only within the CallRail web application.

Retrieving All Call Tags

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/tags.json"

The above command returns a JSON structured object like this:

{
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_records": 4,
  "tags": [
    {
      "name": "Conversion"
    },
    {
      "name": "Sales"
    },
    {
      "name": "Unanswered"
    },
    {
      "name": "Problem Call"
    }
  ]
}

This endpoint returns a paginated array of tags within the target account.

API Endpoint

Method URL
GET /v2/a/{account_id}/tags.json

Request Parameters

This endpoint supports Pagination and Sorting.

Name Type Required? Description
company_id integer optional If provided, only return calls to tracking numbers belonging to this company.

Sorting is available for the following fields:

Response Field

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
name string The name of the tag formatted for display.

Creating a Call Tag

curl -H "Authorization: Token token={api_token}" \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{
           "name": "Existing Customer",
           "company_id": 213472384,
           "color": "#464646",
           "background_color": "#e7e7e7"
        }' \
        "https://api.callrail.com/v2/a/{account_id}/tags.json"

The above command returns a JSON structured object like this:

{
  "name": "Existing Customer",
  "company_id": 213472384,
  "color": "#464646",
  "background_color": "#e7e7e7",
  "created_at": "2014-06-06T12:11:02.964-04:00"
}

This endpoint creates a single tag object in the target company.

API Endpoint

Method URL
POST /v2/a/{account_id}/tags.json

Request Body

Name Type Required? Description
name string required The name of the tag formatted for display.
company_id integer required Unique identifier for the company.
color string optional The color-hex value for the text of the tag.
background_color string optional The color-hex value of the background color for the tag.

Response Fields

Name Type Description
name string The name of the tag formatted for display.
color string The color-hex value for the text of the tag.
background_color string The color-hex value of the background color for the tag.
created_at string The date and time the tag was created in UTC (ISO 8601 format.)

Companies

A company in CallRail is a separate entity within your account. Companies are where you create tracking phone numbers, configure integrations, enable email notifications, and handle specific company settings. Calls and other activities are tracked within the context of a company, and reports can be aggregated across all tracking numbers within a company. You can also restrict users’ access to specific companies to limit the data they can interact with or modify.

For example, if you’re a marketing agency looking to keep separate reports for each client you manage, you’d create a separate company for each client. Or, if you’re overseeing calls to a franchise, you can create separate companies for each franchise location.

Listing All Companies

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/companies.json"

The above command returns JSON structured object like this:

{
  "page": 1,
  "per_page": 250,
  "total_pages": 1,
  "total_records": 3,
  "companies": [
    {
        "id": 183570817,
        "name": "Widget Shop",
        "status": "active",
        "time_zone": "America/New_York",
        "created_at": "2016-06-06T07:06:01.000Z",
        "disabled_at": null,
        "script_url": "//cdn.callrail.com/companies/183570817/5706dbe6dc972c634a65/12/swap.js",
        "callscore_enabled": false,
        "keyword_spotting_enabled": false,
        "callscribe_enabled": false,
        "lead_scoring_enabled": true,
        "swap_exclude_jquery": null,
        "swap_ppc_override": null,
        "swap_landing_override": null,
        "swap_cookie_duration": 365
    },
    {
        "id": 411892629,
        "name": "Bob's Burger",
        "status": "active",
        "time_zone": "America/New_York",
        "created_at": "2017-06-20T09:30:08.676Z",
        "disabled_at": null,
        "script_url": "//cdn.callrail.com/companies/411892629/1dbf0fc11eabdc04483a/12/swap.js",
        "callscore_enabled": false,
        "keyword_spotting_enabled": false,
        "callscribe_enabled": false,
        "lead_scoring_enabled": true,
        "swap_exclude_jquery": null,
        "swap_ppc_override": null,
        "swap_landing_override": null,
        "swap_cookie_duration": 365
    },
    {
        "id": 785622206,
        "name": "Joe's Icecream",
        "status": "active",
        "time_zone": "America/New_York",
        "created_at": "2016-06-06T07:06:01.000Z",
        "disabled_at": null,
        "script_url": "//cdn.callrail.com/companies/785622206/81fbf538633804b8dea6/12/swap.js",
        "callscore_enabled": false,
        "keyword_spotting_enabled": false,
        "callscribe_enabled": false,
        "lead_scoring_enabled": true,
        "swap_exclude_jquery": null,
        "swap_ppc_override": null,
        "swap_landing_override": null,
        "swap_cookie_duration": 365
    }
  ]
}

This endpoint returns a paginated array of all companies associated with the target account.

API Endpoint

Method URL
GET /v2/a/{account_id}/companies.json

Request Parameters

This endpoint supports Pagination, Sorting, and Filtering.

Sorting is available for the following fields:

Filtering is available for the following:

Searching is available for the following fields:

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id number Unique identifier for the company.
callscore_enabled boolean Whether or not the company has CallScore enabled. See CallScore.
keyword_spotting_enabled boolean Whether or not the company has Keyword Spotting enabled. See Keyword Spotting.
callscribe_enabled boolean Whether or not the company has CallScribe enabled. See CallScribe
created_at string The date and time the company was created in UTC (ISO 8601 format).
disabled_at string The date and time the company was disabled in UTC (ISO 8601 format). If the company is still enabled, this value will be null.
lead_scoring_enabled boolean Whether or not the company has manual lead scoring enabled.
name string Name of the company.
script_url string The URL for the CallRail tracking script for this company. See Dynamic Number Insertion.
status string Indicates whether the company is currently “active” or “disabled”.
swap_cookie_duration integer Cookie duration length in number of days (30, 60, 90, or 365.) Visitors who clear their cookies, return after the cookie expires, or use a different web browser will be treated as new visitors.
swap_exclude_jquery boolean (Deprecated) CallRail’s DNI script no longer requires jQuery; this field is returned for compatibility purposes but has no effect.
swap_landing_override string/null Option to override the original source when a visitor arrives on a landing page containing a given param.
swap_ppc_override boolean Option to override the original source when a visitor arrives via PPC.
time_zone string Time Zone configured for this company.

Additional User Requested Response Fields

Field Selection is available for the following fields.

Name Type Description
verified_caller_ids array An array containing JSON objects of all verified Outbound Caller IDs for this company. Each object has a name and phone_number key/value.

Retrieving a Single Company

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/companies/{company_id}.json"

The above command returns JSON structured object like this:

{
    "id": 183570817,
    "name": "Widget Shop",
    "status": "active",
    "time_zone": "America/New_York",
    "created_at": "2016-06-06T07:06:01.000Z",
    "disabled_at": null,
    "script_url": "//cdn.callrail.com/companies/183570817/5706dbe6dc972c634a65/12/swap.js",
    "callscore_enabled": false,
    "keyword_spotting_enabled": false,
    "callscribe_enabled": false,
    "lead_scoring_enabled": true,
    "swap_exclude_jquery": null,
    "swap_ppc_override": null,
    "swap_landing_override": null,
    "swap_cookie_duration": 365
}

This endpoint returns a single company object associated with the target account.

API Endpoint

Method URL
GET /v2/a/{account_id}/companies/{company_id}.json

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id number Unique identifier for the company.
callscore_enabled boolean Whether or not the company has CallScore enabled. See CallScore.
keyword_spotting_enabled boolean Whether or not the company has Keyword Spotting enabled. See Keyword Spotting.
callscribe_enabled boolean Whether or not the company has CallScribe enabled. See CallScribe
created_at string The date and time the company was created in UTC (ISO 8601 format).
disabled_at string The date and time the company was disabled in UTC (ISO 8601 format). If the company is still enabled, this value will be null.
lead_scoring_enabled boolean Whether or not the company has manual lead scoring enabled.
name string Name of the company.
script_url string The URL for the CallRail tracking script for this company. See Dynamic Number Insertion.
status string Indicates whether the company is currently “active” or “disabled”.
swap_cookie_duration integer Cookie duration length in number of days (30, 60, 90, or 365.) Visitors who clear their cookies, return after the cookie expires, or use a different web browser will be treated as new visitors.
swap_exclude_jquery boolean (Deprecated) CallRail’s DNI script no longer requires jQuery; this field is returned for compatibility purposes but has no effect.
swap_landing_override string/null Option to override the original source when a visitor arrives on a landing page containing a given param.
swap_ppc_override boolean Option to override the original source when a visitor arrives via PPC.
time_zone string Time Zone configured for this company.

Additional User Requested Response Fields

Field Selection is available for the following fields.

Name Type Description
verified_caller_ids array An array containing JSON objects of all verified Outbound Caller IDs for this company. Each object has a name and phone_number key/value.

Creating a Company

curl -H "Authorization: Token token={api_token}" \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{
          "name": "Widget Shop",
          "time_zone": "America/New_York"
         }' \
         "https://api.callrail.com/v2/a/{account_id}/companies.json"

The above command returns JSON structured object like this:

{
  "id": 279054151,
  "name": "Widget Shop",
  "status": "active",
  "time_zone": "America/New_York",
  "created_at": "2017-01-26T22:58:04.184Z",
  "disabled_at": null,
  "script_url": "//cdn.callrail.com/companies/279054151/a74c824140d67442debd/12/swap.js",
  "callscore_enabled": false,
  "keyword_spotting_enabled": false,
  "callscribe_enabled": false,
  "lead_scoring_enabled": false,
  "swap_exclude_jquery": null,
  "swap_ppc_override": null,
  "swap_landing_override": null,
  "swap_cookie_duration": 365
}

This endpoint creates a company object within the target account.

API Endpoint

Method URL
POST /v2/a/{account_id}/companies.json

Request Body

Name Type Required? Description
name string required Company name.
time_zone string optional Time Zone configured for this company. See List of Timezones.

Response Fields

When successful, the HTTP response code will indicate 201 CREATED.

Name Type Description
id number Unique identifier for the company.
name string Name of the company.
status string Indicates whether the company is currently “active” or “disabled”.
time_zone string Time Zone configured for this company.
created_at string The date and time the company was created in UTC (ISO 8601 format).
disabled_at string The date and time the company was disabled in UTC (ISO 8601 format). If the company is still enabled, this value will be null.
script_url string The URL for the CallRail tracking script for this company. See Dynamic Number Insertion.
callscore_enabled boolean Whether or not the company has CallScore enabled. See CallScore.
keyword_spotting_enabled boolean Whether or not the company has Keyword Spotting enabled. See Keyword Spotting.
callscribe_enabled boolean Whether or not the company has CallScribe enabled. See CallScribe
lead_scoring_enabled boolean Whether or not the company has manual lead scoring enabled.
swap_exclude_jquery boolean (Deprecated) CallRail’s DNI script no longer requires jQuery; this field is accepted for compatibility purposes but has no effect.
swap_ppc_override boolean Option to override the original source when a visitor arrives via PPC.
swap_landing_override string/null Option to override the original source when a visitor arrives on a landing page containing a given param.
swap_cookie_duration integer Cookie duration length in number of days (30, 60, 90, or 365.) Visitors who clear their cookies, return after the cookie expires, or use a different web browser will be treated as new visitors.

Updating a Company

curl -H "Authorization: Token token={api_token}" \
     -X PUT \
     -H "Content-Type: application/json" \
     -d '{
          "swap_ppc_override": "true",
          "swap_landing_override": "utm_source",
          "callscribe_enabled": true
         }' \
         "https://api.callrail.com/v2/a/{account_id}/companies/{company_id}.json"

The above command returns JSON structured object like this:

{
  "id": 279054151,
  "name": "Widget Shop",
  "status": "active",
  "time_zone": "America/New_York",
  "created_at": "2017-01-26T22:58:04.184Z",
  "disabled_at": null,
  "script_url": "//cdn.callrail.com/companies/279054151/a74c824140d67442debd/12/swap.js",
  "callscore_enabled": false,
  "keyword_spotting_enabled": false,
  "callscribe_enabled": true,
  "lead_scoring_enabled": false,
  "swap_exclude_jquery": null,
  "swap_ppc_override": true,
  "swap_landing_override": "utm_source",
  "swap_cookie_duration": 365
}

This endpoint updates a company object within the target account.

API Endpoint

Method URL
PUT /v2/a/{account_id}/companies/{company_id}.json

Request Body

Name Type Required? Description
name string optional Company name.
callscore_enabled boolean options Turns the CallScore feature on or off for this company. See CallScore.
keyword_spotting_enabled boolean options Turns the Keyword Spotting feature on or off for this company. See Keyword Spotting.
callscribe_enabled boolean options Turns the CallScribe feature on or off for this company. See CallScribe
time_zone string optional Time Zone configured for this company. See List of Timezones.
swap_exclude_jquery boolean optional (Deprecated) CallRail’s DNI script no longer requires jQuery; this field is accepted for compatibility purposes but has no effect.
swap_ppc_override boolean optional Option to override the original source when a visitor arrives via PPC.
swap_landing_override string/null optional Option to override the original source when a visitor arrives on a landing page containing a given param. To enable, pass a string as the value. To disable, pass null as the value.
swap_cookie_duration integer optional Cookie duration length in number of days (30, 60, 90, or 365.) Visitors who clear their cookies, return after the cookie expires, or use a different web browser will be treated as new visitors.

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id number Unique identifier for the company.
callscore_enabled boolean Whether or not the company has CallScore enabled. See CallScore.
keyword_spotting_enabled boolean Whether or not the company has Keyword Spotting enabled. See Keyword Spotting.
callscribe_enabled boolean Whether or not the company has CallScribe enabled. See CallScribe
created_at string The date and time the company was created in UTC (ISO 8601 format).
disabled_at string The date and time the company was disabled in UTC (ISO 8601 format). If the company is still enabled, this value will be null.
lead_scoring_enabled boolean Whether or not the company has manual lead scoring enabled.
name string Name of the company.
script_url string The URL for the CallRail tracking script for this company. See Dynamic Number Insertion.
status string Indicates whether the company is currently “active” or “disabled”.
swap_exclude_jquery boolean (Deprecated) CallRail’s DNI script no longer requires jQuery; this field is returned for compatibility purposes but has no effect.
swap_ppc_override boolean Option to override the original source when a visitor arrives via PPC.
swap_landing_override string/null Option to override the original source when a visitor arrives on a landing page containing a given param.
swap_cookie_duration integer Cookie duration length in number of days (30, 60, 90, or 365.) Visitors who clear their cookies, return after the cookie expires, or use a different web browser will be treated as new visitors.
time_zone string Time Zone configured for this company.

Additional User Requested Response Fields

Field Selection is available for the following fields.

Name Type Description
verified_caller_ids array An array containing JSON objects of all verified Outbound Caller IDs for this company. Each object has a name and phone_number key/value.

Disabling a Company

curl -H "Authorization: Token token={api_token}" \
     -X DELETE \
     "https://api.callrail.com/v2/a/{account_id}/companies/{company_id}.json"

The above command does not return a JSON response.

This endpoint disables a Company object in the target company. If you disable a company all the tracking phone numbers will be disabled and the swap.js script will be deactivated.

API Endpoint

Method URL
DELETE /v2/a/{account_id}/companies/{company_id}.json

Response

When successful, the HTTP response code will indicate 204 No Content and no JSON response will be returned.

If an Account has only one company, then that company cannot be disabled. Attempting to do this will return the following error message.

{ error: 'You must have at least one active company.' }

Listing All Keyword Spotting Sets

Keyword Spotting gives users the ability to automatically tag, score, and apply a value to calls based on specific sets of words said by the caller or agent. Keyword Spotting can be configured to work with all calls or only ones that meet specific call criteria.

Keyword Spotting is configured independently for each company in your account, and only understands standard English words that can be found in a dictionary. For example, a proper noun like “CallRail” or your business’s name may not be recognized.

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/companies/{company_id}/keyword_spotting_sets.json"

The above command returns a JSON structured object like this:

{
  "keyword_spotting_sets": [
    {
      "speaker": "caller",
      "keywords": ["on sale"],
      "keywords_required": "all",
      "call_criteria": {
        "direction": "inbound",
        "active_pages": ["www.business-as-usual.com"],
        "campaigns": ["email"],
        "referrers": ["www.best-marketing-sites.com"],
        "search_keywords": ["marketing"],
        "sources": ["google_paid"],
        "min_duration": 20,
        "max_duration": 320,
        "landing_pages": ["utm_source=landing"]
      },
      "actions": {
        "lead_status": "lead",
        "tags": ["email"],
        "value": "1.02"
      }
    },
    {
      "speaker": "any",
      "keywords": ["appointment", "referral"],
      "keywords_required": "any",
      "not_said_keywords": ["cancel"],
      "not_said_keywords_required": "any",
      "call_criteria": {
        "sources": ["yahoo_paid"]
      },
      "actions": {
        "tags": ["business"],
        "value": "24.70"
      }
    }
  ]
}

API Endpoint

This endpoint returns an array of Keyword Spotting sets currently configured for the target company.

Method URL
GET /v2/a/{account_id}/companies/{company_id}/keyword_spotting_sets.json

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
keyword_spotting_sets array An array of Keyword Spotting sets.

Keyword Spotting Set Fields

All of the Keyword Spotting sets within a target company. These are listed in a JSON array.

Name Type Description
speaker string The person whose keywords you are listening for. Choose from “caller" or “agent" or “any".
keywords array The keywords you are listening for listed in a JSON array.
keywords_required string The keywords that must be spotted in order for actions to be taken. Choose from “any” or “all”.
not_said_keywords array The keywords the speaker does not say, listed in a JSON array.
not_said_keywords_required string The keywords that must be omitted in order for actions to be taken. Choose from “any” or “all”.
call_criteria object The call criteria that must be met for an action to be taken on the call. These are listed in a JSON object and include “direction”, “active_pages”, “campaigns”, “referrers”, “search_keywords”, “sources”, “min_duration”, “max_duration”, and “landing_pages”.
actions object The action that should be taken once a keyword is spotted. These are listed in a JSON object and include “lead_status”, “tags”, and “value”.

Call Criteria Fields

The fields list below apply to the “call_criteria” JSON object and are all optional. Keyword Spotting sets can be configured so that any of the criteria listed must be met in order for keywords to be spotted in calls.

Name Type Description
direction string The direction of the call. Choose from “inbound” or “outbound”.
active_pages array The URL of the active page at the time of the call. These URLs are listed in a JSON array.
campaigns array The campaigns assigned to the tracking number used in the call. These titles are listed in a JSON array.
referrers array The referring URLs that that led to the call. These URLs are listed in a JSON array.
search_keywords array The keywords you are bidding on that led to the call. These keywords are listed in a JSON array.
sources array The specific referring source that led to a call. These are listed in a JSON array and include “google_paid”, “bing_paid”, “yahoo_paid”, “ppc_search”, “google_organic”, “bing_organic”, “yahoo_organic”, “organic_search”, and “direct”
min_duration integer The minimum amount of time that the call must have lasted for an action to be applied. This is listed in seconds.
max_duration integer The maximum amount of time that the call must have lasted for keywords to be spotted. This is listed in seconds.
landing_pages array The landing pages on your website that led to the call. These are either URLs or UTM Parameters listed in a JSON array

Action Fields

The fields list below apply to the (action) JSON object. Keyword Spotting sets can be configured so that if all keyword and call criteria is met, specific actions can then be taken.

Name Type Description
lead_status string Mark this caller with a specific lead status. Choose from “lead” and “not_a_lead”.
tags array Apply specific tags to the call. These tags are listed in a JSON array.
value string Apply a specific value to the call. This value is a float number listed as a string.

Updating all Keyword Spotting Sets

curl -H "Authorization: Token token={api_token}" \
     -X PUT \
     -H "Content-Type: application/json" \
     -d '{
          "keyword_spotting_sets": [
            {
              "speaker": "caller",
              "keywords": ["on sale"],
              "keywords_required": "all",
              "call_criteria": {
                "direction": "inbound",
                "active_pages": ["www.business-as-usual.com"],
                "campaigns": ["email"],
                "referrers": ["www.best-marketing-sites.com"],
                "search_keywords": ["marketing"],
                "sources": ["google_paid"],
                "min_duration": 20,
                "max_duration": 320,
                "landing_pages": ["utm_source=landing"]
              },
              "actions": {
                "lead_status": "lead",
                "tags": ["email"],
                "value": "1.02"
              }
            },
            {
              "speaker": "any",
              "keywords": ["appointment", "referral"],
              "keywords_required": "any",
              "not_said_keywords": ["cancel"],
              "not_said_keywords_required": "any",
              "call_criteria": {
                "sources": ["yahoo_paid"]
              },
              "actions": {
                "tags": ["business"],
                "value": "24.70"
              }
            }
          ]
        }' \
        "https://api.callrail.com/v2/a/{account_id}/companies/{company_id}/keyword_spotting_sets.json"

The above command returns JSON structured object like this:

{
  "keyword_spotting_sets": [
    {
      "speaker": "caller",
      "keywords": ["on sale"],
      "keywords_required": "all",
      "call_criteria": {
        "direction": "inbound",
        "active_pages": ["www.business-as-usual.com"],
        "campaigns": ["email"],
        "referrers": ["www.best-marketing-sites.com"],
        "search_keywords": ["marketing"],
        "sources": ["google_paid"],
        "min_duration": 20,
        "max_duration": 320,
        "landing_pages": ["utm_source=landing"]
      },
      "actions": {
        "lead_status": "lead",
        "tags": ["email"],
        "value": "1.02"
      }
    },
    {
      "speaker": "any",
      "keywords": ["appointment", "referral"],
      "keywords_required": "any",
      "not_said_keywords": ["cancel"],
      "not_said_keywords_required": "any",
      "call_criteria": {
        "sources": ["yahoo_paid"]
      },
      "actions": {
        "tags": ["business"],
        "value": "24.70"
      }
    }
  ]
}

This endpoint allows you to replace the current Keyword Spotting set configuration in a target company.

API Endpoint

Method URL
PUT /v2/a/{account_id}/companies/{company_id}/keyword_spotting_sets.json

Request Body

Name Type Required? Description
keyword_spotting_sets array required All of the Keyword Spotting sets within a target company. These are listed in a JSON array.

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
keyword_spotting_sets array Field inputs may be adjusted when the request is made in order to meet validation.

Keyword Spotting Set Fields

All of the Keyword Spotting sets within a target company. These are listed in a JSON array.

Name Type Required? Description
speaker string required The person whose keywords you are listening for. Choose from “caller" or “agent" or “any".
keywords array required The keywords you are listening for listed in a JSON array. Not required if not_said_keywords are specified instead.
keywords_required string optional The keywords that must be spotted in order for actions to be taken. Choose from “any” or “all”.
not_said_keywords array optional The keywords the speaker does not say, listed in a JSON array.
not_said_keywords_required string optional The keywords that must be omitted in order for actions to be taken. Choose from “any” or “all”.
call_criteria object optional The call criteria that must be met for an action to be taken on the call. These are listed in a JSON object and include “direction”, “active_pages”, “campaigns”, “referrers”, “search_keywords”, “sources”, “min_duration”, “max_duration”, and “landing_pages”.
actions object optional The action that should be taken once a keyword is spotted. These are listed in a JSON object and include “lead_status”, “tags”, and “value”.

Call Criteria Fields

The fields list below apply to the “call_criteria” JSON object and are all optional. Keyword Spotting sets can be configured so that any of the criteria listed must be met in order for keywords to be spotted in calls.

Name Type Required? Description
direction string optional The direction of the call. Choose from “inbound” or “outbound”.
active_pages array optional The URL of the active page at the time of the call. These URLs are listed in a JSON array.
campaigns array optional The campaigns assigned to the tracking number used in the call. These titles are listed in a JSON array.
referrers array optional The referring URLs that that led to the call. These URLs are listed in a JSON array.
search_keywords array optional The keywords you are bidding on that led to the call. These keywords are listed in a JSON array.
sources array optional The specific referring source that led to a call. These are listed in a JSON array and include “google_paid”, “bing_paid”, “yahoo_paid”, “ppc_search”, “google_organic”, “bing_organic”, “yahoo_organic”, “organic_search”, and “direct”
min_duration integer optional The minimum amount of time that the call must have lasted for an action to be applied. This is listed in seconds.
max_duration integer optional The maximum amount of time that the call must have lasted for keywords to be spotted. This is listed in seconds.
landing_pages array optional The landing pages on your website that led to the call. These are either URLs or UTM Parameters listed in a JSON array

Action Fields

The fields list below apply to the (action) JSON object. Keyword Spotting sets can be configured so that if all keyword and call criteria is met, specific actions can then be taken.

Name Type Required? Description
lead_status string optional Mark this caller with a specific lead status. Choose from “lead” and “not_a_lead”.
tags array optional Apply specific tags to the call. These tags are listed in a JSON array.
value string optional Apply a specific value to the call. This value is a float number listed as a string.

Form Submissions

If you’ve included the dynamic number insertion script in your website and have form tracking enabled for your company in the CallRail application, this endpoint allows you programmatic access to those form submissions.

Listing All Form Submissions

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/form_submissions.json"

The above command return JSON structured object like this:

{
    "page": 1,
    "per_page": 2,
    "total_pages": 75,
    "total_records": 150,
    "form_submissions": [
        {
            "id": 836820748,
            "company_id": 285368250,
            "person_id": "anonymous",
            "form_data": {
                "name": "Graham Armstrong",
                "email": "graham@example.com",
                "phone": "(999) 999-9999",
                "contact_method": "call",
                "best_time_to_call": "evening"
            },
            "form_url": "http://www.uptowndental.com/overview?adposition=1s3&matchtype=b&network=g",
            "landing_page_url": "http://www.uptowndental.com/contact?adposition=1s3&matchtype=e&network=g",
            "referrer": "google_paid",
            "referring_url": "http://www.google.com/aclk?q=default plain test",
            "submitted_at": "2017-11-17T07:46:28.000Z",
            "first_form": false
        },
        {
            "id": 187914696,
            "company_id": 285368250,
            "person_id": 377128794,
            "form_data": {
                "name": "Veronica Auer",
                "email": "veronica.auer@example.com",
                "phone": "888-888-8888",
                "contact_method": "email",
                "best_time_to_call": "evening"
            },
            "form_url": "http://www.uptowndental.com/contact?network=g",
            "landing_page_url": "http://www.uptowndental.com/pricing?network=g",
            "referrer": "google_organic",
            "referring_url": "http://www.google.com/url",
            "submitted_at": "2017-12-02T12:30:09.000Z",
            "first_form": false
        }
    ]
}

This endpoint returns a paginated array of all form submissions associated with the target account.

API Endpoint

Method URL
GET /v2/a/{account_id}/form_submissions.json

Request Parameters

This endpoint supports Pagination, Sorting, Filtering, and Field Selection

Sorting is available for the following fields:

Filtering is available for the following categories:

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id number Unique identifier for the form submission.
company_id number Unique identifier for the company associated with the form submission.
person_id number Unique identifier for the person associated with the form submission.
form_data object Object that captures all of the form fields and values
form_url string The URL that the form was submitted to
landing_page_url string The URL that the user landed on from the referring entity
referrer string Name of the referring entity, e.g. google_paid.
referring_url string URL for the referring entity
submitted_at timestamp Server time when the form was submitted. This is assigned by the CallRail app.
first_form boolean Indicates whether this is the first form submitted from a person.

Additional User Requested Response Fields

Field Selection is available for the following fields.

Name Type Description
lead_status string The current lead status for the form submission. One of good_lead, not_a_lead, previously_marked_good_lead, or null.

Creating a form submission

curl -H "Authorization: Token token={api_token}" \
       -X POST \
     -H "Content-Type: application/json" \
     -d '{
          "form_submission": {
            "company_id": 339960693,
            "referrer": "wikipedia_link",
            "referring_url": "wikipedia.org/wiki/Carmen_Sandiego",
            "landing_page_url": "missingmonuments.com/info",
            "form_url": "missingmonuments.com/report/new",
            "form_data": {
              "phone_number": "5555555555",
              "report": "Carmen stole the Liberty Bell.",
              "last_sighting": "Near Washington D.C."
            }
          }
        }' \
        "https://api.callrail.com/v2/a/{account_id}/form_submissions.json"

The above command returns JSON structured object like this:

{
    "id": 917498039,
    "company_id": 339960693,
    "person_id": 337413662,
    "form_data": {
        "phone_number": "5555555555",
        "report": "Carmen stole the Liberty Bell.",
        "last_sighting": "Near Washington D.C."
    },
    "form_url": "missingmonuments.com/report/new",
    "landing_page_url": "missingmonuments.com/info",
    "referrer": "wikipedia_link",
    "referring_url": "wikipedia.org/wiki/Carmen_Sandiego",
    "submitted_at": "2018-02-13T17:03:33.018Z",
    "first_form": false
}

You can use the API to create form submissions for a given company. The app will attempt to parse out any phone numbers in the form data, and use that phone number to create or find a customer to associate with the form submission.

API Endpoint

Method URL
POST /v2/a/{account_id}/form_submissions.json

Request Body

Name Type Description
company_id number Unique identifier for the company associated with the form submission.
referrer string Name of the referring entity, e.g. google_paid.
referring_url string URL for the referring entity
landing_page_url string The page that user landed on from the referring entity
form_url string The URL that the form was submitted to
form_data object Object that captures all of the form fields and values

Response Fields

When successful, the HTTP response code will indicate 201 Created.

Name Type Description
id number Unique identifier for the form submission.
company_id number Unique identifier for the company associated with the form submission.
person_id number Unique identifier for the person associated with the form submission.
form_data object Object that captures all of the form fields and values
form_url string The URL that the form was submitted to
landing_page_url string The page that user landed on from the referring entity
referrer string Name of the referring entity, e.g. google_paid.
referring_url string URL for the referring entity
submitted_at timestamp Server time when the form was submitted. This is assigned by the CallRail app.
first_form boolean Indicates whether this is the first form submitted from a person.

Integrations

An integration in CallRail is a resource that can be used to facilitate communication between CallRail and third-party services. Customers can utilize ‘Webhook’ integrations to send data from CallRail to outside sources, and 'Custom’ integrations to capture custom cookie data from web visitors and associate it with calls in CallRail. A single company in CallRail can have one of each integration type.

Listing All Integrations

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/integrations.json?company_id=213472384"

The above command returns a JSON structured object like this:

{
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_records": 3,
  "integrations": [
    {
      "id": 5,
      "config": {
        "api_key": "12345"
      },
      "state": "disabled",
      "type": "GoogleAnalytics"
    },
    {
      "id": 10,
      "config": {
        "api_key": "12345"
      },
      "state": "active",
      "type": "Slack"
    },
    {
      "id": 4,
      "config": {
        "pre_call_webhook": ["http://example.com/webhook.php"]
      },
      "state": "active",
      "type": "Webhooks"
    }
  ]
}

This endpoint returns a paginated array of all Integrations within the target company.

API Endpoint

Method URL
GET /v2/a/{account_id}/integrations.json

Request Parameters

This endpoint supports Pagination.

Name Type Required? Description
company_id integer required Ensures results contain integrations belonging to a single company.

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id integer Unique identifier for the integration object.
type string The type of integration represented by the object.
state string The current state of the integrations. One of “active”, “disabled”, “pending”, or “failed”.
config object An object containing specific information about the configuration for the integration. The contents of this object will vary depending on the integration type.

Retrieving a Single Integration

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/integrations/{integration_id}.json"

The above command returns JSON structured object like this:

{
  "id": 4,
  "config": {
    "pre_call_webhook": ["http://example.com/webhook.php"]
  },
  "state": "active",
  "type": "Webhooks"
}

This endpoint returns a single Integration object in the target company.

API Endpoint

Method URL
GET /v2/a/{account_id}/integrations/{integration_id}.json

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id integer Unique identifier for the integration object.
type string The type of integration represented by the object.
state string The current state of the integrations. One of “active”, “disabled”, “pending”, or “failed”.
config object An object containing specific information about the configuration for the integration. The contents of this object will vary depending on the integration type.

Creating an Integration

curl -H "Authorization: Token token={api_token}" \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{
          "type": "Webhooks",
          "company_id": 213472384,
          "config": {
            "pre_call_webhook": ["http://example.com/webhook.php"]
          }
        }' \
         "https://api.callrail.com/v2/a/{account_id}/integrations.json"

The above command returns JSON structured object like this:

{
  "id": 4,
  "config": {
    "pre_call_webhook": ["http://example.com/webhook.php"]
  },
  "state": "active",
  "type": "Webhooks"
}

You can use the API to create and activate a new instance of an integration for a company. A company may only have a single integration of a given type. Currently the only types that can be created via the API are ‘Webhooks’ and 'Custom’ integrations.

API Endpoint

Method URL
POST /v2/a/{account_id}/integrations.json

Request Body

Name Type Description
company_id integer Unique identifier for the integration object.
type string The type of integration represented by the object. One of “Webhooks” or “Custom”.
config object An object containing specific information about the configuration for the integration. The contents of this object will vary depending on the integration type. See the documentation for Integration Configuration.

Response Fields

When successful, the HTTP response code will indicate 201 Created.

Name Type Description
id integer Unique identifier for the integration object.
type string The type of integration represented by the object.
state string The current state of the integrations. One of “active”, “disabled”, “pending”, or “failed”.
config object An object containing specific information about the configuration for the integration. The contents of this object will vary depending on the integration type.

Updating an Integration

curl -H "Authorization: Token token={api_token}" \
     -X PUT \
     -H "Content-Type: application/json" \
     -d '{
          "state": "active",
          "config": {
            "pre_call_webhook": ["http://example.com/webhook.php"]
          }
         }' \
         "https://api.callrail.com/v2/a/{account_id}/integrations/{integration_id}.json"

The above command activates an existing integration and updates the configuration.

{
  "id": 4,
  "config": {
    "pre_call_webhook": ["http://example.com/webhook.php"]
  },
  "state": "active",
  "type": "Webhooks"
}

API Endpoint

Method URL
PUT v2/a/{account_id}/integrations/{integration_id}.json

Request Body

Name Type Description
state string A valid integration state. One of “active”, or “disabled”.
config object An object containing specific information about the configuration for the integration. The contents of this object will vary depending on the integration type. See the documentation for Integration Configuration.

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id integer Unique identifier for the integration object.
type string The type of integration represented by the object.
state string The current state of the integrations. One of “active”, “disabled”, “pending”, or “failed”.
config object An object containing specific information about the configuration for the integration. The contents of this object will vary depending on the integration type.

Disabling an Integration

curl -H "Authorization: Token token={api_token}" \
     -X DELETE \
     "https://api.callrail.com/v2/a/{account_id}/integrations/{integration_id}.json"

The above command does not return a JSON response.

This endpoint disables an Integration object in the target company.

API Endpoint

Method URL
DELETE /v2/a/{account_id}/integrations/{integration_id}.json

Response Fields

When successful, the HTTP response code will indicate 204 No Content and no JSON response will be returned.

Configuring Integrations

Integration Configuration Object

Each Integration type has it’s own specific configuration format. When creating or updating an integration via the API, you should provide the appropriate configuration format for that integration type.

Webhook Configuration Object

When creating a Webhooks Integration, the fields below may be provided in the config object. Each field accepts an array of valid URLs.

Example: [“https://example.com/pre-call.php”, “http://zapier.com/zaps/123”]

Name Type Required? Description
pre_call_webhook array optional List of URLs to be notified when a call is incoming.
post_call_webhook array optional List of URLs to be notified after a call is completed.
updated_call_webhook array optional List of URLs to be notified when a call’s note or tag is changed.
sms_received_webhook array optional List of URLs to be notified when a text message is received.
form_captured_webhook array optional List of URLs to be notified when a Form Submission is received.
post_outbound_call_webhook array optional List of URLs to be notified when an outbound call is completed.
updated_outbound_call_webhook array optional List of URLs to be notified when an outbound call’s note or tag is changed.

When creating a Custom Cookie Capture Integration, the field below should be provided in the config object. This field accepts an array of cookie names.

Example: [“_ga”, “mycookie31”]

Name Type Required? Description
grab_cookies array required List of cookie names to associate with user sessions.

Integration Triggers

Integration triggers are filter criteria that can be applied to integrations to limit the kinds of data or events that are shipped to third-party services. For more details on integrations, see the API docs or support documentation.

Each integration can have a single associated integration trigger. Since integration triggers reduce or scope the data for external integrations, they must be associated with an existing active integration. Accordingly, the integration will be sideloaded when displaying the integration triggers as JSON.

An optional default integration trigger can be defined for a company. This default trigger applies to all integrations that do not have a specific integration trigger defined. If an integration trigger is specified for an integration, it will override the default trigger settings for that integration.

The individual attributes of integration triggers are additive; that is, creating a trigger for first calls longer than 10s will only trigger integrations for calls that match both attributes. A null value on an integration trigger attribute indicates that attribute is not being used as a filter criteria.

Listing All Integration Triggers

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/integration_triggers.json?company_id=213472384"

The above command returns a JSON structured object like this:

{
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_records": 3,
  "integration_criteria": [
    {
      "id": 2,
      "company_id": 279238462,
      "integration_id": null,
      "tracker_ids": [],
      "call_type": null,
      "min_duration": null,
      "max_duration": null,
      "lead_status": 1,
      "integration": {
        "id": null,
        "type": "All (Default Integration Trigger)"
      }
    },
    {
      "id": 26,
      "company_id": 213472384,
      "integration_id": 219,
      "tracker_ids": [346823746],
      "call_type": null,
      "min_duration": 1,
      "max_duration": 11,
      "lead_status": null,
      "integration": {
        "id": 219,
        "type": "Custom"
      }
    },
    {
      "id": 34,
      "company_id": 213472384,
      "integration_id": 247,
      "tracker_ids": [203891483],
      "call_type": "first_call",
      "min_duration": 3,
      "max_duration": null,
      "lead_status": null,
      "integration": {
        "id": 247,
        "type": "Webhooks"
      }
    }
  ]
}

This endpoint returns a paginated array of all the integration triggers and their associated integrations.

API Endpoint

Method URL
GET /v2/a/{account_id}/integration_triggers.json

Request Parameters

This endpoint supports Pagination.

Name Type Required? Description
company_id integer required Ensures results contain integration triggers and integrations belonging to a single company.

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id integer Unique identifier for the integration trigger object.
company_id integer The integration trigger is associated with the company with this unique id.
integration_id integer The integration trigger is associated with the integration with this unique id.
tracker_ids array(integers) The integration trigger is scoped to the tracker ids present in this array.
call_type string The type of calls which will activate the integration trigger. Can be one of: null, first_call, vm, missed_and_vm, where vm indicates voicemail.
min_duration integer The minimum duration in seconds that will activate the integration trigger.
max_duration integer The maximum duration in seconds that will activate the integration trigger.
lead_status integer The lead status that will activate the integration trigger. Can be either good_lead or not_a_lead.
integration object An object describing the attributes of the integration associated with the integration trigger.

Creating an Integration Trigger

curl -H "Authorization: Token token={api_token}" \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{
          "company_id": 213472384,
          "integration_id": 219,
          "tracker_ids": [203891483],
          "call_type": null,
          "min_duration": 1,
          "max_duration": 11,
          "lead_status": null,
          }
        }' \
         "https://api.callrail.com/v2/a/{account_id}/integration_triggers.json"

The above command returns a JSON object like this:

{
  "id": 34,
  "company_id": 213472384,
  "integration_id": 219,
  "tracker_ids": [203891483],
  "call_type": "first_call",
  "min_duration": 3,
  "max_duration": null,
  "lead_status": null,
  "integration": {
    "id": 219,
    "type": "Webhooks"
  }
}

You can use the API to create a single integration trigger for each integration. Not every type of integration can be configured with a trigger; the API will return a helpful error in those cases indicating the incompatibility.

API Endpoint

Method URL
POST /v2/a/{account_id}/integration_triggers.json

Request Body

Name Type Description
company_id integer The integration trigger is associated with the company with this unique id.
integration_id integer The integration trigger is associated with the integration with this unique id.
tracker_ids array(integers) The integration trigger is scoped to the tracker ids present in this array.
call_type string The type of calls which will activate the integration trigger. Can be one of: null, first_call, vm, missed_and_vm. (vm => voicemail)
min_duration integer The minimum duration in seconds that will activate the integration trigger.
max_duration integer The maximum duration in seconds that will activate the integration trigger.
lead_status integer The lead status that will activate the integration trigger. Can be either good_lead or not_a_lead.

Response Fields

When successful, the HTTP response code will indicate 201 Created.

Name Type Description
id integer Unique identifier for the integration trigger object.
company_id integer The integration trigger is associated with the company with this unique id.
integration_id integer The integration trigger is associated with the integration with this unique id.
tracker_ids array(integers) The integration trigger is scoped to the tracker ids present in this array.
call_type string The type of calls which will activate the integration trigger. Can be one of: null, first_call, vm, missed_and_vm, where vm indicates voicemail.
min_duration integer The minimum duration in seconds that will activate the integration trigger.
max_duration integer The maximum duration in seconds that will activate the integration trigger.
lead_status integer The lead status that will activate the integration trigger. Can be either good_lead or not_a_lead.
integration object An object describing the attributes of the integration associated with the integration trigger.

The API will return 400 Bad Request with a helpful message if a integration trigger already exists when attempting to create a new trigger for a given integration.

Retrieving a Single Integration Trigger

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/integration_triggers/{integration_trigger_id}.json"

The above command returns JSON structured object like this:

{
      "id": 34,
      "company_id": 213472384,
      "integration_id": 247,
      "tracker_ids": [203891483],
      "call_type": "first_call",
      "min_duration": 3,
      "max_duration": null,
      "lead_status": null,
      "integration": {
        "id": 247,
        "type": "Webhooks"
      }
    }

This endpoint returns a single Integration object in the target company.

API Endpoint

Method URL
GET /v2/a/{account_id}/integration_triggers/{integration_triggers_id}.json

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id integer Unique identifier for the integration trigger object.
company_id integer The integration trigger is associated with the company with this unique id.
integration_id integer The integration trigger is associated with the integration with this unique id.
tracker_ids array(integers) The integration trigger is scoped to the tracker ids present in this array.
call_type string The type of calls which will activate the integration trigger. Can be one of: null, first_call, vm, missed_and_vm, where vm indicates voicemail.
min_duration integer The minimum duration in seconds that will activate the integration trigger.
max_duration integer The maximum duration in seconds that will activate the integration trigger.
lead_status integer The lead status that will activate the integration trigger. Can be either good_lead or not_a_lead.
integration object An object describing the attributes of the integration associated with the integration trigger.

Updating an Integration Trigger

curl -H "Authorization: Token token={api_token}" \
     -X PUT \
     -H "Content-Type: application/json" \
     -d '{
          "call_type": "vm",
          "min_duration": 10
         }' \
         "https://api.callrail.com/v2/a/{account_id}/integration_triggers/{integration_trigger_id}.json"

The above command updates an existing integration trigger

{
  "id": 34,
  "company_id": 213472384,
  "integration_id": 219,
  "tracker_ids": [203891483],
  "call_type": "vm",
  "min_duration": 10,
  "max_duration": null,
  "lead_status": null,
  "integration": {
    "id": 219,
    "type": "Webhooks"
  }
}

API Endpoint

Method URL
PUT v2/a/{account_id}/integration_triggers/{integration_trigger_id}.json

Request Body

Name Type Description
tracker_ids array(integers) The integration trigger is scoped to the tracker ids present in this array.
call_type string The type of calls which will activate the integration trigger. Can be one of: null, first_call, vm, missed_and_vm. (vm => voicemail)
min_duration string The minimum duration in seconds that will activate the integration trigger.
max_duration string The maximum duration in seconds that will activate the integration trigger.
lead_status integer The lead status that will activate the integration trigger. Can be either good_lead or not_a_lead.

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id integer Unique identifier for the integration trigger object.
company_id integer The integration trigger is associated with the company with this unique id.
integration_id integer The integration trigger is associated with the integration with this unique id.
tracker_ids array(integers) The integration trigger is scoped to the tracker ids present in this array.
call_type string The type of calls which will activate the integration trigger. Can be one of: nil, first_call, vm, missed_and_vm, where vm indicates voicemail.
min_duration string The minimum duration in seconds that will activate the integration trigger.
max_duration string The maximum duration in seconds that will activate the integration trigger.
lead_status integer The lead status that will activate the integration trigger. Can be either good_lead or not_a_lead.
integration object An object describing the attributes of the integration associated with the integration trigger.

Deleting an Integration Trigger

curl -H "Authorization: Token token={api_token}" \
     -X DELETE \
     "https://api.callrail.com/v2/a/{account_id}/integration_triggers/{integration_trigger_id}.json"

The above command does not return a JSON response.

This endpoint deletes an integration trigger object in the target company. The integration will continue to function as configured, without any scoping of

API Endpoint

Method URL
DELETE /v2/a/{account_id}/integration_triggers/{integration_triggers_id}.json

Response Fields

When successful, the HTTP response code will indicate 204 No Content and no JSON response will be returned.

Notifications

The notifications endpoint configures user alerts sent on incoming calls and text messages. Each notification record is set for a specific user, and is limited to either a specific tracker, all trackers in a company, or all trackers in the target account. Each record indicates if it is active for calls, text messages, or both. Finally, each record indicates one or more notification channels: email, push notifications to mobile devices, or browser-based desktop notifications.

For notification records configured for calls, the alerts can be further filtered by type of call. Users can opt to receive notifications for all calls, only for first-time callers, only for voicemails, or for voicemails and missed calls.

Listing All Notifications

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     -d '{
          "user_id" : 351665079
        }' \
        "https://api.callrail.com/v2/a/{account_id}/notifications.json"

The above command returns a JSON structured object like this:

{
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_records": 2,
  "notifications": [
    {
      "id": 100,
      "user_id": 351665079,
      "alert_type": "all",
      "call_enabled": true,
      "company_id": 716361862,
      "name": "All Calls and All Texts for Katherine's Ice Cream",
      "send_desktop": false,
      "send_email": true,
      "send_push": false,
      "sms_enabled": true,
      "tracker_id": null
    },
    {
      "id": 101,
      "user_id": 351665079,
      "alert_type": "all",
      "call_enabled": true,
      "company_id": 716361862,
      "name": "All Calls and All Texts for Google Organic",
      "send_desktop": false,
      "send_email": true,
      "send_push": true,
      "sms_enabled": true,
      "tracker_id": 971427260
    }
  ]
}

This endpoint returns a paginated array of notifications within the target account.

API Endpoint

Method URL
GET /v2/a/{account_id}/notifications.json

Request Parameters

This endpoint supports Pagination.

Request Body

Name Type Required? Description
user_id number Required List notifications for the specified user.

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id number Unique identifier for the notification.
user_id number Unique identifier for the user configured to receive these notifications.
alert_type string When call alerts are enabled, applies a filter for alerts based on call type. One of “all”, “first_call”, “missed_and_vm”, “vm_only”.
call_enabled boolean Whether or not call alerts are enabled.
company_id number This notification is limited to this specific company. If null, this notification applies for all companies within the account.
name string Describes the configuration setup of the notification.
send_desktop boolean Whether or not the notifications will be sent via the desktop web application.
send_email boolean Whether or not the notifications will be sent via email.
send_push boolean Whether or not the notifications will be sent via mobile push notification.
sms_enabled boolean Whether or not alerts are enabled for incoming text messages.
tracker_id number This notification is limited to this specific tracker. If null, this notification applies for all trackers.

Creating a Notification

curl -H "Authorization: Token token={api_token}" \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{
          "user_id": 152563331,
          "tracker_id" : 351665079,
          "send_email" : true,
          "send_push" : true,
          "send_desktop" : true,
          "alert_type" : "vm_only",
          "sms_enabled" : true,
          "call_enabled" : true
        }' \
        "https://api.callrail.com/v2/a/{account_id}/notifications.json"

The above command returns JSON structured object like this:

{
  "id": 127,
  "user_id": 152563331,
  "alert_type": "vm_only",
  "call_enabled": true,
  "company_id": 548387638,
  "company_name": "Katherine's Ice Cream",
  "send_desktop": true,
  "send_email": true,
  "send_push": true,
  "sms_enabled": true,
  "tracker_id": 351665079,
  "tracker_name": "Google Organic"
}

Creating a notification configures an alert to be sent to the specified user for specific events within CallRail. Users can configure as many notifications as necessary using the available filtering and configuration options provided.

API Endpoint

Method URL
POST /v2/a/{account_id}/notifications.json

Request Body

Name Type Required? Description
user_id number Required The user to receive these notifications.
company_id number Optional Limit this notification to the specified company. If not specified, this notification is not limited by company.
tracker_id number Optional Limit this notification to the specified tracker. If not specified, this notification is not limited by tracker.
call_enabled boolean Optional Whether or not notifications are enabled for incoming calls. When enabled, alert_type becomes required.
sms_enabled boolean Optional Whether or not notifications are enabled for incoming text messages.
alert_type string Optional Selects the type of call that triggers this notification. One of “all”, “first_call”, “missed_and_vm”, “vm_only”. Required when call_enabled is true.
send_desktop boolean Optional Whether or not notifications will be sent via the desktop web application.
send_email boolean Optional Whether or not notifications will be sent via email.
send_push boolean Optional Whether or not notifications will be sent via mobile push notification.

Response Fields

When successful, the HTTP response code will indicate 201 Created.

Name Type Description
id number Unique identifier for the notification.
user_id number Unique identifier for the user configured to receive these notifications.
alert_type string When call alerts are enabled, applies a filter for alerts based on call type. One of “all”, “first_call”, “missed_and_vm”, “vm_only”.
call_enabled boolean Whether or not call alerts are enabled.
company_id number This notification is limited to this specific company. If null, this notification applies for all companies within the account.
company_name string Name of the configured company, if specified.
name string Describes the configuration setup of the notification.
send_desktop boolean Whether or not the notifications will be sent via the desktop web application.
send_email boolean Whether or not the notifications will be sent via email.
send_push boolean Whether or not the notifications will be sent via mobile push notification.
sms_enabled boolean Whether or not alerts are enabled for incoming text messages.
tracker_id number This notification is limited to this specific tracker. If null, this notification applies for all trackers.
tracker_name string Name of the configured tracker, if specified.

Removing a Notification

curl -H "Authorization: Token token={api_token}" \
     -X DELETE \
     "https://api.callrail.com/v2/a/{account_id}/notifications/{notification_id}.json"

The above command does not return a JSON response.

This endpoint will delete a notification.

API Endpoint

Method URL
DELETE /v2/a/{account_id}/notifications/{notification_id}.json

Response

When successful, the HTTP response code will indicate 204 No Content and no JSON response will be returned.

If the specified notification is not managed by the current authorized user, the response will be 403 Forbidden with the following error message.

{ "error" => "You do not have permission to perform the requested action" }

Outbound Caller IDs

When you make an outbound call through CallRail, you can choose any of your active tracking numbers to appear on the recipient’s caller ID. We also provide an option to show non-CallRail tracking numbers for caller ID. Before another number can be used for caller ID, you must verify that you own that phone number. This endpoint allows you to register external phone numbers and trigger verification calls to confirm ownership.

Listing All Outbound Caller ID’s

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/caller_ids.json?company_id=213472384"

The above command returns a JSON structured object like this:

{
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_records": 2,
  "caller_ids": [
    {
      "id": 13,
      "phone_number": "+14043334455",
      "name": "Bob's Cell",
      "verified": true,
      "created_at": "2016-08-26T09:29:00.198-04:00",
      "validation_code": "906053"
    },
    {
      "id": 14,
      "phone_number": "+14043345566",
      "name": "Gene's Cell",
      "verified": true,
      "created_at": "2016-08-26T09:29:00.198-04:00",
      "validation_code": "916054"
    }
  ]
}

This endpoint returns a paginated array of all Outbound Caller ID’s within the target company.

API Endpoint

Method URL
GET /v2/a/{account_id}/caller_ids.json

Request Parameters

This endpoint supports Pagination.

Name Type Required? Description
company_id integer required If provided, only the caller IDs to belonging to this company will be returned.

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id integer Unique identifier for the Outbound Caller ID object.
phone_number string The telephone number (in e.164 format) of the Outbound Caller ID object.
name string A descriptive name of the Caller ID formatted for display.
company_id integer Unique identifier for the company.
verified boolean Whether or not the phone number has been verified in CallRail.
created_at string The date and time the Outbound Caller ID was created in UTC (ISO 8601 format).
validation_code string Code needed to verify ownership of the phone number to be used with the Outbound Caller ID feature.

Retrieving a Single Outbound Caller ID

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/caller_ids/{caller_ids_id}.json

The above command returns JSON structured object like this:

{
  "id": 10,
  "phone_number": "+17704445555",
  "name": "Bob's Cell",
  "verified": true,
  "created_at": "2015-04-17T11:02:36.461-04:00",
  "validation_code": "332377"
}

This endpoint returns a single Outbound Caller ID object in the target company.

API Endpoint

Method URL
GET /v2/a/{account_id}/caller_ids/{caller_ids_id}.json

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id integer Unique identifier for the Outbound Caller ID object.
phone_number string The telephone number (in e.164 format) of the Outbound Caller ID object.
name string A descriptive name of the Caller ID formatted for display.
company_id integer Unique identifier for the company.
verified boolean Whether or not the phone number has been verified in CallRail.
created_at string The date and time the Outbound Caller ID was created in UTC (ISO 8601 format).
validation_code string Code needed to verify ownership of the phone number to be used with the Outbound Caller ID feature.

Creating an Outbound Caller ID

curl -H "Authorization: Token token={api_token}" \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{
          "phone_number": "+14047704070",
          "name": "Widget Shop",
          "company_id": 213472384
         }' \
         "https://api.callrail.com/v2/a/{account_id}/caller_ids.json"

The above command returns JSON structured object like this:

{
  "id": 15,
  "phone_number": "19042223344",
  "name": "Bob's Cell",
  "verified": false,
  "created_at": "2017-01-18T11:43:30.188-05:00",
  "validation_code": "688107"
}

This endpoint creates a single Outbound Caller ID object within the target company. After a successful request to this endpoint, the specified phone number will ring and prompt for a code to be entered in order to verify the phone number. The recipient of the call will need to enter the returned validation_code on the phone’s numeric keypad. If the verification phone call is missed for any reason, a new POST request will need to be made in order to initiate the verification process again.

API Endpoint

Method URL
POST /v2/a/{account_id}/caller_ids.json

Request Body

Name Type Required? Description
company_id integer required Unique identifier for the company.
phone_number string required The telephone number to be verified with the Outbound Caller ID feature.
name string required A descriptive name for the Outbound Caller ID being created.

Response Fields

When successful, the HTTP response code will indicate 201 Created.

Name Type Description
id integer Unique identifier for the Outbound Caller ID object.
phone_number string The telephone number (in e.164 format) of the Outbound Caller ID object.
name string A descriptive name of the Caller ID formatted for display.
company_id integer Unique identifier for the company.
verified boolean Whether or not the phone number has been verified in CallRail.
created_at string The date and time the Outbound Caller ID was created in UTC (ISO 8601 format).
validation_code string Code needed to verify ownership of the phone number to be used with the Outbound Caller ID feature.

Deleting an Outbound Caller ID

curl -H "Authorization: Token token={api_token}" \
     -X DELETE \
     "https://api.callrail.com/v2/a/{account_id}/caller_ids/{caller_ids_id}.json

The above command does not return a JSON response.

This endpoint deletes a Outbound Caller ID object in the target company.

API Endpoint

Method URL
DELETE /v2/a/{account_id}/caller_ids/{caller_ids_id}.json

Response Fields

When successful, the HTTP response code will indicate 204 No Content and no JSON response will be returned.

Page Views

The call page views endpoint provides the browsing history associated with a given call. This endpoint returns web session data, like the referring URL and landing page URL associated with a call to a session tracker. These endpoints return in reverse chronological order, with the newest displaying first.

Responses will list all page views that happen before a caller dials your tracking number, regardless of whether or not the caller is a first-time caller. We won’t return the page views that occurred after the call took place.

Retrieving All Page Views For A Call

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/calls/{call_id}/page_views.json?time_zone=America/Los_Angeles"

The above command returns a JSON structured object like this:

{
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_records": 5,
  "page_views": [
    {
      "referrer_url": "https://www.grandsymphonyresort.com/available-suites/",
      "page_url": "https://www.grandsymphonyresort.com/book-now/",
      "created_at": "2017-03-09T10:17:29-08:00"
    },
    {
      "referrer_url": "https://www.grandsymphonyresort.com/things-to-do",
      "page_url": "https://www.grandsymphonyresort.com/available-suites/",
      "created_at": "2017-03-09T10:17:21-08:00"
    },
    {
      "referrer_url": "https://www.grandsymphonyresort.com/attractions/",
      "page_url": "https://www.grandsymphonyresort.com/things-to-do",
      "created_at": "2017-03-09T10:17:19-08:00"
    },
    {
      "referrer_url": "https://www.grandsymphonyresort.com/?utm_source=google&utm_medium=cpc&utm_campaign=Non-Brand&matchtype=b&device=c&position=1t1&keyword=%2Bvacation%20%2Bresort%20%2Brelax&gclid=DjwKCBjwcdbLBRALEiwFn8pA5QgnviLjpiYy9fY3hcwHxrpIhUj7WbkYGFDhVy-LL2WA9HsQ_KcA_RoCpPgQAvD_BwE",
      "page_url": "https://www.grandsymphonyresort.com/attractions/",
      "created_at": "2017-03-09T10:17:09-08:00"
    },
    {
      "referrer_url": "https://www.google.com/",
      "page_url": "https://www.grandsymphonyresort.com/?utm_source=google&utm_medium=cpc&utm_campaign=Non-Brand&matchtype=b&device=c&position=1t1&keyword=%2Bvacation%20%2Bresort%20%2Brelax&gclid=DjwKCBjwcdbLBRALEiwFn8pA5QgnviLjpiYy9fY3hcwHxrpIhUj7WbkYGFDhVy-LL2WA9HsQ_KcA_RoCpPgQAvD_BwE",
      "created_at": "2017-03-09T10:17:00-08:00"
    }
  ]
}

This endpoint returns a paginated array of page views for a given call within the target account.

API Endpoint

Method URL
GET /v2/a/{account_id}/calls/{call_id}/page_views.json

Request Parameters

This endpoint supports Pagination.

Response Field

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
referrer_url string The url of the referring source or website the caller was previously viewing.
page_url string The url the caller was viewing before navigating to new portion of a website or the last url visited before calling the tracking number displayed on a website.
created_at string The date and time the page view was created in ISO 8601 format.

Working with Time Zones

The CallRail API aligns all dates to the time zone specified within the account. This can be overridden for specified API requests by including a time_zone parameter. This parameter accepts any standard time zone as defined by the IANA’s TZ Database, or using the common names from the examples below.

See an additional list of Time Zones in the Getting Started section.

ex. time_zone=America/New_York

Value Description
user default
Use the default time zone for the user indicated by the current API key. This setting is configured within the application.
America/New_York Eastern Time Zone
America/Indiana/Indianapolis Indiana Time Zone
America/Chicago Central Time Zone
America/Denver Mountain Time Zone
America/Phoenix Arizona Time Zone
America/Los_Angeles Pacific Time Zone

Summary Emails

Users in your CallRail account can be configured to receive periodic activity emails. These emails include a summary of the calls received in the selected period, and can be scheduled on a daily, weekly, or monthly basis. It is also possible to configure which sections are included in the email, as well as opt to send a CSV of calls received. This series of endpoints allows these summary emails to be configured within your account.

Listing All Summary Email Subscriptions

This endpoint lists all summary emails visible to this user. Note that only Administrator users can manage summary emails for other users. If the API Key being used does not belong to an Administrator, only the owner’s summary emails will be returned.

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/summary_emails"

The above command returns a JSON structured object like this:

{
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_records": 2,
  "summary_emails": [
    {
      "id": 944819243,
      "scope": {
        "id": 781435093,
        "type": "Company",
        "name": "C1"
      },
      "frequency": ["daily", "weekly"],
      "config": {
         "summary_statistics": true,
         "top_sources": true,
         "top_keywords": true,
         "call_log": true
      },
      "user": {
        "id": 374621347,
        "name": "Bob Smith",
        "email": "bob.smith@example.com"
      }
    },
    {
      "id": 963510320,
      "scope": {
        "id": 781435093,
        "type": "Company",
        "name": "C1"
      },
      "frequency": ["daily"],
      "config": {
         "summary_statistics": true,
         "top_sources": true,
         "top_keywords": true,
         "call_log": true
      },
      "user": {
        "id": 374621347,
        "name": "Bob Smith",
        "email": "bob.smith@example.com"
      }
    }
  ]
}

This endpoint returns a paginated array of summary emails within the target account or company.

API Endpoint

Method URL
GET /v2/a/{account_id}/summary_emails

Request Parameters

This endpoint supports Pagination and Filtering.

Name Type Required? Description
frequency array optional If provided, only return summary email records configured for the specified frequency. (“daily”, “weekly”, or “monthly”)
company_id number optional Unique identifier for the company. If left blank, Account summary email settings will be fetched.
user_id number optional If provided, only return summary email records configured for the specified user.

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id number Unique identifier for this summary email record.
scope object A short representation of the scope (either Company or Account) for which this email is configured.
frequency array The frequency at which the emails are sent. An array that can include any value of “daily”, “weekly”, or “monthly”.
config object An object that indicates which sections are included in this summary email. Keys are boolean switches for summary_statistics, top_sources, top_keywords, and call_log.
user object A short representation of the user referenced by user_id.

Create a Summary Email Subscription

This endpoint allows creation of a new summary email subscription. A summary email subscription represents a periodic email sent to a user with information about recent activity within a CallRail account. It can be configured for either a specific company (when company_id is present), or for all companies to which the user has access (account_id is used when company_id is absent). The frequency defines how often to send the summary email. Daily emails are sent every morning, while weekly emails are sent every Monday, and monthly emails are sent on the first of every month.

Only administrators can create summary email subscriptions for other users.

curl -H "Authorization: Token token={api_token}" \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{
          "user_id": 374621347,
          "company_id": 781435093,
          "frequency": ["weekly", "daily"],
          "filters": {
            "lead_status": "Not a Lead"
          },
          "config": {
             "summary_statistics": true,
             "top_sources": true,
             "top_keywords": true,
             "call_log": true
          }
        }' \
        "https://api.callrail.com/v2/a/{account_id}/summary_emails.json"

The above command returns JSON structured object like this:

{
  "id": 999127085,
  "scope": {
    "id": 781435093,
    "type": "Company",
    "name": "C1"
  },
  "frequency": ["weekly", "daily"],
  "filters": {
    "lead_status": "Not a Lead"
  },
  "config": {
     "summary_statistics": true,
     "top_sources": true,
     "top_keywords": true,
     "call_log": true
  },
  "user": {
    "id": 374621347,
    "name": "Bob Smith",
    "email": "bob.smith@example.com"
  }
}

API Endpoint

Method URL
POST /v2/a/{account_id}/summary_emails.json

Request Body

Name Type Required? Description
company_id number optional Unique identifier for the company. If left blank, the summary email settings will be assigned to the Account for the specified account’s/company’s summary emails.
frequency array required The frequency at which the emails are sent. Can be one of “daily”, “weekly”, or “monthly”.
config object required An object that contains further configuration for the specified companies summary emails. This object has keys for at least one of summary_statistics, top_sources, top_keywords, and call_log, with boolean values set to true or false.
user_id number required Indicates the user to receive these summary emails.
filters object optional Lead status can be one of ‘Lead’, 'Not a Lead’, 'Not Scored’, or 'All’.

Response Fields

When successful, the HTTP response code will indicate 201 Created.

Name Type Description
id number Unique identifier for this summary email record.
scope object A short representation of the scope (either Company or Account) for which this email is configured.
frequency string The frequency at which the emails are sent. Can be one of “daily”, “weekly”, or “monthly”.
config object An object that indicates which sections are included in this summary email. Keys are boolean switches for summary_statistics, top_sources, top_keywords, and call_log.
user object A short representation of the user referenced by user_id.

Retrieving a Summary Email Subscription

This endpoint retrieves a single summary email record.

Only records that the authenticated user has access to will be returned. Administrators may access records for all users on the account, but other user types may only access their own records.

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/summary_emails/{summary_email_id}.json"

The above command returns a JSON structured object like this:

  {
    "id": 999127085,
    "scope": {
      "id": 781435093,
      "type": "Account",
      "name": "A1"
    },
    "frequency": ["daily", "weekly"],
    "config": {
       "summary_statistics": true,
       "top_sources": true,
       "top_keywords": true,
       "call_log": true
    },
    "user": {
      "id": 374621347,
      "name": "Bob Smith",
      "email": "bob.smith@example.com"
    }
  }

API Endpoint

Method URL
GET /v2/a/{account_id}/summary_emails/{summary_email_id}.json

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id number Unique identifier for this summary email record.
scope object A short representation of the scope (either Company or Account) for which this email is configured.
frequency string The frequency at which the emails are sent. An array that can include any value of “daily”, “weekly”, or “monthly”.
config object An object that indicates which sections are included in this summary email. Keys are boolean switches for summary_statistics, top_sources, top_keywords, and call_log.
user object A short representation of the user referenced by user_id.

Update a Summary Email Subscription

This endpoint allows you to update a user’s summary email subscription. Only the frequency and configuration settings may be modified. To change the scope or user, delete the record and create a new one.

curl -H "Authorization: Token token={api_token}" \
     -X PUT \
     -H "Content-Type: application/json" \
     -d '{
          "frequency": ["monthly", "weekly"],
          "config": {
             "call_log": false
          }
        }' \
        "https://api.callrail.com//v2/a/{account_id}/summary_emails/{summary_email_id}.json"

The above command returns JSON structured object like this:

  {
    "id": 999127085,
    "scope": {
      "id": 781435093,
      "type": "Company",
      "name": "C1"
    },
    "frequency": ["monthly", "weekly"],
    "filters": {
      "lead_status": "Lead"
    },
    "config": {
       "summary_statistics": true,
       "top_sources": true,
       "top_keywords": true,
       "call_log": false
    },
    "user": {
      "id": 374621347,
      "name": "Bob Smith",
      "email": "bob.smith@example.com"
    }
  }

API Endpoint

Method URL
PUT /v2/a/{account_id}/summary_emails/{summary_email_id}.json

Request Body

Name Type Required? Description
frequency array optional The frequency at which the emails are sent. An array that can include any value of “daily”, “weekly”, or “monthly”. If present, only the frequencies listed in the call will be subscribed to, other frequencies will be unsubscribed from. If omitted, the update parameters will apply to the current summary email frequencies.
config object required An object that contains further configuration for the specified companies summary emails. This object has keys for at least one of summary_statistics, top_sources, top_keywords, and call_log, with boolean values set to true or false.
filters object optional Lead status can be one of ‘Lead’, 'Not a Lead’, 'Not Scored’, or 'All’.

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id number Unique identifier for this summary email record.
scope object A short representation of the scope (either Company or Account) for which this email is configured.
frequency string The frequency at which the emails are sent. An array that can include any value of “daily”, “weekly”, or “monthly”.
config object An object that indicates which sections are included in this summary email. Keys are boolean switches for summary_statistics, top_sources, top_keywords, and call_log.
user object A short representation of the user referenced by user_id.

Delete a Summary Email Subscription

curl -H "Authorization: Token token={api_token}" \
     -X DELETE \
     "https://api.callrail.com/v2/a/{account_id}/summary_emails/{summary_email_id}.json"

The above command does not return a JSON response.

This endpoint will remove the specified summary email, which unsubscribes the user from future deliveries.

API Endpoint

Method URL
DELETE /v2/a/{account_id}/summary_emails/{summary_email_id}.json

Response

When successful, the HTTP response code will indicate 204 No Content and no JSON response will be returned.

If the authorized user tries to unsubscribe from a summary email that they don’t have permission to access, the server will return code 403 Forbidden with the following error message:

{ "error" => "You do not have permission to perform the requested action" }

Text Messages

Listing All Conversations

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/text-messages.json"

The above command returns a JSON structured object that includes a paginated list of all text message conversations for a given account.

{
  "page": 1,
  "per_page": 100,
  "total_pages": 3,
  "total_records": 312,
  "conversations": [
    {
      "id": "KZaGR",
      "company_id": 213472384,
      "initial_tracker_id": "519217395",
      "current_tracker_id": "518427598",
      "customer_name": "MANN KEVIN",
      "customer_phone_number": "+14042223333",
      "initial_tracking_number": "+14045556677",
      "current_tracking_number": "+17703334455",
      "last_message_at": "2016-07-28T19:26:43.578Z",
      "state": "active",
      "company_time_zone": "America/New_York",
      "formatted_customer_phone_number": "404-222-3333",
      "formatted_initial_tracking_number": "404-555-6677",
      "formatted_current_tracking_number": "770-333-4455",
      "formatted_customer_name": "Mann Kevin",
      "recent_messages": [
        {
          "direction": "outgoing",
          "content": "Awww! But I was going into Tosche Station to pick up some power converters!",
          "created_at": "2016-07-28T19:28:21.578Z"
        },
        {
          "direction": "incoming",
          "content": "Take these two over to the garage, will you?  I want them cleaned up before dinner.",
          "created_at": "2016-07-28T19:26:43.578Z"
        }
      ]
    },
    {
      "id": "KZaGY",
      "company_id": 213472384,
      "initial_tracker_id": "516617",
      "current_tracker_id": "513727",
      "customer_name": "POWELL ANDY",
      "customer_phone_number": "+14042223333",
      "initial_tracking_number": "+14045556677",
      "current_tracking_number": "+17703334455",
      "last_message_at": "2016-07-28T19:26:43.578Z",
      "state": "active",
      "company_time_zone": "America/New_York",
      "formatted_customer_phone_number": "404-222-3333",
      "formatted_initial_tracking_number": "404-555-6677",
      "formatted_current_tracking_number": "770-333-4455",
      "formatted_customer_name": "Powell Andy",
      "recent_messages": [
        {
          "direction": "outgoing",
          "content": "It’s not impossible. I used to bullseye womp rats in my T-16 back home, they’re not much bigger than two meters.",
          "created_at": "2016-07-28T19:28:21.578Z"
        },
        {
          "direction": "incoming",
          "content": "That's impossible, even for a computer!",
          "created_at": "2016-07-28T19:26:43.578Z"
        }
      ]
    }
  ]
}

Conversations are ordered by their most recent message and the newest conversations are returned first. Conversation objects include the two most recent messages.

API Endpoint

Method URL
GET /v2/a/{account_id}/text-messages.json

Request Parameters

This endpoint supports Pagination, Filtering, Searching and Field Selection

Name Type Required? Description
company_id integer optional Limit response to conversations belonging to a single company.

Filtering is available for the following:

Searching is available for the following fields:

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id string Unique alphanumeric identifier for the text conversation.
company_id integer An ID indicating which company the message belongs to.
initial_tracker_id number Unique identifier for the tracking number used to start the conversation.
current_tracker_id number Unique identifier for the tracking number used most recently in the conversation.
customer_name string The customer’s name
customer_phone_number string The customer’s phone number (in E.164 format).
initial_tracking_number string The tracking phone number used to start the conversation (in E.164 format).
current_tracking_number string The tracking phone number used in the most recent conversation (in E.164 format).
last_message_at string The date and time the text was received or sent in UTC, in ISO 8601 format.
state string Whether or not the conversation is active or archived in CallRail. One of “active” or “archived”.
company_time_zone string The timezone of the company associated with the conversation.
formatted_customer_phone_number string The phone number of the customer, formatted for display.
formatted_initial_tracking_number string The initial_tracking_number formatted for display.
formatted_current_tracking_number string The current_tracking_number formatted for display.
formatted_customer_name string The name or the customer, formatted for display.
recent_messages array JSON array containing up to two previous text messages in the current conversation (fields described below.)
Message Fields
Name Type Description
direction string The direction of the text message sent to or received from the customer. One of “incoming” or “outgoing”.
content string The content body of the text message.
created_at string The date and time the text was created in UTC, in ISO 8601 format.

Additional User Requested Response Fields

Field Selection is available for the following fields.

Name Type Description
lead_status string The current lead status for the text conversation. One of previously_marked_good_lead, or null.

Retrieving A Single Text Conversation

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/text-messages/{conversation_id}.json"

The above command returns a single paginated JSON conversation object.

  {
    "id": "KkMhr",
    "company_id": 213472384,
    "initial_tracker_id": "519217395",
    "current_tracker_id": "518427598",
    "customer_name": "MANN KEVIN",
    "customer_phone_number": "+14042223333",
    "initial_tracking_number": "+14045556677",
    "current_tracking_number": "+17703334455",
    "last_message_at": "2016-07-28T19:26:43.578Z",
    "state": "active",
    "company_time_zone": "America/New_York",
    "formatted_customer_phone_number": "404-222-3333",
    "formatted_initial_tracking_number": "404-555-6677",
    "formatted_current_tracking_number": "770-333-4455",
    "formatted_customer_name": "Mann Kevin",
    "page": 1,
    "per_page": 100,
    "total_pages": 1,
    "total_records": 2,
    "messages": [
      {
        "id": 23456,
        "content": "These aren't the droids you're looking for.",
        "created_at": "2016-07-28T19:28:21.578Z",
        "status": null,
        "direction": "incoming",
        "user": {
          "id": 374621347,
          "name": "Bob Smith"
        }
      }
    ]
  }

This endpoint retrieves a text message conversation. Text messages in the conversation are ordered by the most recent message first.

API Endpoint

Method URL
GET /v2/a/{account_id}/text-messages/{conversation_id}.json

Request Parameters

This endpoint supports Field Selection

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id string Unique alphanumeric identifier for the text conversation.
company_id integer An ID indicating which company the message belongs to.
initial_tracker_id number Unique identifier for the tracking number used to start the conversation.
current_tracker_id number Unique identifier for the tracking number used most recently in the conversation.
customer_name string The customer’s name.
customer_phone_number string The customer’s phone number (in E.164 format).
initial_tracking_number string The tracking phone number used to start the conversation (in E.164 format).
current_tracking_number string The tracking phone number used in the most recent conversation (in E.164 format).
last_message_at string The date and time the text was received or sent in UTC, in ISO 8601 format.
state string Whether or not the conversation is active or archived in CallRail. One of “active” or “archived”.
company_time_zone string The timezone of the company associated with the conversation.
formatted_customer_phone_number string The phone number of the customer, formatted for display.
formatted_initial_tracking_number string The initial_tracking_number formatted for display.
formatted_current_tracking_number string The current_tracking_number formatted for display.
formatted_customer_name string The name of the customer, formatted for display.
page number Specific page number of the paginated messages in this conversation.
per_page number Total number of messages per page.
total_pages number Total number of paginated messages returned in each page.
total_records number Total number of messages returned in the conversation.
messages string JSON array of text messages returned by the query (fields described in table below).
Message Fields
Name Type Description
id number Unique identifier for a specific text.
content string The content body of the text message.
created_at string The date and time the text was created in UTC, in ISO 8601 format.
status string For outgoing messages, whether the message was successfully sent (sent), or failed to be delivered (failed). For incoming messages, this field will be null.One of “sent” or “error”
direction string The direction of the text message sent to or received from the customer. One of “incoming” or “outgoing”.
user resource The CallRail user who sent the text message
id
number The ID of the CallRail user who sent the text message.
name
string The name of the CallRail user who sent the text message.

Additional User Requested Response Fields

Field Selection is available for the following fields.

Name Type Description
lead_status string The current lead status for the text conversation. One of previously_marked_good_lead, or null.

Send a Text Message

curl -H "Authorization: Token token={api_token}" \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{
          "customer_phone_number": "+14044442233",
          "tracking_number": "+17703334455",
          "content": "These are not the droids you are looking for.",
          "company_id": 213472384
         }' \
         "https://api.callrail.com/v2/a/{account_id}/text-messages.json"

This endpoint creates a SMS text message in the target company.

The above command creates a single outbound text message that can be part of an existing conversation or the start of a new conversation. The response is a JSON structured object containing message details, and may include the two most recent messages for an existing converasation.

{
  "id": "FyzZ6",
  "company_id": 213472384,
  "initial_tracker_id": 519217395,
  "current_tracker_id": 518427598,
  "customer_name": "MANN KEVIN",
  "customer_phone_number": "+14044442233",
  "initial_tracking_number": "+14045556677",
  "current_tracking_number": "+17703334455",
  "last_message_at": null,
  "state": "archived",
  "company_time_zone": "America/New_York",
  "formatted_customer_phone_number": "404-444-2233",
  "formatted_initial_tracking_number": "404-555-6677",
  "formatted_current_tracking_number": "770-333-4455",
  "formatted_customer_name": "Mann Kevin",
  "recent_messages": [
    {
      "direction": "outgoing",
      "content": "These are not the droids you are looking for.",
      "created_at": "2016-10-12T11:57:57.337-04:00"
    }
  ]
}

API Endpoint

Method URL
POST /v2/a/{account_id}/text-messages.json

Request Body

Name Type Required? Description
company_id integer required An ID indicating which company the message belongs to.
tracking_number integer required Tracking phone number used to send this message to the customer. Must be a valid 10 digit US or Canadian number. Note: tracking_number is optional if there is an existing conversation with the customer_phone_number specified in the request.
customer_phone_number string required The customer’s phone number this message will be delivered to. Must be a valid 10 digit US or Canadian number.
content string required Message body being sent to the customer. This string must be limited to 140 characters.

Response Fields

When successful, the HTTP response code will indicate 201 Created.

Name Type Description
id string Unique alphanumeric identifier for the text conversation.
company_id integer An ID indicating which company the message belongs to.
initial_tracker_id number Unique identifier for the tracking number used to start the conversation.
current_tracker_id number Unique identifier for the tracking number used in the most recent conversation. If null, initial_tracker_id is the current tracker_id used in the conversation.
customer_name string The customer’s name.
customer_phone_number string The customer’s phone number (in E.164 format).
initial_tracking_number string The tracking phone number used to start the conversation (in E.164 format).
current_tracking_number string The tracking phone number used in the most recent conversation (in E.164 format).
last_message_at string The date and time the text was received or sent in UTC, in ISO 8601 format.
state string Whether or not the conversation is active or archived in CallRail.
company_time_zone string The timezone of the company associated with the conversation.
formatted_customer_phone_number string The phone number of the customer, formatted for display.
formatted_initial_tracking_number string The initial_tracking_number formatted for display.
formatted_current_tracking_number string The current_tracking_number formatted for display.
formatted_customer_name string The name or the customer, formatted for display.
recent_messages array JSON array containing up to two previous text messages in the current conversation (fields described below.)
Message Fields
Name Type Description
direction string The direction of the text message sent to or received from the customer. One of “incoming” or “outgoing”.
content string The content body of the text message.
created_at string The date and time the text was created in UTC, in ISO 8601 format.

Archive a Text Conversation

curl -H "Authorization: Token token={api_token}" \
     -X PUT \
     -H "Content-Type: application/json" \
     -d '{
          "state": "archived"
         }' \
         "https://api.callrail.com/v2/a/{account_id}/text-messages/{conversation_id}.json"

The above command archives an existing conversation.

{
  "id": "FyzZ6",
  "state": "archived"
}

API Endpoint

Method URL
PUT v2/a/{account_id}/text-messages/{conversation_id}.json

Request Parameters

Name Type Required? Description
conversation_id integer required Unique identifier for SMS conversation.

Request Body

Name Type Required? Description
state string required The new state of the conversation, either ‘active’ or 'archived’.

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id string Unique alphanumeric identifier for the text conversation.
state string Whether or not the conversation is active or archived in CallRail.

Trackers

Trackers are phone numbers that can be used to route phone calls to a business. CallRail provides two different types of trackers.

Source trackers associate a single tracking number to a certain set of customers based on how they found the number. For example, a single source tracker might be used to identify website visitors who came from facebook.com, or all visitors who found your site from a paid Google search. Or it may attribute to an offline source such as a billboard or TV advertisement. When used online, a single source tracking phone number may be shown to multiple visitors simultaneously, and as such cannot be used to capture full session details for individual visitors.

Session trackers serve one number from a pool of tracking numbers to website visitors, allowing you to associate calls to individual visitors, the keywords they searched for before arriving via search engine, and their browsing history on your site.

Listing All Trackers

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/trackers.json"

The above command returns JSON structured object like this:

{
  "page": 1,
  "per_page": 250,
  "total_pages": 1,
  "total_records": 3,
  "trackers": [
    {
      "id": 279054151,
      "name": "My Billboard",
      "type": "source",
      "status": "active",
      "destination_number": "+15553104554",
      "tracking_numbers": ["+14045559999"],
      "whisper_message": null,
      "sms_enabled": false,
      "sms_supported": true,
      "company": {
        "id": 219817635,
        "name": "Bob's Auto Shop"
      },
      "call_flow": {
        "type": "basic",
        "recording_enabled": true,
        "destination_number": "+15553104554",
        "greeting_text": "This call will be recorded for quality assurance"
      },
      "source": {
        "type": "search",
        "search_engine": "google",
        "search_type": "organic"
      },
      "created_at": "2011-07-05T19:06:10Z",
      "disabled_at": null
    },
    {
      "id": 279054152,
      "name": "Widget Shop",
      "type": "session",
      "status": "active",
      "destination_number": "+15553104554",
      "tracking_numbers": ["+14045551111","+14045552222", "+14045553333", "+14045554444"],
      "whisper_message": "Call from [source].",
      "sms_enabled": true,
      "sms_supported": true,
      "company": {
        "id": 219817635,
        "name": "Bob's Auto Shop"
      },
      "call_flow": {
        "type": "basic",
        "recording_enabled": true,
        "destination_number": "+15553104554",
        "greeting_text": "This call will be recorded for quality assurance"
      },
      "source": {
        "google": ["paid", "organic"],
        "bing": ["paid", "organic"],
        "yahoo": ["paid", "organic"]
      },
      "created_at": "2011-07-05T19:06:10Z",
      "disabled_at": null
    }
  ]
}

This endpoint returns a paginated array of all companies associated with the target account.

Method URL
GET /v2/a/{account_id}/trackers.json

Request Parameters

This endpoint supports Pagination, Field Selection, Sorting, Filtering, and Searching.

Name Type Required? Description
company_id integer optional Limit response to trackers belonging to a single company.

Sorting is available for the following fields:

Filtering is available for the following:

Searching is available for the following fields:

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id number Unique identifier for this Tracker.
name string Descriptive Name for this Tracker.
type string Type of tracker. One of “source” or “session”.
destination_number string The destination phone number that rings when calls are placed to a tracker.
status string Current status of the tracker. Returns “active” or “disabled”.
tracking_numbers array List of tracking phone numbers for this Tracker.
whisper_message string A ‘Whisper Message’ is a short message that plays to the call recipient before the call is connected. The caller does not hear this message. If the whisper message contains [source], it will whisper the detected source of the caller.
sms_enabled boolean Whether or not this tracker is configured to send and receive text messages. This setting is currently only supported for local phone numbers in the US and Canada.
sms_supported boolean Indicates whether or not this tracker can support text messages. (i.e., whether or not sms_enabled could be set to true)
company object Basic information on which company owns this Tracker.
call_flow object An object describing how calls are routed for this Tracker.
source object An object describing the source of the calls that this tracker will handle.
created_at string The date and time the Tracker was created in UTC (ISO 8601 format).
disabled_at string If the tracker has been disabled, this will be the date and time at which it was disabled (UTC, ISO 8601 format). If the tracker is still enabled, this value will be null.

Additional User Requested Response Fields

Field Selection is available for the following fields.

Name Type Description
swap_targets array A list of telephone numbers configured to dynamically replace with a tracking number. See Swap Targets.

Retrieving a Single Tracker

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/trackers/{tracker_id}.json"

The above command returns JSON structured object like this:

{
  "id": 279054151,
  "name": "My Billboard",
  "type": "source",
  "status": "active",
  "destination_number": "+15553104554",
  "tracking_numbers": ["+14045554444"],
  "whisper_message": "Call from [source].",
  "sms_enabled": true,
  "sms_supported": true,
  "company": {
    "id": 219817635,
    "name": "Bob's Auto Shop"
  },
  "call_flow": {
    "type": "basic",
    "recording_enabled": true,
    "destination_number": "+15553104554",
    "greeting_text": "This call will be recorded for quality assurance"
  },
  "source": {
    "type": "search",
    "search_engine": "google",
    "search_type": "organic"
  },
  "created_at": "2011-07-05T19:06:10Z",
  "disabled_at": null
}

This endpoint returns a single tracker object associated with the target account.

Method URL
GET /v2/a/{account_id}/trackers/{tracker_id}.json

Request Parameters

This endpoint supports Field Selection.

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id number Unique identifier for this Tracker.
name string Descriptive Name for this Tracker.
type string Type of tracker. One of “source” or “session”.
destination_number string The destination phone number that rings when calls are placed to a tracker.
status string Current status of the tracker. Returns “active” or “disabled”.
tracking_numbers array List of tracking phone numbers for this Tracker.
whisper_message string A ‘Whisper Message’ is a short message that plays to the call recipient before the call is connected. The caller does not hear this message. If the whisper message contains [source], it will whisper the detected source of the caller.
sms_enabled boolean Whether or not this tracker is configured to send and receive text messages. This setting is currently only supported for local phone numbers in the US and Canada.
sms_supported boolean Indicates whether or not this tracker can support text messages. (i.e., whether or not sms_enabled could be set to true)
company object Basic information on which company owns this Tracker.
call_flow object An object describing how calls are routed for this Tracker.
source object An object describing the source of the calls that this tracker will handle.
created_at string The date and time the Tracker was created in UTC (ISO 8601 format).
disabled_at string If the tracker has been disabled, this will be the date and time at which it was disabled (UTC, ISO 8601 format). If the tracker is still enabled, this value will be null.

Additional User Requested Response Fields

Field Selection is available for the following fields.

Name Type Description
swap_targets array A list of telephone numbers configured to dynamically replace with a tracking number. See Swap Targets.

Creating a Session Tracker

curl  -H "Authorization: Token token=\"{api_token}\"" \
      -X POST
      -H "Content-Type: application/json" \
      -d '{
            "type": "session",
            "name": "Website Call Tracker",
            "company_id": 219817635,
            "swap_targets": ["7704761456", "7705551234"],
            "whisper_message": "Call from [source]",
            "sms_enabled": true,
            "pool_size": 10,
            "call_flow": {
              "type": "basic",
              "recording_enabled": true,
              "destination_number": "+15553104554",
              "greeting_text": "This call will be recorded for quality assurance"
            },
            "pool_numbers": {
              "area_code": "555",
              "local": "+15553104554"
            },
            "source": {
              "google": ["paid", "organic"],
              "bing": ["paid", "organic"],
              "yahoo": ["paid", "organic"]
            }
          }' \
      "https://api.callrail.com/v2/a/{account_id}/trackers.json"

This endpoint creates a session tracker within the target company. See the Terminology section for more info about session trackers.

The above command returns JSON structured object like this:

{
  "id": 279054151,
  "name": "Website Call Tracker",
  "type": "session",
  "status": "active",
  "destination_number": "+15553104554",
  "tracking_numbers": ["+14045551111","+14045552222", "+14045553333", "+14045554444"],
  "sms_enabled": true,
  "sms_supported": true,
  "company": {
    "id": 219817635,
    "name": "Bob's Auto Shop"
  },
  "call_flow": {
    "type": "basic",
    "recording_enabled": true,
    "destination_number": "+15553104554",
    "greeting_text": "This call will be recorded for quality assurance"
  },
  "source": {
    "google": ["paid", "organic"],
    "bing": ["paid", "organic"],
    "yahoo": ["paid", "organic"]
  },
  "created_at": "2011-07-05T19:06:10Z",
  "disabled_at": null
}

API Endpoint

Method URL
POST /v2/a/{account_id}/trackers.json

Request Body

Name Type Required? Description
name string required Name of the tracker.
type string required Type of tracker to create. Use “session” to create a session tracker.
company_id number required An ID indicating which company the tracker belongs to.
call_flow object required An object describing what happens to the customer’s call. See Configuring Call Flows.
pool_size number required How many phone numbers to allocate to this tracker. Must be between 4 and 50.
pool_numbers object required An object describing constraints for provisioning tracking phone numbers. See Requesting a Number.
source string or object required An object describing which visitors will be served this tracker. See Session Tracker Call Sources.
swap_targets array optional The telephone number(s) to target for replacement on your website. When this Tracker applies, this number will be replaced with a tracking phone number. No formatting is required, as the script will search for all possible formats. If no swap targets are provided, the destination number will be used.
whisper_message string optional A ‘Whisper Message’ is a short message that plays to the call recipient before the call is connected. The caller does not hear this message.
If the whisper message contains [source], it will whisper the name of the tracker.
sms_enabled boolean optional Allows text messages to be sent and received by this tracker. This setting is currently only supported for local phone numbers in the US and Canada.

Response Fields

When successful, the HTTP response code will indicate 201 Created.

Name Type Description
id number Unique identifier for this Tracker.
name string Descriptive Name for this Tracker.
type string Type of tracker. One of “source” or “session”.
status string Current status of the tracker. Returns “active” or “disabled”.
destination_number string The destination phone number that rings when calls are placed to a tracker.
tracking_numbers array List of tracking phone numbers for this Tracker.
sms_enabled boolean Whether or not this tracker is configured to send and receive text messages. This setting is currently only supported for local phone numbers in the US and Canada.
sms_supported boolean Indicates whether or not this tracker can support text messages. (i.e., whether or not sms_enabled could be set to true)
company object Basic information on which company owns this Tracker.
call_flow object An object describing how calls are routed for this Tracker.
source object An object describing the source of the calls that this tracker will handle.
created_at string The date and time the Tracker was created in UTC (ISO 8601 format).
disabled_at string If the tracker has been disabled, this will be the date and time at which it was disabled (UTC, ISO 8601 format). If the tracker is still enabled, this value will be null.

Creating a Source Tracker

curl  -H "Authorization: Token token=\"{api_token}\"" \
      -H "Content-Type: application/json" \
      -X POST
      -d '{
            "name": "My Billboard",
            "company_id": 219817635,
            "call_flow": {
              "type": "basic",
              "recording_enabled": false,
              "destination_number": "+15553104554",
              "greeting_text": "This call will be recorded for quality assurance"
            },
            "tracking_number": {
              "area_code": "555",
              "local": "+15553104554"
            },
            "sms_enabled": true,
            "source": {
              "type": "search",
              "search_engine": "google",
              "search_type": "organic"
            },
            "type": "source",
            "swap_targets": ["7704761456", "7705551234"],
            "whisper_message": "Call from My Billboard"
          }' \
      "https://api.callrail.com/v2/a/{agency_id}/trackers.json"

The above command returns JSON structured object like this:

{
  "id": 279054151,
  "name": "My Billboard",
  "type": "source",
  "status": "active",
  "destination_number": "+15553104554",
  "tracking_numbers": ["+14045554444"],
  "sms_enabled": true,
  "sms_supported": true,
  "company": {
    "id": 219817635,
    "name": "Bob's Auto Shop"
  },
  "call_flow": {
    "type": "basic",
    "recording_enabled": true,
    "destination_number": "+15553104554",
    "greeting_text": "This call will be recorded for quality assurance"
  },
  "source": {
    "type": "search",
    "search_engine": "google",
    "search_type": "organic"
  },
  "created_at": "2011-07-05T19:06:10Z",
  "disabled_at": null
}

This endpoint creates a source tracker in the target company. See the Terminology section for more info about source trackers.

API Endpoint

Method URL
POST /v2/a/{account_id}/trackers.json

Request Body

Name Type Required? Description
name string required A descriptive name for this tracker.
type string required Type of tracker to create. Use “source” to create a source tracker.
company_id number required An ID indicating which company the tracker belongs to.
call_flow object required An object describing what happens to the customer’s call. See Configuring Call Flow.
tracking_number object required An object describing what constraints the tracking phone number should have. See Requesting a Number.
source object required An object describing how the visitor will be routed to this tracker. See Source Tracker Call Sources.
sms_enabled boolean optional Allows text messages to be sent and received by this tracker. This setting is currently only supported for local phone numbers in the US and Canada.
swap_targets array optional The telephone number(s) to target for replacement on your website. When this Tracker applies, this number will be replaced with a tracking phone number. No formatting is required, as the script will search for all possible formats. If no swap targets are provided, the destination number will be used.
whisper_message string optional A ‘Whisper Message’ is a short message that plays to the call recipient before the call is connected. The caller does not hear this message.

Response Fields

When successful, the HTTP response code will indicate 201 Created.

Name Type Description
id number Unique identifier for this Tracker.
name string Descriptive Name for this Tracker.
type string Type of tracker. One of “source” or “session”.
status string Current status of the tracker. Returns “active” or “disabled”.
destination_number string The destination phone number that rings when calls are placed to a tracker.
tracking_numbers array List of tracking phone numbers for this Tracker.
sms_enabled boolean Whether or not this tracker is configured to send and receive text messages. This setting is currently only supported for local phone numbers in the US and Canada.
sms_supported boolean Indicates whether or not this tracker can support text messages. (i.e., whether or not sms_enabled could be set to true)
company object Basic information on which company owns this Tracker.
call_flow object An object describing how calls are routed for this Tracker.
source object An object describing the source of the calls that this tracker will handle.
created_at string The date and time the Tracker was created in UTC (ISO 8601 format).
disabled_at string If the tracker has been disabled, this will be the date and time at which it was disabled (UTC, ISO 8601 format). If the tracker is still enabled, this value will be null.

Updating a Session Tracker

curl  -H "Authorization: Token token=\"{api_token}\"" \
      -H "Content-Type: application/json" \
      -X PUT
      -d '{
            "name": "My Website Tracker",
            "swap_targets": ["7704761456", "7705551234"],
            "whisper_message": "Call from [source]",
            "pool_size": 4,
            "sms_enabled": true,
            "call_flow": {
              "type": "basic",
              "recording_enabled": true,
              "destination_number": "+14044554321",
              "greeting_text": "This call will be recorded for quality assurance"
            },
            "source": {
              "google": ["paid", "organic"],
              "bing": ["paid", "local"]
            }
          }' \
      "https://api.callrail.com/v2/a/{account_id}/trackers/{tracker_id}.json"

The above command returns JSON structured object like this:

{
  "id": 279054151,
  "name": "My Website Tracker",
  "type": "session",
  "status": "active",
  "destination_number": "+14044554321",
  "tracking_numbers": ["+14045551111", "+14045552222", "+14045553333", "+14045554444"],
  "sms_enabled": true,
  "sms_supported": true,
  "company": {
    "id": 219817635,
    "name": "Bob's Auto Shop"
  },
  "call_flow": {
    "type": "basic",
    "recording_enabled": true,
    "destination_number": "+14044554321",
    "greeting_text": "This call will be recorded for quality assurance"
  },
  "source": {
    "google": ["paid", "organic"],
    "bing": ["paid", "local"]
  },
  "created_at": "2011-07-05T19:06:10Z",
  "disabled_at": null
}

This endpoint updates an existing session tracker within the target company. See the Terminology section for more info about session trackers.

API Endpoint

Method URL
PUT /v2/a/{account_id}/trackers/{tracker_id}.json

Request Body

Name Type Required? Description
name string optional Name of the tracker.
pool_size number optional The count of phone numbers to allocate to this pool. To prevent unexpected loss of live phone numbers, this size can only be increased.
*Numbers may not be available immediately after updating pool size.
whisper_message string optional A ‘Whisper Message’ is a short message that plays to the call recipient before the call is connected. The caller does not hear this message. If the whisper message contains [source], it will whisper the detected source of the caller.
swap_targets array optional The telephone number(s) to target for replacement on your website. When this Tracker applies, this number will be replaced with a tracking phone number. No formatting is required, as the script will search for all possible formats. If no swap targets are provided, the destination number will be used.
call_flow object optional An object describing what happens to the customer’s call. See Configuring Call Flows.
source string or object optional An object describing which visitors will be served this tracker. See Configuring Call Sources.
sms_enabled boolean optional Allows text messages to be sent and received by this tracker. This setting is currently only supported for local phone numbers in the US and Canada.

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id number Unique identifier for this Tracker.
name string Descriptive Name for this Tracker.
type string Type of tracker is “session”.
status string Current status of the tracker. Returns “active” or “disabled”.
destination_number string The destination phone number that rings when calls are placed to a tracker.
tracking_numbers array List of tracking phone numbers for this Tracker.
sms_enabled boolean Whether or not this tracker is configured to send and receive text messages. This setting is currently only supported for local phone numbers in the US and Canada.
sms_supported boolean Indicates whether or not this tracker can support text messages. (i.e., whether or not sms_enabled could be set to true)
company object Basic information on which company owns this Tracker.
call_flow object An object describing how calls are routed for this Tracker.
source object An object describing the source of the calls that this tracker will handle.
created_at string The date and time the Tracker was created in UTC (ISO 8601 format).
disabled_at string If the tracker has been disabled, this will be the date and time at which it was disabled (UTC, ISO 8601 format). If the tracker is still enabled, this value will be null.

Updating a Source Tracker

curl  -H "Authorization: Token token=\"{api_token}\"" \
      -H "Content-Type: application/json" \
      -X PUT
      -d '{
            "call_flow": {
              "type": "basic",
              "recording_enabled": false,
            },
            "source": {
              "type": "search",
              "search_engine": "google",
              "search_type": "organic"
            },
            "sms_enabled": true,
            "swap_targets": ["7705551234", "7705554567"],
            "whisper_message": ""
          }' \
      "https://api.callrail.com/v2/a/{account_id}/trackers/{tracker_id}.json"

The above command returns JSON structured object like this:

{
  "id": 279054151,
  "name": "My Billboard",
  "type": "source",
  "status": "active",
  "destination_number": "+15553104554",
  "tracking_numbers": ["+14045551114", "+14045552223", "+14045553332", "+14045554441"],
  "sms_enabled": true,
  "sms_supported": true,
  "company": {
    "id": 219817635,
    "name": "Bob's Auto Shop"
  },
  "call_flow": {
    "type": "basic",
    "recording_enabled": false,
    "destination_number": "+15553104554",
    "greeting_text": "This call will be recorded for quality assurance",
    "greeting_recording_url": null
  },
  "source": {
    "type": "search",
    "search_engine": "google",
    "search_type": "organic"
  },
  "created_at": "2011-07-05T19:06:10Z",
  "disabled_at": null
}

This endpoint updates an existing source tracker within the target company. See the Terminology section for more info about source trackers.

API Endpoint

Method URL
PUT /v2/a/{account_id}/trackers/{tracker_id}.json

Request Body

Name Type Required? Description
name string optional Name of the tracker.
whisper_message string optional A ‘Whisper Message’ is a short message that plays to the call recipient before the call is connected. The caller does not hear this message. If the whisper message contains [source], it will whisper the detected source of the caller.
swap_targets array optional The telephone number(s) to target for replacement on your website. When this Tracker applies, this number will be replaced with a tracking phone number. No formatting is required, as the script will search for all possible formats. If no swap targets are provided, the destination number will be used.
sms_enabled boolean optional Allows text messages to be sent and received by this tracker. This setting is currently only supported for local phone numbers in the US and Canada.
call_flow object optional An object describing what happens to the customer’s call. See Configuring Call Flows.
source object optional An object describing which visitors will be served this tracker. See Configuring Call Sources.

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
id number Unique identifier for this Tracker.
name string Descriptive Name for this Tracker.
type string Type of tracker is “source”.
status string Current status of the tracker. Returns “active” or “disabled”.
destination_number string The destination phone number that rings when calls are placed to a tracker.
tracking_numbers array List of tracking phone numbers for this Tracker.
sms_enabled boolean Whether or not this tracker is configured to send and receive text messages. This setting is currently only supported for local phone numbers in the US and Canada.
sms_supported boolean Indicates whether or not this tracker can support text messages. (i.e., whether or not sms_enabled could be set to true)
company object Basic information on which company owns this Tracker.
call_flow object An object describing how calls are routed for this Tracker.
source object An object describing the source of the calls that this tracker will handle.
created_at string The date and time the Tracker was created in UTC (ISO 8601 format).
disabled_at string If the tracker has been disabled, this will be the date and time at which it was disabled (UTC, ISO 8601 format). If the tracker is still enabled, this value will be null.

Disabling a Tracker

curl -H "Authorization: Token token={api_token}" \
     -X DELETE \
     "https://api.callrail.com/v2/a/{account_id}/trackers/{tracker_id}.json"

The above command does not return a JSON response.

This endpoint disables an Tracker object in the target company.

API Endpoint

Method URL
DELETE /v2/a/{account_id}/trackers/{tracker_id}.json

Response

When successful, the HTTP response code will indicate 204 No Content and no JSON response will be returned.

If the Tracker is used as an Outbound Number for form submissions, a 400 error with the following response will be returned.

{ error: 'You must select a different number for outbound Form Submission calls before disabling this tracker.' }

Requesting a Number

When creating a Source or Session Tracker, you are given the opportunity to request what kind of phone number(s) you would like to use for the tracker.

At least one parameter must be provided to obtain number(s).

The options you can provide are as follows:

Name Type Description
area_code string The phone number should be located in the provided area code.
local string The phone number should be “local” to another phone number (for example, your main business number).
toll_free boolean If true, the phone number should be toll free.

Examples:

{
  "area_code": "404",
  "local": "+14045558769"
}

Request a phone number local to a given business phone number.

This is the most common use case for local numbers. CallRail will attempt to obtain a phone number in the same area code as the provided number. If no inventory is available in that area code, the search will fall back to other local area codes when available.

{
  "area_code": "404",
  "local": "+14045558769"
}

Request a phone number local to a given business phone number, but require in the 404 area code.

A number in the same area code is required in this example. If no inventory is available in 404, the Tracker will not be created and an error will be returned.

{
  "area_code": "303"
}

Request any phone number in the 303 area code.

{
  "toll_free": true
}

Request a toll free number in any area code.

This is the most common use case for toll free numbers. This may be an 888, 877, 866, or 855 number. CallRail will prefer area codes in that order.

{
  "area_code": "888",
  "toll_free": true
}

Request a toll free number in the 888 area code.

A number in the 888 area code is required in this example. If no 888 numbers are available, the Tracker will not be created and an error will be returned.

Configuring Call Flows

Call Flows are analogous to traditional telephone interactive voice response (IVR) systems. Call Flows allow for custom prompts and dynamic call routing to take place on a per call basis. At this time, only touch tone responses via the caller’s phone keypad are able to interact with a Call Flow.

The Call Flow Object describes what happens to an incoming phone call to a tracking number. This can involve multiple steps before ultimately routing a call to the destination number or voicemail.

API Representation

A distinction is made between a “basic” call flow and an “advanced” call flow. A basic call flow may play either a text or recorded greeting before routing the call to the destination number. An advanced call flow may have multiple steps including menus, time of day based routing, voicemail, or more.

At this time, only Basic Call Flow Objects are supported when creating or updating a Source Tracker or Session Tracker. Advanced Call Flow Objects can only be configured or updated through the CallRail application interface. However, when retrieving Trackers with Advanced Call Flows the format described below will be used.

Basic Call Flow Object

/* no greeting */
{
  "type": "basic",
  "recording_enabled": false,
  "destination_number": "+15558675309",
  "greeting_text": null,
  "greeting_recording_url": null
}

/* recorded greeting */
{
  "type": "basic",
  "recording_enabled": true,
  "destination_number": "+15558675309",
  "greeting_text": null,
  "greeting_recording_url": "https://s3.aws.com/.../recording.mp3"
}

/* text greeting */
{
  "type": "basic",
  "recording_enabled": true,
  "destination_number": "+15558675309",
  "greeting_text": "This call will be recorded for quality assurance",
  "greeting_recording_url": null
}

/* text greeting (will default to text greeting only) */
{
  "type": "basic",
  "recording_enabled": true,
  "destination_number": "+15558675309",
  "greeting_text": "This call will be recorded for quality assurance",
  "greeting_recording_url": "https://s3.aws.com/.../recording.mp3"
}

Advanced Call Flow Object

/* route to voicemail or dial a number based on a menu */

{
  "type": "advanced",
  "recording_enabled": false,
  "initial_step_id": 210884509,
  "steps": [
    {
      "destination_number": "+15551234567",
      "timeout": 60,
      "timeout_step_id": null,
      "id": 344126405,
      "type": "dial"
    },
    {
      "prompt_type": "text",
      "prompt_recording_id": null,
      "prompt_text": "Thank you for your support call. Please leave a message.",
      "transcribe": false,
      "id": 250778404,
      "type": "voicemail"
    },
    {
      "prompt_type": "text",
      "prompt_recording_id": null,
      "prompt_text": "Press 1 for Sales, press 2 for Support.",
      "menu_options": [
        {
          "key": "1",
          "description": "Forward to Sales",
          "next_step_id": 344126405
        },
        {
          "key": "2",
          "description": "Forward to Support",
          "next_step_id": 250778404
        }
      ],
      "id": 210884509,
      "type": "menu"
    }
  ]
}

The format for more advanced call flows is necessarily more complex:

Session Tracker Call Sources

The Call Source object describes the type of website visitor that will be tracked by a Session Tracker, and therefore see numbers from the pool.

// Track all website visitors, regardless of source
"source": "all"

// Note that the API will return a structured object
"source": {
  "type": "all"
}

Tracking All Visitors

To track all website visitors regardless of source, specify the string "all" in place of the object. This is the most common usage scenario.

// To track only visitors from Google Adwords:
"source": {
  "google": ["paid"]
}

// To track all PPC visitors:
"source": {
  "google": [ "paid" ],
  "yahoo": [ "paid" ],
  "bing": [ "paid" ]
}

// To track Adwords visitors and visitors with
// specific landing page parameters:
"source": {
  "google": [ "paid" ],
  "landing": [ "facebook_landing", "email_landing" ]
}

// To track all visitors except direct visitors and
// those coming from organic search results:
"source": {
  "inverted": true,
  "type": "direct",
  "google": [ "organic" ],
  "yahoo": [ "organic" ],
  "bing": [ "organic" ]
}

Advanced Session Tracking Options

Session Trackers can also be used to only track visitors from specific search engines, or based on other attributes from the referring URL or landing page. To configure using this option, pass a JSON object with any of the keys described below.

Name Type Description
type string Specify “direct” to include direct visitors.
google array An array of types of Google Search to be handled by this tracker. Possible values are “paid” and “organic”.
bing array An array of types of Bing Search to be handled by this tracker. Possible values are “paid” and “organic”.
yahoo array An array of types of Yahoo Search to be handled by this tracker. Possible values are “paid” and “organic”.
landing array An array of values to look for in the landing page URL. These values are used for simple string matching and can match path names, file names, URL parameter names, and URL parameter values.
referrer array An array of values to look for in the referring page. These values are used for simple string matching and are most commonly used as a list of domain names to match.
inverted boolean Set to true to invert the matching rules. Default is false. When set as true, visitors not matching the previously defined rules will see a tracking number from this Session Tracker pool.

Source Tracker Call Sources

The Call Source object describes the type of website visitor who will see this tracking number. (Source Trackers can alternatively be configured as “offline” trackers for use in offline media such as billboards or TV ads.) Depending on the source type configured, different fields may be present in the Call Source object.

All Call Source objects will have the following:

Name Type Description
type string Indicates the traffic source assigned for this tracking number. One of “all”, “landing_url”, “landing_params”, “offline”, “web_referrer”, “direct”, or “search”.
// Show this number to all website visitors
"source": {
  "type": "all"
}

All Visitors

A value of "all" indicates that all online traffic will see the number associated with this tracker. There are no other fields in the object.

Note that this can also be used as a catch-all setting. If any other Source Tracker or Session Tracker would match a given visitor, that number will take precedence over this configuration.

// Show this number to any visitor who first lands on "www.example.com/promo1"
"source": {
  "type": "landing_url"
  "landing": "www.example.com/promo1"
}

Landing URL

A value of "landing_url" indicates that online visitors who first land on a specific webpage will be shown the tracking number. The tracking number will persist for the visitor even as they navigate to other pages on the site.

Name Type Description
type string “landing_url”
landing string The landing page URL that will trigger this number to be served.
Example “www.example.com/promo1”
// Show this number to any visitor who first lands on a page with
// "promo=1" in the URL parameters
"source": {
  "type": "landing_params"
  "landing": "promo=1"
}

Landing Parameters

A value of "landing_params" indicates that online visitors who first land on a page with the specified query parameters will be served the tracking number. The tracking number will persist for the visitor as they navigate to other pages on the site, even without the landing parameter present.

Name Type Description
type string “landing_params”
landing string The query parameters that will trigger this number to be served.
Example “promo=1”
// Never swap this number on the website. This number is reserved for
// offline use, or non-webpage online use.
"source": {
  "type": "offline"
}

Offline

A value of "offline" means that this Source Tracker is associated with an offline campaign such as a TV or Print advertisement. The tracking phone number will not be served to any web traffic.

// Show this number to any visitor who arrives with a referrer matching "facebook.com".
"source": {
  "type": "web_referrer"
  "referrer": "facebook.com"
}

Web Referrer

A value of "web_referrer" indicates that this phone number will be served when a visitor arrives from a specific referring website.

Name Type Description
type string “web_referrer”
referrer string The referring website that will trigger this number to be served.
Example “facebook.com”
// Show this number to any visitor who visits the site directly.
"source": {
  "type": "direct"
}

Direct

A value of "direct" indicates that this tracking number will be served to web visitors who visit the page directly, without being referred from another site.

// Show this number to all Adwords visitors
"source": {
  "type": "search",
  "search_engine": "google",
  "search_type": "paid"
}

// Show this number to all PPC visitors
"source": {
  "type": "search",
  "search_engine": "all",
  "search_type": "paid"
}

// Show this number to visitors from Google search
"source": {
  "type": "search",
  "search_engine": "google",
  "search_type": "all"
}

A value of "search" indicates that this number should be served to visitors who arrived on the page from a given search engine and search type.

Name Type Description
type string “search”
search_engine string The name of the search engine. One of “google”, “yahoo”, “bing”, or “all”.
Example: “google”
search_type string The type of search traffic. One of “paid”, “organic”, “local”, “organic_local”, or “all”.
Example: “paid”

Users

A user represents a specific person with access to your account who can view and interact with your call data. Users are identified by an email address, and have an assigned role that controls the privileges they have within your account.

User Roles

Administrators have complete access to every company in your account. They can add companies, users, and tracking numbers. They also have access to all configurations, including creating call flows, adding call tags, company customizations, and billing and invoice information. These users are identified by the role admin.

Managers can create and edit tracking phone numbers and call flows within their companies. They may add and edit users within those companies. They’ll also have the same permissions as Reporting and Notification users as outlined below. These users are identified by the role manager.

Reporting users can view calls, text messages, and reports about the data associated with their companies. They can make notes on calls, listen to recorded calls, and tag and score calls. They’ll also have the same notification configuration options as the users outlined below. These users cannot create or modify tracking numbers or other settings. These users are identified by the role reporting.

Notification users can be configured to receive email notifications for incoming calls and texts to tracking numbers, and to receive scheduled summary emails. They can listen to recorded calls if they receive an email about the call. These users cannot otherwise login to the CallRail web interface. These users are identified by the role notification.

Listing All Users

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/users.json"

The above command returns a JSON structured object like this:

{
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_records": 3,
  "users": [
    {
      "email": "kevin@example.com",
      "id": 286700463,
      "created_at": "2011-04-06T16:38:27.505-04:00",
      "role": "admin",
      "first_name": "Kevin",
      "last_name": "Mann",
      "name": "Kevin Mann"
    },
    {
      "email": "andy@example.com",
      "id": 245038451,
      "created_at": "2011-06-09T14:12:57.842-04:00",
      "role": "admin",
      "first_name": "Andy",
      "last_name": "Powell",
      "name": "Andy Powell"
    },
    {
      "email": "elliott@example.com",
      "id": 166715485,
      "created_at": "2013-08-10T11:18:00.001-04:00",
      "role": "admin",
      "first_name": "Elliott",
      "last_name": "Wood",
      "name": "Elliott Wood"
    }
  ]
}

This endpoint returns a paginated array of users within the target account.

API Endpoint

Method URL
GET /v2/a/{account_id}/users.json

Request Parameters

This endpoint supports Pagination, Sorting, and Searching.

Name Type Required? Description
company_id integer optional Limit response to users belonging to a single company.

Sorting is available for the following fields:

Searching is available for the following fields:

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
email string The email address associated with this user.
id integer Unique identifier for the user.
created_at string The date and time the user was created in UTC (ISO 8601 format).
role string The user’s permission within this CallRail account. One of “admin”, “reporting”, “manager” or “notification”.
first_name string The user’s first name.
last_name string The user’s last name.
name string Full name of the user formatted for display.

Retrieving a Single User

curl -H "Authorization: Token token={api_token}" \
     -X GET \
     "https://api.callrail.com/v2/a/{account_id}/users/{user_id}.json"

The above command returns a JSON structured object like this:

{
  "email": "kevin@example.com",
  "id": 286700463,
  "created_at": "2011-04-06T16:38:27.505-04:00",
  "role": "admin",
  "first_name": "Kevin",
  "last_name": "Mann",
  "name": "Kevin Mann",
  "companies": [
    {
      "id": 213472384,
      "name": "Widget Shop"
    },
    {
      "id": 196207137,
      "name": "Bob's Burgers"
    },
    {
      "id": 221426002,
      "name": "Mos Eisley Cantina"
    }
  ]
}

This endpoint returns a single user object in the target account.

API Endpoint

Method URL
GET /v2/a/{account_id}/users/{user_id}.json

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
email string The email address associated with this user.
id integer Unique identifier for the user.
created_at string The date and time the user was created in UTC (ISO 8601 format).
role string Whether or not the user is active or disabled.
first_name string The user’s first name.
last_name string The user’s last name.
name string Full name of the user formatted for display.
companies JSON JSON array of all companies the user is associated with.

Creating a User

curl -H "Authorization: Token token={api_token}" \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{
          "first_name": "Bob",
          "last_name": "Belcher",
          "email": "bob@example.com",
          "role": "reporting",
          "companies": [252993629, 189409482],
          "password": "password1234" // Do not use this password //
        }' \
        "https://api.callrail.com/v2/a/{account_id}/users.json"

The above command returns a JSON structured object like this:

{
  "email": "bob@example.com",
  "id": 417722128,
  "created_at": "2017-01-13T13:01:17.320-05:00",
  "role": "reporting",
  "first_name": "Bob",
  "last_name": "Belcher",
  "name": "Bob Belcher",
  "companies": [
    {
      "id": 252993629,
      "name": "Widget Shop 2"
    },
    {
      "id": 189409482,
      "name": "Widget Shop"
    }
  ]
}

This endpoint creates a single user object in the target account.

API Endpoint

Method URL
POST /v2/a/{account_id}/users.json

Request Body

The request body below is standard for all Users.

Name Type Required? Description
first_name string required The user’s first name.
last_name string required The user’s last name.
email string required The email address the user will use to log in to CallRail and receive call or text message notifications.
role string required What level of access the user should have to your CallRail Account or Companies. One of “admin”, “reporting”, “manager”, or “notification”.

Account Administrators

Name Type Required? Description
password string optional The password the user will use to log in to CallRail. If not set, an email will be sent to the user prompting them to set the password.

Manager and Reporting

Name Type Required? Description
password string optional The password the user will use to log in to CallRail. If not set, an email will be sent to the user prompting them to set the password.
companies array required A list of company IDs that the user should be able to access.

Notification

Name Type Required? Description
companies array required A list of company IDs that the user should be able to access.

Response Fields

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
email string The email address associated with this user.
id number Unique identifier for the User.
created_at string The date and time the user was created in UTC (ISO 8601 format).
role string The user’s permission within this CallRail account.
first_name number The user’s first name.
last_name string The user’s last name.
name string The full name of the user formatted for display.
companies JSON JSON array of all companies the user is associated with.

Updating a User

curl -H "Authorization: Token token={api_token}" \
     -X PUT \
     -H "Content-Type: application/json" \
     -d '{
          "first_name": "Gene",
          "email": "gene@example.com",
          "old_password": "password1234", // Do not use this password //
          "new_password": "1234password" // Do not use this password //
        }' \
        "https://api.callrail.com/v2/a/{account_id}/users/{user_id}.json"

The above command returns JSON structured object like this:

{
  "email": "gene@example.com",
  "id": 417722128,
  "created_at": "2017-01-13T13:01:17.320-05:00",
  "role": "reporting",
  "first_name": "Gene",
  "last_name": "Belcher",
  "name": "Gene Belcher",
  "companies": [
    {
      "id": 252993629,
      "name": "Widget Shop 2"
    },
    {
      "id": 189409482,
      "name": "Widget Shop"
    }
  ]
}

This endpoint updates a single user object in the target account.

API Endpoint

Method URL
PUT /v2/a/{account_id}/users/{user_id}.json

Request Body

The request body below is standard for all Users.

Name Type Required? Description
first_name string optional The user’s first name.
last_name string optional The user’s last name.
email string optional The email address the user will use to log in to CallRail and receive call or text message notifications.

Account Administrators

Name Type Required? Description
old_password string optional The password the user previously used to log in to CallRail.
new_password string optional The new password the user would like to use to log in to CallRail.
reset_password boolean optional If true, sends an email to the user prompting them to set the password.

Manager and Reporting

Name Type Required? Description
old_password string optional The password the user previously used to log in to CallRail.
new_password string optional The new password the user would like to use to log in to CallRail.
reset_password boolean optional If true, sends an email to the user prompting them to set the password.
companies array optional A list of company IDs that the user should be able to access. To remove a user from one or more companies, only include company IDs the user should be able to access.

Notification

Name Type Required? Description
companies array optional A list of company IDs that the user should be able to access. To remove a user from one or more companies, only include company IDs the user should be able to access.

Response Field

When successful, the HTTP response code will indicate 200 OK.

Name Type Description
email string The email address associated with this user.
id number Unique identifier for the User.
created_at string The date and time the user was created in UTC (ISO 8601 format).
role string The user’s permission within this CallRail account; one of “admin”, “reporting”, “manager” or “notification”.
first_name number The user’s first name.
last_name string The user’s last name.
name string The full name of the user formatted for display.
companies JSON JSON array of all companies the user is associated with. Includes the company id and company name.

WEBHOOKS

Introduction

Webhooks are notifications sent out by CallRail for certain events that happen in your account. They allow software developers to send real-time call notifications to web applications and reporting systems. These are most useful when you wish to be notified automatically when something happens, rather than having to poll the API.

Once webhooks is set up, it sends an HTTP POST request to a URL endpoint of your choice. There are three types of webhooks for calls: Pre-Call, Post-Call, and Call Modified. Additionaly, there are webhooks for Text Messages and Form Submissions.

You can create a webhook from inside your account. When doing so, you’ll specify the URL that should receive the data, as well as the events that trigger the webhook. You can also create and configure a webhook through CallRail’s API.

All attributes are available in the JSON POST body, which is the recommended format for any new development. A limited number of attributes are available in the query string because of the legacy version of our API. Currently, additions and updates are only made to the JSON POST body; therefore, we recommend parsing the JSON POST body and ignoring the query string parameters according to the currently-supported version of our API.

Responding

Your endpoint should respond with a HTTP status code of 2xx to indicate that the data was received properly. In general, a response status code other than 2xx indicates that the webhook was unable to complete the requested action.

When a non-2xx response is received, you may notice missing webhooks or calls on your end. CallRail does not resend webhooks, so missing calls might be your first indication of a problem. Repeated failed webhooks could result in an automated disabling of the webhook integration.

Common reasons for invalid response codes include errors in the receiving endpoint’s URL (typos or invalid URLs), as well as the receiving server not accepting URLs over a certain amount of characters.

Events

Below are the events that are currently available to trigger a webhook.

Pre-Call

The pre-call webhook executes the moment an inbound phone call is received by CallRail. Your server will receive the call information before the call is connected, allowing you to develop real-time systems for your representatives, such as screen-pops or CRM database lookups.

Because the pre-call webhook executes before the call is connected, it contains less information than the post-call webhook. For example, the post-call webhook will contain the call duration, whether the call was answered, and a link to the recording (if applicable).

This webhook sends the call object in the POST body, formatted as JSON as specified in the call endpoint. See Retrieving a Single Call for details. Additional fields are returned in the JSON and GET request line because of our Legacy API; however, we encourage users to build requests using the parameters outlined in this version of our API documentation for support purposes.

Post-Call Webhook

The post-call webhook executes immediately after an inbound phone call has completed. It contains the full data about the call.

This webhook sends the call object in the POST body, formatted as JSON as specified in the call endpoint. See Retrieving a Single Call for details. For legacy purposes some additional fields are returned in the JSON and in the GET request line, but new implementations are strongly encouraged not to rely upon parameters other than the ones currently documented.

Call Modified

Please note that the fields in the call modified webhook will already contain the modified information. The "changes" key will then contain an array of the fields modified.

 {
  ...
  "note":"this is a note written after the call was completed",
  ...
  "changes":["note"]
}

Call modified webhooks are sent when a call has changed after it’s ended. For example, if you add a tag or a note to a call after the call has ended, you’d use a call modified webhook to retrieve the latest version of the call. This webhook also contains a field called changes that notes which fields changed (like “note”, ”recording”, ”tag”). Please note, this webhook also fires when a call has been marked as spam.

Call modified webhooks send the call object in the POST body, formatted as JSON as specified in the call endpoint. See Retrieving a Single Call for details. Additional fields are returned in the JSON and GET request line because of our Legacy API; however, we encourage users to build requests using the parameters outlined in this version of our API documentation for support purposes.

Key Description
changes An array of the changes to the call that triggered the call modified webhook appended to the end of the normal response fields. These fields include tags, note, value, transcription_text, recording_duration, auto_score, and manual_score.

Outbound Post Call

Outbound post-call webhooks are sent after an outbound phone call has ended. The primary difference between Post Call Webhooks and Outbound Post Call Webhooks is that it is sent only after an outbound call has completed. As such, the call_type field will be set to "outbound".

This webhook sends the call object in the POST body, formatted as JSON as specified in the call endpoint. See Retrieving a Single Call for details. Additional fields are returned in the JSON and GET request line because of our Legacy API; however, we encourage users to build requests using the parameters outlined in this version of our API documentation for support purposes.

Outbound Call Modified

An outbound call modified webhook is sent when an outbound call has changed after it has ended. For example, if you add a tag or note to an outbound call, you’d use an outbound call modified webhook to retrieve the latest version of the call with the most recent information attached.

This webhook sends the call object in the POST body, formatted as JSON as specified in the call endpoint. See Retrieving a Single Call for details. For legacy purposes, some additional fields are returned in the JSON and in the GET request line, but new implementations are strongly encouraged not to rely upon parameters other than the ones currently documented.

Text Message Received

Text message webhooks are sent after a text message is received.

  {
   "id":879204976,
   "source_number":"770-555-5555",
   "destination_number":"770-123-4567",
   "content":"CallRail is the best! ",
   "received_at":"2017-10-23T15:57:18.826-04:00"
  }

Text message webhooks send after a text message is received by one of your tracking numbers. This webhook includes all information about the message, including the ID for the message, as well as the contents of the message.

Key Description
id Unique identifier for a specific text.
source_number The phone number that sent the text message.
destination_number The tracking number that was texted.
content The content of the text message.
received_at Timestamp of when the text was received with Time Zone offset.

Text Message Sent

Text message webhooks sent after a text message is sent.

 {
   "id":980561249,
   "agent":"Keith Rail",
   "source_number":"770-123-4567",
   "destination_number":"770-555-5555",
   "content":"Well, that is good to know!",
   "sent_at":"2017-10-23T16:00:53.286-04:00"
 }

Text message sent webhooks send after a text message is sent by one of your tracking numbers. This webhook includes all information about the message, including the ID for the message, as well as the contents of the message.

Key Description
id Also Unique identifier for a specific text.
source_number The phone number that sent the text message.
destination_number The number that was texted.
content The content of the text message.
received_at Timestamp of when the text was sent with Time Zone offset.

Form Submission

{
  "id":123456789,
  "company_id":987654321,
  "form_data":
    {
      "form_field1":"this is the message",
      "form_field2":"support@callrail.com",
      "form_field3":"John Q. Customer"
    },
  "form_url":"http://www.example.com/form",
  "landing_page_url":"http://www.example.com/",
  "referrer":"direct",
  "referring_url":"www.google.com",
  "submitted_at":"2017-10-24T09:40:18.000-04:00",
  "first_form":true,
}

Form Submission webhooks send whenever a form is submitted to your website. To retrieve this information, you should have Form Tracking active. This webhook sends information gathered from the form submission, including all recognized form fields.

Key Description
id Unique identifier for a specific form submission.
company_id Unique identifier of the company receiving the form submission.
form_data The contents of the form submission, broken down by form field.
form_url The url of the page from which the form was submitted.
landing_page_url The URL the visitor first landed on.
referrer The URL that referred the visitor to your website.
submitted_at Timestamp of when the form was submitted.
referring_url The referrer’s webpage.
first_form Boolean denoting whether or not this is the first form submitted by this visitor.

Security

For security reasons, you may want to ensure that requests received by your server are sent by CallRail. CallRail includes a Signature header to verify that the request your server has received is valid.

Validating Payloads

If you’re using Ruby, generating the signature to validate the request would look something like this:

  hmac = OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha1'), YOUR_COMPANY_SIGNING_KEY, request_payload)
  signature = Base64.strict_encode64(hmac)

To test your signature computation, use the JSON request body below with a test signing key of 072e77e426f92738a72fe23c4d1953b4. Your computation should return a signature of UZAHbUdfm3GqL7qzilGozGzWV64=

{"answered":false,"business_phone_number":"","call_type":"voicemail","company_id":155920786,"company_name":"Boost Marketing","company_time_zone":"America/Los_Angeles","created_at":"2018-02-19T13:41:00.252-05:00","customer_city":"Rochester","customer_country":"US","customer_name":"Kaylah Mills","customer_phone_number":"+12148654559","customer_state":"PA","device_type":"","direction":"inbound","duration":"13","first_call":false,"formatted_call_type":"Voicemail","formatted_customer_location":"Rochester, PA","formatted_business_phone_number":"","formatted_customer_name":"Kaylah Mills","prior_calls":16,"formatted_customer_name_or_phone_number":"Kaylah Mills","formatted_customer_phone_number":"214-865-4559","formatted_duration":"13s","formatted_tracking_phone_number":"404-555-8514","formatted_tracking_source":"Google Paid","formatted_value":"--","good_lead_call_id":715587840,"good_lead_call_time":"2016-06-17T10:23:33.363-04:00","id":766970532,"lead_status":"previously_marked_good_lead","note":"","recording":"https://app.callrail.com/calls/766970532/recording/redirect?access_key=aaaaccccddddeeee","recording_duration":8,"source_name":"Google AdWords","start_time":"2018-02-19T13:41:00.236-05:00","tags":[],"total_calls":17,"tracking_phone_number":"+14045558514","transcription":"","value":"","voicemail":true,"tracker_id":354024023,"keywords":"","medium":"","referring_url":"","landing_page_url":"","last_requested_url":"","referrer_domain":"","conversational_transcript":"","utm_source":"google","utm_medium":"cpc","utm_term":"","utm_content":"","utm_campaign":"Google AdWords","utma":"","utmb":"","utmc":"","utmv":"","utmz":"","ga":"","gclid":"","integration_data":[{"integration":"Webhooks","data":null}],"keywords_spotted":"","recording_player":"https://app.callrail.com/calls/766970532/recording?access_key=aaaabbbbccccdddd","speaker_percent":"","call_highlights":[],"callercity":"Rochester","callercountry":"US","callername":"Kaylah Mills","callernum":"+12148654559","callerstate":"PA","callsource":"google_paid","campaign":"","custom":"","datetime":"2018-02-19 18:41:00","destinationnum":"","ip":"","kissmetrics_id":"","landingpage":"","referrer":"","referrermedium":"","score":1,"tag":"","trackingnum":"+14045558514","timestamp":"2018-02-19T13:41:00.236-05:00"}

CallRail generates a secret, random token for every company that can be viewed on the Webhooks configuration page inside the application. The token is used with the request payload to generate a hash signature that is passed as a request header in the webhook request. You can use the secret token on your server to recompute the same hash based on the request payload. If your computed signature matches the header that CallRail sends, the request is valid!

The CallRail signature is computed with an HMAC digest of the content of the request. Each webhook request will include a timestamp field based on the data in the request that you can compare to the current time to prevent an unauthorized system from replaying requests.

Swap.js

Getting Started

While most users will not need to do anything beyond installing swap.js on their website, CallRail’s Dynamic Number Insertion script provides a set of options and methods which might be useful to those with advanced use cases.

Dynamic Number Insertion

<body>
  <div>
    <!-- the following phone number will be replaced -->
    <a href="tel:+15551231234">Call me at 555-123-1234</a>
  </div>
  <div data-calltrk-noswap>
    <!-- content inside this element will not be affected -->
    <a href="tel:+15551231234">..</a>
  </div>
</body>

HTML Markup

By default, swap.js replaces any phone numbers on your page that match a configured swap target. If part of a page should not be processed for phone numbers, you can tell swap.js to ignore it by adding a data-calltrk-noswap attribute. When this attribute is present, swap.js will ignore any content inside of that element or it’s children.

This is useful if you wish to show the original number on part of the page, or to improve performance given a page with large sections that do not contain any phone numbers.


/* If this function is called after the page has initially loaded,
 * swap.js have already swapped the numbers and will not know to
 * process the new element. */
function addCallLink() {
  var callLink = document.createElement('div');
  callLink.innerHTML = 'Call us now at 555-123-1234';
  document.body.appendChild(callLink);

  /* At this point, the element is in the DOM and on the page, but the
   * original swap target phone number is being displayed.
   * We can invoke CallTrk.swap() manually to attempt a swap.
   * For performance reasons we can instruct swap.js to only look at
   * the modified element, but if the parameter is omitted the entire
   * page will be re-scanned. */
  CallTrk.swap(callLink);
}

/* This example uses getSwapNumbers to manually perform number swapping.
 * This method may be required if your site is a single-page application
 * and DOM content is managed by a templating engine. */
function addCallLink() {
  CallTrk.getSwapNumbers(['5551231234'], function(result) {
    var callLink = document.createElement('div');
    /* Use the result to fill in the tracking phone number ourselves.
     * Note that you'll likely want to reformat this number to
     * an expected display format for your locale. */
    callLink.innerHTML = "Call us now at " + result['5551231234'];
    document.body.appendChild(callLink);
  });
}

Javascript API

This function causes swap.js to re-scan the DOM and attempt to swap phone numbers again. The parameter is optional. If the parameter is omitted, processing starts at document.body.

If a DOM node is provided as the parameter, the scope will be limited to that node and its children.

If a CSS selector is provided as the parameter, any matching nodes and their children will be searched. Note that swap.js does not depend on jQuery, and therefore the selector is used via document.querySelectorAll(). This is a native Javascript function, and may not support everything supported by jQuery selectors. Behavior may also vary across browsers.

This function provides access to the swap settings for the current page. It is provided for situations in which the Dynamic Number Insertion needs to be performed manually. One common use case is within single-page applications, where a templating engine controls the DOM and would otherwise replace numbers swapped by normal swap.js operations.

This method accepts an array of phone numbers (formatted as 10-digit numbers with no separators), and provides a callback mechanism to swap numbers. Numbers provided as a parameter are appended to a list of numbers already found on the page. The swap mechanism is asynchronous, since a request to CallRail servers may be required to obtain tracking phone numbers in some cases.

The callback function is supplied with one parameter, which is an object with keys representing swap targets and values representing the tracking number to be displayed in its place. Your callback function should handle number insertion or replacement, including any desired formatting.

Note that getSwapNumbers immediately returns the current list of known swap replacements, which may or may not include replacements for all queried numbers. Since numbers may load asynchronously, it is strongly recommended that you use the callback mechanism rather than relying on the return value of this function.

Also note that if no suitable replacements are found, some values from the queried number list may not have a corresponding value in the result provided to your callback function. This can happen if you provide an unknown swap target in the numbers array, but can also happen if your keyword pool is temporarily exhausted.

Form Submission

<body>
  <!-- this form will not be captured -->
  <form action="/search" method="get" data-cr-no-capture>
    <input type="text" placeholder="Search...">
    <input type="submit">
  </form>

  <form action="/request-quote" method="post">
    <input type="text" name="Email">
    <textarea name="Comments"></textarea>
    <!-- this form will be captured,
         but the captcha will be excluded. -->
    <input type="text" name="captcha" data-cr-no-capture>
    <input type="submit">
  </form>
</body>

HTML Markup

When Form Submission is configured, swap.js will capture all forms submitted on a page and submit them to CallRail.

If there are forms you don’t wish to be included, you can mark them with a data-cr-no-capture attribute.

Additionally, you can mark specific <input> tags inside a form with this attribute to prevent it from being submitted along with the rest of the form.

CallTrk.captureForm('#contact-form', function() {
  alert('thank you for your submission!'); 
});

/* or with a form element directly: */
var form = document.querySelector('#contact-form');

CallTrk.captureForm(form, function() {
  alert('thank you for your submission!');
});

Javascript API

CallRail’s Form Submission functionality works automatically for a wide variety of forms; however, sometimes it may be necessary to manually trigger form submissions.

Given a DOM <form> Node or a document.querySelector() String that resolves to a <form>, report the form contents to CallRail, and then trigger the given callback.

EXAMPLES

Grapher - Ruby on Rails

Grapher is intended for anyone who wants to see an example of how to consume CallRail’s API. This example source code includes explanitory comments and a detailed Readme. Code can be found here.