Calls

Contents

Listing All Calls

Return a paginated list of all calls in your Account.

API Endpoint

Method URL
GET /v1/calls.json

Request Parameters

Name Type Required? Description
per_page number optional How many calls to return for this request (default 100, maximum 250).
Example: 25
page number optional Page number that should be returned for this request (the first page is 1).
Example: 3
company_id number optional If provided, only return calls to tracking numbers belonging to this company.
Example: 395108857
tracker_id number optional If provided, only return calls to this specific tracking number.
Example: 415158127
start_date string optional Date or Date and Time in ISO 8601 format. Calls on or after this date will be included.
Example: “2015-09-05T00:00-04:00” for midnight EDT or “2012-09-05” to use midnight UTC
end_date string optional Date or Date and Time in ISO 8601 format. Calls on or before this date will be included.
Example: “2015-09-05T00:00-04:00” for midnight EDT or “2012-09-05” to use midnight UTC
sort string optional Specify the field by which to sort the returned calls. One of customer_name, customer_phone_number, duration, start_time (Default), company or source_type.
order string optional Specify in which order to return the calls, ascending or descending. Should be one of asc (Default) or desc.
call_type string optional If provided, only return calls that match this call type. One of first_call, missed, voicemails, inbound, or outbound.
tags string optional 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.
Example: “Existing Customer”

Response Fields

Name Type Description
id number Unique identifier for the call.
Example: 123618124
direction string Whether the call was inbound (from a customer to you) or outbound (from you to a customer).
Example: “inbound”
start_time string The date and time the call started at in UTC (ISO 8601 format).
Example: “2011-07-05T19:06:10Z”
tracking_number string The business’ tracking phone number for this call (in E.164 format).
Example: “+17701112222”
formatted_tracking_number string The business’ tracking phone number for this call formatted for display.
Example: “770-111-2222”
destination_number string The phone number that rang (in E.164 format).
Example: “+17701114444”
customer_phone_number string The customer’s phone number (in E.164 format).
Example: “+17701234567”
formatted_customer_phone_number string The customer’s phone number for display.
Example: “770-123-4567”
customer_name string The customer’s name, as reported by Caller ID.
Example: “Kevin Mann”
formatted_customer_name string The customer’s name with certain values stylized for display.
Example: “(unavailable)”
customer_city string The customer’s city, based on the original assigned location of their phone number.
Example: “Atlanta”
customer_state string The 2-character abbreviation for the customer’s state, based on the original assigned location of their phone number.
Example: “GA”
formatted_customer_name_or_phone_number string The name or phone number of the customer as reported by Caller ID, formatted for display.
Example: “Kevin Mann”
formatted_customer_city_and_state string The customer’s location, formatted as “City, ST”.
Example: “Atlanta, GA”
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.
Example: “30047”
customer_country string The customer’s country, based on the area code of their phone number.
duration number The duration of the call in seconds.
Example: 131
formatted_duration string The duration of the call formatted for display.
Example: 1m 11s
created_at string The date and time the call was created in UTC, in ISO 8601 format.
Example: “2011-07-05T19:06:10Z”
answered boolean Whether or not the call was answered.
Example: true
first_call boolean Whether or not the call is the caller’s first call to this company.
Example: true
note string Any notes that have been attached to the call via the CallRail dashboard.
Example: “Caller requested return call”
value string A value that has been assigned to the call via the CallRail dashboard
Example: 195.00
formatted_value string The value of the call assigned via the CallRail dashboard, formatted as currency or “–” if not set.
Example: $194.00
recording_duration number The length in seconds of the recording, if available
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.
Example: “http://app.callrail.com/calls/227799611/recording/redirect?access_key=3b91eb7f7cc08a4d01ed”
recording_player string The URL for the stand-alone recording player for this call, if available
Example: “http://app.callrail.com/calls/227799611/recording?access_key=3b91eb7f7cc08a4d01ed”
tag string DEPRECATED The call’s first tag, if set in the CallRail dashboard, Uncategorized otherwise
Example: “New Lead”
tags array The call’s tags, if set in the CallRail dashboard, empty array otherwise.
Example: [“New Lead”, “Sales”]
source_id number The unique id of the source the call belongs to.
Example: 123456789
source_name string The name of the source
Example: “Bob’s Car Garage Spring Mailer”
formatted_tracking_source string The name of the call source formatted for display.
Example: “Google Paid”
company_id number The numeric id of the company the call belongs to
Example: 123456789
company_name string The name of the company the source belongs to
Example: “Bob’s Auto Garage”
utm_source string utm_source as captured from the landing page parameter for Session Trackers, or as specified in the configuration for Source Trackers.
Example: “bing”
utm_medium string utm_medium as captured from the landing page parameter, or as specified in the configuration for Source Trackers.
Example: “PPC”
utm_campaign string utm_campaign as captured from the landing page parameter, or as specified in the configuration for Source Trackers.
Example: “Display”
voicemail boolean true if this call resulted in a voicemail message.
transcription string If this call resulted in a voicemail, and transcription is enabled, contains the transcribed voicemail text.
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.
Example: “good_lead”
caller_name string DEPRECATED See customer_name
caller_number string DEPRECATED See customer_phone_number
caller_city string DEPRECATED See customer_city
caller_state string DEPRECATED See customer_state
caller_zip string DEPRECATED See customer_zip
caller_country string DEPRECATED See customer_country

In addition, calls that were made to a Session Tracker (Keyword Pool) include the following fields:

Name Type Description
last_active_at string The date and time the caller was last active on your website, in UTC, in ISO 8601 format.
Example: “2011-07-05T19:06:10Z”
medium string “PPC” or “Organic”
utma string Google Analytics _utma value.
Example: “54326476.1583134706.1347902844.1347901841.1347901544.1”
utmb string Google Analytics _utmb value.
Example: “54326476.3.10.1347901844”
utmc string Google Analytics _utmc value.
Example: “54326476”
utmv string Google Analytics _utmv value.
Example: “169871586.|1=l=/=1^3=r=www.google.com/url?sa=t&source=web&cd=16&ved==1”
utmz string Google Analytics _utmz value.
Example: “54326476.1347901844.1.1.utmcsr=google|utmccn=(organic)|utmcmd=organic|utmctr=(not provided)”
ga string Google Universal Analytics _ga value.
Example: “GA1.2.1344132132.1396882288”
gclid string gclid as captured from the landing page parameter
Example: “COmA2vj3268CFUhl7Aodp3E45A”
ip string The caller’s most recent IP address.
Example: “68.24.99.102”
utm_term string utm_term as captured from the landing page parameter.
Example: “call tracking”
utm_content string utm_content as captured from the landing page parameter.
Example: “Atlanta”
keywords string The keywords the visitor searched for.
Example: “call tracking”
landing_page_url string The URL the caller first landed on.
Example: “http://www.callrail.com/”
referring_url string The URL that referred the caller to your website.
Example: “http://atlanta.craigslist.org”
last_requested_url string The URL of the active page at the time the call was placed.
Example: “http://www.callrail.com”

Example

curl -H "Authorization: Token token=abc1234" \
  https://api.callrail.com/v1/calls.json?per_page=250&page=1
{
  "page": 1,
  "per_page": 250,
  "total_pages": 29,
  "total_records": 28104,
  "calls": [
    {
      "id": 227799611,
      "tracking_number": "+16782562476",
      "destination_number": "+17705985444",
      "caller_number": "+16677858774",
      "caller_name": "Kevin Mann",
      "caller_city": "ATLANTA",
      "caller_state": "GA",
      "caller_zip": "30305",
      "caller_country": "US",
      "customer_phone_number": "+16677858774",
      "customer_name": "Kevin Mann",
      "customer_city": "ATLANTA",
      "customer_state": "GA",
      "customer_zip": "30305",
      "customer_country": "US",
      "duration": 131,
      "created_at": "2012-06-20T19:19:52Z",
      "answered": true,
      "note": null,
      "value": null,
      "recording": "http://app.callrail.com/calls/227799611/recording/redirect?access_key=3b91eb7f7cc08a4d01ed",
      "recording_player": "http://app.callrail.com/calls/227799611/recording?access_key=3b91eb7f7cc08a4d01ed",
      "tag": "",
      "source_id": 154093037,
      "source_name": "Bob's Car Garage Spring Mailer",
      "company_id": 245874536,
      "company_name": "Bob's Auto Garage",
      "last_active_at": "2012-08-20T19:19:52Z",
      "medium": null,
      "utma": null,
      "utmb": null,
      "utmc": null,
      "utmv": null,
      "utmz": null,
      "utmx": null,
      "gclid": null,
      "ip": null,
      "utm_source": null,
      "utm_medium": null,
      "utm_term": null,
      "utm_content": null,
      "utm_campaign": null,
      "first_call": true,
      "keywords": null,
      "landing_page_url": null,
      "referring_url": null,
      "last_requested_url": null,
      "lead_status": "good_lead",
      "start_time": "2011-06-21T19:48:20Z"
    },
    ...
  ]
}

Retrieving a Single Call

API Endpoint

Method URL
GET /v1/calls/{call_id}.json

Request Parameters

None

Response Fields

Includes all of the above fields. Additionally, a single call includes:

Name Type Description
prior_calls number 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.
Example: 2
waveforms array Only present if the call was recorded. Contains the URLs of two images representing the volume of the call over time.
Example: [“http://s3.amazonaws.com/calltrk/calls/waveforms/000/primary.png”, “http://s3.amazonaws.com/calltrk/calls/waveforms/000/secondary.png”]

Updating a Single Call

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 /v1/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
tag string optional DEPRECATED The name of a Tag to associate with this call. This tag must exist.
Example: “New Business”
tags array optional Array of tag names to associate with this call. See the documentation for Tag. This tag must exist.
Example: [“New Business”, “Sales”]
note string optional Any text notes to associate with this call.
Example: “Customer requested a call back tomorrow afternoon.”
value number optional A number representing the value of this call.
Example: “24.99”
lead_status string optional A string representing a valid lead status. One of "good_lead", "not_a_lead", or null.
Example: “good_lead”
Warning: 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 successfully updated, the response will be 204 NO CONTENT. If an error occurs, the response code will be 4xx or 5xx and include:

Name Type Description
error string Short description of why the request failed.
Example: “Tag not found”

Example

curl -H "Authorization: Token token=abc1234" \
     -H "Content-Type: application/json"     \   
     -X PUT \
     -v \
     -d '{"note": "call customer back tomorrow", "tag": "New Business", "lead_status": "good_lead"}' \
     https://api.callrail.com/v1/calls/2492175.json
< HTTP/1.1 204 No Content
< Cache-Control: no-cache
< Connection: close
<
* Closing connection 0