NAV
shell

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 provides call analytics to companies and marketing agencies. CallRail helps data-driven marketers optimize the performance of 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 the user sees 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 clients 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, the keywords they searched for before arriving via search engine, and 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 - Referring to either the source tracker or keyword pool in question. 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) are configured to track. Our company specific DNI JavaScript code will only swap in 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 the UI. Calls placed to accounts or companies to which 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.

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.

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",
    "customer_zip": null,
    "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.

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

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.

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 configurations. Calls and other activity 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,
        "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,
        "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,
        "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.
callscribe_enabled boolean Whether CallScribe is enabled.
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 Option not to include CallRail’s bundled version of jQuery. You must load jQuery on every page before swap.js. CallRail’s DNI script requires jQuery version v1.10.1 or later.
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.

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,
    "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.
callscribe_enabled boolean Whether CallScribe is enabled.
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 Option not to include CallRail’s bundled version of jQuery. You must load jQuery on every page before swap.js. CallRail’s DNI script requires jQuery version v1.10.1 or later.
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.

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,
  "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.
lead_scoring_enabled boolean Whether or not the company has manual lead scoring enabled.
swap_exclude_jquery boolean Option not to include CallRail’s bundled version of jQuery. You must load jQuery on every page before swap.js. CallRail’s DNI script requires jQuery version v1.10.1 or later.
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,
  "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.
callscribe_enabled boolean options Turns the CallScribe feature on or off for this company.
time_zone string optional Time Zone configured for this company. See List of Timezones.
swap_exclude_jquery boolean optional Option not to include CallRail’s bundled version of jQuery. You must load jQuery on every page before swap.js. CallRail’s DNI script requires jQuery version v1.10.1 or later.
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.
callscribe_enabled boolean Whether CallScribe is enabled.
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 Option not to include CallRail’s bundled version of jQuery. You must load jQuery on every page before swap.js. CallRail’s DNI script requires jQuery version v1.10.1 or later.
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.

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

Users

A User represents a specific person with access to your account to 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 call and text message activity, 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 required The password the user will use to log in to CallRail.

Manager and Reporting

Name Type Required? Description
password string required The password the user will use to log in to CallRail.
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"
        }' \
        "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
password string optional The password the user will use to log in to CallRail.

Manager and Reporting

Name Type Required? Description
password string optional The password the user will use to log in to CallRail.
companies array optional A list of company IDs that 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.

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.

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 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,
      "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].",
      "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 and Filtering.

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

Filtering is available for the following:

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.
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].",
  "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.
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_target": "7705551234",
            "whisper_message": "Call from [source]",
            "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"],
  "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 object optional 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_target string optional The telephone number to target on your website. We will search for this number on your website and replace it with your tracking phone number. You do not need to format this number, we will look for all possible formats. If no swap target is 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.

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.
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"
            },
            "source": {
              "type": "search",
              "search_engine": "google",
              "search_type": "organic"
            },
            "type": "source",
            "swap_target": "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"],
  "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.
swap_target string optional The telephone number to target on your website. We will search for this number on your website and replace it with your tracking phone number. You do not need to format this number, we will look for all possible formats. If no swap target is 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.
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_target": "7704761456",
            "whisper_message": "Call from [source]",
            "pool_size": 4,
            "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"],
  "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 object 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_target string optional The telephone number to target on your website. We will search for this number on your website and replace it with your tracking phone number. You do not need to format this number, we will look for all possible formats.
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 Session Tracker 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 “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.
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"
            },
            "swap_target": "7705551234",
            "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"],
  "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 object 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_target string optional The telephone number to target on your website. We will search for this number on your website and replace it with your tracking phone number. You do not need to format this number, we will look for all possible formats. If swap_target is set to null, 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 object optional An object describing which visitors will be served this tracker. See Source Tracker 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.
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”

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",
      "customer_zip": null,
      "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
    },
    {
      "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",
      "customer_zip": null,
      "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
    }
  ]
}

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:

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.
customer_zip string The customer’s 5 digit zip code, based on the original assigned location of their phone number. This data is not available for most calls placed after 2014.
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 If provided, only return calls that have had the given tag applied. This parameter can be provided as tags=A for a single tag, or tags[]=A&tags[]=B to return calls tagged with either tag A or tag B.
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.

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",
  "customer_zip": null,
  "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
}
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",
  "customer_zip": null,
  "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,
  "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.
customer_zip string The customer’s 5 digit zip code, based on the original assigned location of their phone number. This data is not available for most calls placed after 2014.
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 If provided, only return calls that have had the given tag applied. This parameter can be provided as tags=A for a single tag, or tags[]=A&tags[]=B to return calls tagged with either tag A or tag B.
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.
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.

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",
  "customer_zip": null,
  "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.
customer_zip string The customer’s 5 digit zip code, based on the original assigned location of their phone number. This data is not available for most calls placed after 2014.
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",
  "customer_zip": null,
  "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.
customer_zip string The customer’s 5 digit zip code, based on the original assigned location of their phone number. This data is not available for most calls placed after 2014.
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-09T00:00:00-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-04T00:00:00-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
    }
  ]
}

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 100 data points. For larger time spans (for example: longer than 3 months), it is recommended to specify a larger interval such as week or month. If 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 Specifiy the time interval to group response data. Should be one of day, week, ormonth. Defaults today`.
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. 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 summmary date range. This Summary Data response field is available by default.
missed_calls number Total number of calls that were missed in summmary date range.
answered_calls number Total number of calls that were answered in summmary date range.
first_time_callers number Total number of calls that were from first time callers in summmary 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.

Filtering Call 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. This is the default view in the CallRail UI, and is the API default when no other date range parameters are specified.
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
all_time Select all data, including the current date

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 call 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 9, 2015
end_date Provide call 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 9, 2015

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

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.

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

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

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.

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

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.

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.

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

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.

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.