Source Trackers

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.

Contents

Listing All Source Trackers

Return all Source Trackers for a specific company.

API Endpoint

Method URL
GET /v1/companies/{company_id}/source_trackers.json

Request Parameters

Name Type Required? Description
per_page number optional How many trackers 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

Response Fields

Name Type Description
id number Unique identifier for this Tracker.
Example: 519217
name string Descriptive Name for this Tracker.
Example: “TV Advertisement”
tracking_numbers array List of tracking phone numbers for this Tracker.
Example: ["+15558675309"]
company object Basic information on which company owns this Tracker.
Example: {"id": 21981, "name": "Bob's Auto Shop"}
sms_enabled boolean Whether or not this tracker will route text messages.
Example: false
recording_enabled boolean DEPRECATED: This field is now part of the call_flow object.
Whether or not this tracker records inbound calls.
Example: true
call_flow object An object describing how calls are routed for this Tracker. See Call Flow.
source object An object describing the source of the calls that this tracker will handle. See Source Tracker - Call Sources.
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.
Example: Call from Facebook.
created_at string The date and time the Tracker was created in UTC (ISO 8601 format).
Example: “2011-07-05T19:06:10Z”
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.
Example: “2011-07-05T19:06:10Z”

Example

curl -H "Authorization: Token token=abc1234" \
  https://api.callrail.com/v1/companies/579122/source_trackers.json?per_page=100&page=1
{
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_records": 4,
  "source_trackers": [
    {
      "id": 316716820,
      "name": "Billboard Ad",
      "disabled_at": null,
      "created_at": "2013-05-19T18:04:11Z",
      "company": {
        "id": 241369837,
        "name": "Bob's Auto Garage"
      },
      "sms_enabled": false,
      "recording_enabled": true,
      "whisper_message": "Call from Billboard Ad",
      "tracking_numbers": [
        "+15551578756"
      ],
      "call_flow": {
        "type": "basic",
        "recording_enabled": true,
        "destination_number": "+15558675309",
        "greeting_text": null,
        "greeting_recording_url": "https://example.com/recordings/greeting.mp3?1401993577"
      },
      "source": {
        "type": "offline"
      }
    {
      "id": 306564398,
      "name": "Radio Ad",
      "disabled_at": null,
      "created_at": "2013-05-19T18:05:55Z",
      "company": {
        "id": 241369837,
        "name": "Bob's Auto Garage"
      },
      "sms_enabled": true,
      "recording_enabled": true,
      "whisper_message": "Call from Radio Ad",
      "tracking_numbers": [
        "+15551481935"
      ]
    },
    {
      "id": 253276911,
      "name": "Paid Search Ad",
      "disabled_at": null,
      "created_at": "2013-05-19T18:07:50Z",
      "company": {
        "id": 241369837,
        "name": "Bob's Auto Garage"
      },
      "sms_enabled": true,
      "recording_enabled": true,
      "whisper_message": "Call from Paid Search Ad",
      "tracking_numbers": [
        "+15558722479"
      ],
      "call_flow": {
        "type": "basic",
        "recording_enabled": true,
        "destination_number": "+15558675309",
        "greeting_text": "Thanks for calling! This call may be recorded for quality assurance.",
        "greeting_recording_url": null
      },
      "source": {
        "type": "search",
        "search_engine": "google",
        "search_type": "paid"
      }
    },
    {
      "id": 236871070,
      "name": "Facebook Traffic",
      "disabled_at": null,
      "created_at": "2013-05-19T18:09:42Z",
      "company": {
        "id": 241369837,
        "name": "Bob's Auto Garage"
      },
      "sms_enabled": false,
      "recording_enabled": false,
      "whisper_message": "Call from Facebook Traffic",
      "tracking_numbers": [
        "+15553683862"
      ],
      "call_flow": {
        "type": "basic",
        "recording_enabled": false,
        "destination_number": "+15558675309",
        "greeting_text": null,
        "greeting_recording_url": null
      },
      "source": {
        "type": "web_referrer",
        "referrer": "facebook.com"
      }
    }
  ]
}

Retrieving a Single Source Tracker

Get detailed information about a single source tracker for a given company.

API Endpoint

Method URL
GET /v1/companies/{company_id}/source_trackers/{tracker_id}.json

Request Parameters

None

Response Fields

Name Type Description
id number Unique identifier for this Tracker.
Example: 519217
name string Descriptive Name for this Tracker.
Example: “TV Advertisement”
tracking_numbers array List of tracking phone numbers for this Tracker.
Example: ["+15558675309"]
company object Basic information on which company owns this Tracker.
Example: {"id": 21981, "name": "Bob's Auto Shop"}
sms_enabled boolean Whether or not this tracker will route text messages.
Example: false
recording_enabled boolean DEPRECATED: This field is now part of the call_flow object.
Whether or not this tracker records inbound calls.
Example: true
call_flow object An object describing how calls are routed for this Tracker. See Call Flow.
source object An object describing the source of the calls that this tracker will handle. See Source Tracker - Call Sources.
call_alerts array List of users who will be notified when this tracker receives a call.
Example: [{ "first_name": "John", "last_name": "Robertson", id: "12", "email": "john@example.com"}]
sms_alerts array List of users who will be notified when this tracker receives a text message.
Example: [{ "first_name": "John", "last_name": "Robertson", id: "12", "email": "john@example.com"}]
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.
Example: Call from Facebook.
created_at string The date and time the Tracker was created in UTC (ISO 8601 format).
Example: “2011-07-05T19:06:10Z”
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.
Example: “2011-07-05T19:06:10Z”

Example

curl -H "Authorization: Token token=abc1234" \
  https://api.callrail.com/v1/companies/579122/source_trackers/16021421.json
{
  "id": 160214210,
  "name": "TV Ad",
  "created_at": "2013-05-19T17:52:12Z",
  "disabled_at": null,
  "tracking_numbers": [
    "+14044276267"
  ],
  "sms_enabled": true,
  "recording_enabled": false,
  "whisper_message": "Call from TV Ad",
  "call_flow": {
    "type": "basic",
    "recording_enabled": false,
    "destination_number": "+14041234567",
    "greeting_text": null,
    "greeting_recording_url": null
  },
  "source": {
    "type": "offline"
  },
  "call_alerts": [
    {
      "id": 300390903,
      "first_name": "John",
      "last_name": "Robertson",
      "email": "john@example.com",
      "created_at": "2014-05-19T13:47:47-04:00",
      "role": "admin"
    },
    {
      "id": 5120817,
      "first_name": "Kelly",
      "last_name": "Johnson",
      "email": "kelly@example.com",
      "created_at": "2014-05-19T13:47:47-04:00",
      "role": "notification"
    }
  ],
  "sms_alerts": [
    {
      "id": 5120817,
      "first_name": "Kelly",
      "last_name": "Johnson",
      "email": "kelly@example.com",
      "created_at": "2014-05-19T13:47:47-04:00",
      "role": "notification"
    }
  ]
}

Creating a Source Tracker

Create a new source tracker for a given company.

API Endpoint

Method URL
POST /v1/companies/{company_id}/source_trackers.json

Request Body

Name Type Required? Description
name string required A descriptive name for this tracker.
Example: “Radio Ad 2014”
call_flow object required An object describing what happens to the client’s call. See Call Flow.
tracking_number object required An object describing what constraints the tracking phone number should have. See Creating 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.
Example: “7705551234”
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.
Example: Call from Facebook.

Example

echo '
{
  "name": "My Billboard",
  "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"
  },
  "swap_target": "7705551234",
  "whisper_message": "Call from My Billboard"
}
' |
curl -H "Authorization: Token token=abc1234" \
     -H "Content-Type: application/json"     \
     -d @-                                   \
  https://api.callrail.com/v1/companies/12512/source_trackers.json
{
  "id": 127163,
  "name": "My Billboard",
  "created_at": "2014-03-20T15:42:00Z",
  "disabled_at": null,
  "sms_enabled": true,
  "recording_enabled": false,
  "whisper_message": "Call from My Billboard",
  "company": {
    "id": 12512,
    "name": "Ron's Surf Shop"
  },
  "call_flow": {
    "type": "basic",
    "recording_enabled": false,
    "destination_number": "+15553104554",
    "greeting_text": "This call will be recorded for quality assurance"
  },
  "source": {
    "type": "search",
    "search_engine": "google",
    "search_type": "organic",
  },
  "tracking_numbers": [
    "+15554512700"
  ]
}

Deleting a Source Tracker

Disabling a source tracker will permanently release it. This action is immediate and cannot be undone.

API Endpoint

Method URL
DELETE /v1/companies/{company_id}/source_trackers/{tracker_id}.json

Request Parameters

None.

Response Fields

None. On success, response will be 204 NO CONTENT.

Example

curl -H "Authorization: Token token=abc1234" \
  -X DELETE \
  -v \
  https://api.callrail.com/v1/companies/291571/source_trackers/5.json
< HTTP/1.1 204 No Content
< Cache-Control: no-cache
< Connection: close
<
* Closing connection 0

Call Sources

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

All Call Source objects will have the following:

Name Type Description
type string Which traffic source will be served this tracking number. One of “all”, “landing_url”, “landing_params”, “offline”, “web_referrer”, “direct”, or “search”.

All

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

Landing URL

A value of "landing_url" indicates that online visitors who first land on a specific webpage will be served 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”

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 “promo1=true”

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.

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”

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.

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”