NAV
shell ruby python

Introduction

The CallTrackingMetrics API provides a RESTful interface to call data, phone numbers, text messaging, and account management. To assist in integrating CallTrackingMetrics with your website, we also provide a JavaScript API that allows you to customize how our dynamic number swapping interacts with your website.

You may make requests using any of the following content types in the request header:

Content-Type: application/json

Content-Type: application/x-www-form-urlencoded

Content-Type: multipart/form-data

Make sure the body matches the Content-Type. For example if you are going to submit a JSON body like { "phone_number": "+18085551212" }, make sure to make the request with a Content-Type: application/json header as well.

All REST API endpoints respond with JSON encoded data.

Content-Type: application/json

Authentication

You can access the CallTrackingMetrics API by using the keys directly in all requests, e.g.

curl -X GET "https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/calls.json"
  -u {access_key}:{secret_key}

curl -X GET "https://api.ctmdev.us/api/v1/accounts/{account_id}/calls.json"
  -H 'authorization: Basic MjkyZDM0NWU4YzQ3OTgzZjMxODBmZWExMTdjNGY1ZTA6N2E3ZjJmNzhmZGVhYjAwYzQwM2M1MGM4ODlhODU0MzJkM2I4'

We support two levels of REST API access: single account level and multi account level.

For either level, once you have enabled API access, you will have an Access Key and Secret Key. Once enabled, there are also buttons to reset the keys or disable API access.

You can either pass a username (access key) and password (secret key) or you can use basic access authentication by passing an Authorization header.

Calls

The Calls API allows you easy access to all your call data. You can subscribe to new incoming calls to receive an HTTP request when a call is completed. You can also query the call API to retrieve all past calls.

GET Calls

GET https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/calls.json

Request params

Request parameters are sent via an HTTP GET query string and should be URL Encoded.

Parameter Description
page page offset to query
filter search string to look for calls with specific callerid, caller_number, called_number, source name, etc.
multi_tags[] query param to filter results by one or tag
multi_agents[] query param to filter results by agent user id
menu_key_press query param to filter results by a specific menu key
filter_visitor_data query param to filter results by either calls that include visitor data (set to 1) or calls that lack visitor data (set to 2)
start_date starting date offset to query
end_date ending date offset to query

Sample successful response JSON

{ 
   "calls":[
      {
         "id":54321234,
         "name":"firstname lastname",
         "caller_number":"(ddd) ddd-dddd",
         "search":"keywords searched",
         "referrer":null,
         "location":"http://example.com/",
         "source":"Direct",
         "likelihood":82.0381,
         "duration":36,
         "city":"a city",
         "state":"CA",
         "country":"US",
         "called_at":"2012-08-17 10:24 AM",
         "tracking_number":"(ddd) ddd-dddd",
         "business_number":"(ddd) ddd-dddd",
         "audio":"https://example.com/url/to/audio"
      }
   ],
   "page":1,
   "total_entries":1963,
   "total_pages":197,
   "per_page":10,
   "next_page":"https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/calls.json?page=2",
   "previous_page":"https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/calls.json"
}

Calls JSON Response

Response data will be JSON encoded.

GET Call Detail

GET https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/calls/{call_id}.json

curl -X GET "https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/calls/{call_id}"

Request params

Request parameters are sent via an HTTP GET query string and should be URL Encoded.

Sample successful response JSON

{
    "id": ":call_id",
    "name": "firstname lastname",
    "caller_number": "+1dddddddddd",
    "search": "searched terms",
    "referrer": null,
    "location": "http://example.com/",
    "source": "Direct",
    "likelihood": 82.0381,
    "duration": 36,
    "city": "caller city",
    "state": "PA",
    "country": "US",
    "called_at": "2012-08-17 10:24 AM",
    "tracking_number": "(ddd) ddd-dddd",
    "business_number": "(ddd) ddd-dddd",
    "audio": "https://example.com/url/to/audio",
    "tag_list": ["tag1", "tag2", "tag3"],
    "notes": "notes on the call",
    "latitude": 122.32,
    "longitude": 54.232,
    "campaign": "your-ad-campaign",
    "web_source": "your-ad-source",
    "medium": "your-ad-medium",
    "keyword": "your-ad-keyword",
    "ad_match_type": "your-ad-match-type",
    "ad_slot": "your-ad-slot",
    "ad_slot_position": "your-ad-slot-position",
    "ad_network": "your-ad-network",
    "creative_id": "your-ad-creative_id",
    "adgroup_id": "your-ad-adgroup_id",
    "campaign_id": "your-ad-campaign_id",
    "ad_format": "your-ad-format",
    "ad_targeting_type": "your-ad-targeting-type",
    "visitor": true,
    "visitor_ip": "ipv4 address",
    "ga": {
      "utma": "...",
      "utmb": "...",
      "utmc": "...",
      "utmz": "...",
      "medium": "...",
      "campaign": "..."
    },
    "extended_lookup": {
      "first_name": "Sally",
      "last_name": "Masbey",
      "phone_type": "mobile",
      "street_number": "1812",
      "street_name": "Court ave",
      "gender": "F",
      "city": "Oakland",
      "state": "CA",
      "zipcode": "946192642"
    },
    "inputs": {
      "menu_inputs":["1"],
      "geo_inputs":["60137"]
    },
    "sale": {
      "name": null,
      "score": 5,
      "conversion": true,
      "value": "789.98",
      "date": "2014-04-17T00:00:00Z"
    }
  }

Calls JSON Response

Response data will be JSON encoded.

POST Sale Record

POST /api/v1/accounts/{account_id}/calls/{call_id}/sale

Request params

curl -XPOST https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/calls/{call_id}/sale
          --data-urlencode 'name=Name' \
          --data-urlencode 'score=4' \
          --data-urlencode 'conversion=1' \
          --data-urlencode 'value=850.0'

Request parameters are sent via an HTTP POST and should be URL Encoded.

Parameter Description
score number between 1 and 5 to indicate the quality of the call
value numeric value to represent the total worth of the call in dollars
conversion boolean flag (1 or 0) to indicate whether the call resulted in a sale
sale_date date when a sale occurred as a result of this call
name reporting tag within the call log, typically used as a product name or sales person name

Sample successful response JSON

{
  "success": 1,
  "rep": {
    "sale_date": "2012-01-02",
    "name": "Name",
    "conversion": 1,
    "value": 850.0,
    "score": 4
  }
}

Sale Record JSON Response

Response data will be JSON encoded.

POST Modify Call data

POST https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/calls/{call_id}/modify.json

curl -XPOST --data-urlencode 'name=todd' \
              --data-urlencode 'email=info@example.com' \
              https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/calls/{call_id}/modify.json

Request params

Request parameters are sent via an HTTP POST URL Encoded request body.

Sample successful response JSON

{"status": "true"}

Calls JSON Response

Response data will be JSON encoded with a status flag true or false indicating successful update or failure to update.

POST Stop Recording

POST /api/v1/accounts/{account_id}/calls/{call_id}/recording_stop

Request params

curl -XPOST -u$key:$sec \
  https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/calls/{call_id}/recording_stop

Request parameters are sent via an HTTP POST and should be URL Encoded.

Sample successful response JSON

{"status": "success"}

POST Start Recording

POST /api/v1/accounts/{account_id}/calls/{call_id}/recording_start

Request params

curl -XPOST -u$key:$sec \
  https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/calls/{call_id}/recording_start

Request parameters are sent via an HTTP POST and should be URL Encoded.

Sample successful response JSON

{"status": "success"}

POST FormReactor Server Side Request

POST https://api.calltrackingmetrics.com/api/v1/formreactor/{formreactor_id}

curl -u'{access_key}:{secret_key}' \
      -XPOST https://api.calltrackingmetrics.com/api/v1/formreactor/{formreactor_id} \
      --data-urlencode 'caller_name=Name Field' \
      --data-urlencode 'country_code=1' \
      --data-urlencode 'phone_number=(555) 555-5555' \
      --data-urlencode 'email=customer@example.com' \
      --data-urlencode 'visitor_sid=visitorid' \
      --data-urlencode 'callback_number=555555555' \
      --data-urlencode 'custom_field_128838228=Your Custom Field1' \
      --data-urlencode 'custom_field_982382388=Your Custom Field2'

Allow any service to start a FormReactor call flow. This will save data into the call log as a Form Lead as well as trigger a phone call to the designated Sales phone number.

Parameter Description
caller_name name you want to associate with the customer phone number
country_code country code of the customer phone number
phone_number base digits of the customers phone number, excluding the country code
email email address, optional
visitor_sid tracking code for each account exposes a session id through the global variable __ctm.config.sid, you will want to capture that value and pass it here.
callback_number base digits of a tracking number, excluding the country code, to be used as the caller ID
receiving_number this field allows you to modify the agent who is connected to the call e.g. a receiving number within your account. the format expects the country code e.g. +13333334444
custom_field1 custom field should start with the prefix custom_ and be followed by the label name in web interface
custom_field2 additional custom field, optional
message when triggering a text message you can override the default message and make it custom to this form submission
trigger set to yes to force sending the message or set to no to avoid sending the message, optional

Custom fields should be defined already within the FormReactor UI, otherwise posting to the endpoint will fail.

Custom Field Parameter Naming

  1. Copy the field name root from the form reactor setting page here found on the edit screen for your form reactor
  2. Prefix the field name with custom_ e.g. for a field name such as field_123481828, in your curl request use the following: --data-urlencode 'custom_field_123481828=field value'

visitor_sid can be retrieved by using our JavaScript API. The visitor_sid in the form post should be retrieved from __ctm.config.sid

Managed Mode FormReactor

FormReactor may be used through other form systems using our API (managed mode). When operating in managed mode, the specific form fields are managed by your third party system. The data sent to CTM through this endpoint automatically creates a new FormReactor for each set of unique form fields. We limit the total number of unique API based FormReactors to 10 per sub-account.

curl -u'{access_key}:{secret_key}' \
      -XPOST https://api.calltrackingmetrics.com/api/v1/formreactor/{your_unique_form_id} \
      --data-urlencode 'type=API' \
      --data-urlencode 'caller_name=Name Field' \
      --data-urlencode 'country_code=1' \
      --data-urlencode 'phone_number=(555) 555-5555' \
      --data-urlencode 'email=customer@example.com' \
      --data-urlencode 'visitor_sid=visitorid' \
      --data-urlencode 'callback_number=555555555' \
      --data-urlencode 'custom_field_128838228=Your Custom Field1' \
      --data-urlencode 'custom_field_982382388=Your Custom Field2'

The two key fields to identify your managed form over a standard CTM managed form is the {your_unique_form_id} is generated or provided on your side and the additional form field: “type=API”

POST Block Caller

curl -X POST \
     "https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/calls/{call_id}/block_call" \
     -u "{access_key}:{secret_key}" \
     -d "exclude=true"

Sample successful response JSON

{"status": "blocked"}

POST https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/calls/{call_id}/block_call

You can block a caller by number or CNAM (Caller ID Name).

Parameters Required Description
account_id * ID of the account
call_id * ID of the call with the number or CNAM you want to block
agency If true, the caller will be blocked across the agency
cnam If true, calls with the specified CNAM will be blocked
exclude If true, also exclude calls from this number from the call log and reports

POST Unblock Caller

curl -X POST \
     "https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/calls/{call_id}/unblock_call" \
     -u "{access_key}:{secret_key}" \

Sample successful response JSON

{"status": "unblocked"}

POST https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/calls/{call_id}/unblock_call

You can unblock a caller by using a Call ID. If a blocked number is found with either the caller number or CNAM associated with the call, the call will be unblocked.

Parameter Required Description
account_id * ID of the account
call_id * ID of the call with the number or CNAM you want to unblock

Webhooks

WebHook API allows you to programatically register endpoints to receive HTTP requests with Call Data. You can create new WebHooks by sending a POST request and delete WebHooks by sending a DELETE request. Each request will be logged on failure response code under /api_logs within the specific account.

You can also configure webhooks within the client account under the “Account Settings” -> “Advanced Settings” -> “Webhooks” menu. You can configure a callback URL that we will send an HTTP POST request to after each call is completed. Additionally, any time a call object is modified within the call log, we will send an HTTP POST request to the given URL as well. This allows you to avoid polling our API endpoints for updates to inbound calls.

Request body sent with the Webhook Standard Request

sample python request verification code

from hashlib import sha1;
import hmac;
import base64;

timestamp = '1350310273' # X-CTM-Time header
signature = 'Ll5rmgW9ErCX9JKNToe7vFL3f44=' # X-CTM-Signature header
api_secret_key = 'dddddddddddddfe5cdbee7336c2f8a9ad885' # your secret key can be found in the account settings
msg = '{...}' # request body
mac = hmac.new(api_secret_key, timestamp, sha1)
mac.update(msg)
print base64.b64encode(mac.digest())

The Request body we send to your service is an application/JSON encoded Call object (see Call Detail).

In PHP you may want to use http_get_request_body to get the contents of the request we send to your webhook.

In Ruby on Rails you may want to use: call = JSON.parse(request.body.read)

POST Create a Webhook

POST https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/webhooks

curl -X POST \
     "https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/webhooks" \
     -u "{access_key}:{secret_key}" \
     -d "weburl=http://your-server.com/webhook/path" \
     -d "position=end"

Request params

Request parameters are sent via an HTTP POST URL Encoded request body.

Parameter Required Description
weburl * fully qualified URL (e.g., https://requestb.in/1aaad2u1)
position defines when the webhook will fire; valid choices include: start, answered, hangup, end, end_delayed, update, sale, form, paid, geokey; if unspecified, defaults to end

Sample successful response JSON

{
  "status": "true",
  "webhook": {
    "id": {webhook_id},
    "weburl": "http://your-server.com/webhook/path",
    "with_resource_url": null,
    "position": "end",
    "account_id": {account_id}
  }
}

Webhook JSON Response

Response data will be JSON encoded with a status flag (true or false) indicating either a successful update or failure to update.

DELETE a Webhook

DELETE https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/webhooks/{webhook_id}

curl -X DELETE \
     "https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/webhooks/{webhook_id}" \
     -u "{access_key}:{secret_key}"

Request params

Request parameters are sent via an HTTP POST URL Encoded request body.

Sample successful response JSON

{ "status": "deleted"}

Webhook JSON Response

Response data will be JSON encoded with a status flag (true or false) indicating either a successful update or failure to update.

Google Analytics

Trigger Custom Events

This feature allows you to trigger events for a call to Google Analytics.

POST https://api.calltrackingmetrics.com/api/v1/ga/{call_id}

curl -X POST "https://api.calltrackingmetrics.com/api/v1/ga/{call_id}"

Request params

Request parameters are sent via an HTTP POST URL Encoded request body.

Parameter Description
ga_category Google Analytics Category
ga_action Google Analytics Action
ga_label Google Analytics Label
ga_value Google Analytics Value (numeric)
uacode Google Analytics Account Code (numeric)

Sample successful response JSON

{"status": "queued"}

GA JSON Response

Response data will be JSON encoded with a status flag (true or false) indicating either a successful update or failure to update.

Numbers

The numbers API allows you to search, purchase, and manage settings on tracking numbers.

List Numbers

GET /accounts/{account_id}/numbers.json

curl -X GET https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/numbers.json

Sample successful response JSON

{
  "page": 1,
  "total_entries": 1,
  "total_pages": 1,
  "numbers": [
    {
      "id": "TPNC3C4B32C34A8EC2E5E4EFD301979CD2EFB6E4F483E702C7FC91E0D0496768A56",
      "filter_id": 54321,
      "name": "test number",
      "active": true,
      "status": "active",
      "account_id": "12345",
      "source": {
        "id": "98765",
        "name": "Google Adwords",
        "url": "https://api.calltrackingmetrics.com/api/v1/accounts/12345/sources/98765"
      },
      "number": "+18085551212",
      "call_setting": {
        "id": "NCF5B75DB2863DBE0AF88D27EB2F5783FAEA94ED6FAB1EDB7AF11E25FEA2FCEE80F",
        "url": "https://api.calltrackingmetrics.com/api/v1/accounts/12345/call_settings/NCF5B75DB2863DBE0AF88D27EB2F5783FAEA94ED6FAB1EDB7AF11E25FEA2FCEE80F",
        "name": "Account Level"
      },
      "country_code": "1",
      "next_billing_date": "2015-03-11",
      "purchased_time": "2015-02-11T22:27:14Z",
      "route_to": {
        "type": "user",
        "dial": {
          "url": "https://api.calltrackingmetrics.com/api/v1/accounts/12345/users.USR043E4672225B9BC5932225389967BF8A",
          "id": "USR043E4672225B9BC5932225389967BF8A",
          "name": "agent@example.com"
        }
      },
      "split": [
        "1",
        "808",
        "555",
        "1212"
      ],
      "stats": {
        "since": 1463154069.793778,
        "renewal_costs": "0.0",
        "calls": 577,
        "minutes": 592,
        "minute_costs": "1698.1"
      },
      "formatted": "(808) 555-1212",
      "routing": "simultaneous",
      "url": "https://api.calltrackingmetrics.com/api/v1/accounts/12345/numbers/TPNC3C4B32C34A8EC2E5E4EFD301979CD2EFB6E4F483E702C7FC91E0D0496768A56.json"
    }
  ]
}

Request params

Request parameters are sent via an HTTP GET query string and should be URL Encoded.

Parameter Required Description
account_id * account id
name search for labels
number search for numbers
page page offset to query
per_page range 5 to 100, default 10

Numbers JSON Response

Response data will be JSON encoded.

Search Numbers

GET /accounts/{account_id}/numbers/search.json

curl -X GET https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/numbers/search.json&country_code=US&area_code=808

Sample successful response JSON

{
  "numbers": null,
  "country": "US",
  "searchby": "area",
  "error": [],
  "format_style": "v1",
  "include_distance": false,
  "contains": null,
  "areacode": "808",
  "status": "success",
  "results": [
    {
      "source": 1,
      "friendly_name": "(808) 518-3585",
      "latitude": "0.000000",
      "longitude": "0.000000",
      "lata": "0",
      "region": "HI",
      "postal_code": "",
      "iso_country": "US",
      "capabilities": {
        "voice": true,
        "SMS": true,
        "MMS": true
      },
      "number": "+18085183585",
      "phone_number": "+18085183585",
      "number_type": "local",
      "addr_required": "none",
      "ratecenter": null
    },
    ...
  ]
}
Parameter Required Description
area_code * area code to search and match on
country_code * country to purchase this number for (e.g., US, CA, GB, AU, etc.)

Numbers JSON Response

Response data will be JSON encoded.

Buy Number

POST /accounts/{account_id}/numbers.json

curl -XPOST  https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/numbers.json
  -u access_key:secret_key
  --data-urlencode 'phone_number=+1dddddddddd'

Sample successful response JSON

{
  "status":"success",
  "number":{"id":ddddd,
    "number":"+1dddddddddd",
    "account_id":ddddd,
    "created_at":"2012-08-20T16:16:43Z"
  }
}

Request params

Request parameters are sent via an HTTP POST and should be URL Encoded.

Parameter Required Description
account_id * account id
phone_number * number to purchase including +
test if present, number purchase will be a test purchase

Testing Number Purchase

You can also use test mode to test your purchase flow. Include the test=1 parameter in your request, either in the test query string or within the body of your request. This will respond as though the number was purchased but neither purchase the phone number nor charge your account.

Line Code
1 area_code=443
2 country=US
3 # grab the first number in the list and buy it
4 phone_number=`curl -XGET -u$key:$sec “https://$host/api/v1/accounts/$account/numbers/search.json?area_code=$area_code&country_code=$country”
5
6 echo “buy $phone_number”
7
8 # send the request to purchase
9 curl -XPOST -u$key:$sec https://$host/api/v1/accounts/$account/numbers.json?test=1 –data-urlencode “phone_number=$phone_number”
10 n.tool

Example to configure your number with a tracking source and default receiving number

curl -XPOST -u$key:$sec https://$host/api/v1/accounts/$account/numbers/TPNC..../update_number.json \
  -d name='name_of_your_number' \
  -d dial_route='number' \
  -d multi_route_preference='simultaneous' \
  -d numbers_id[]=RPN24D8... \
  -d default_physical_phone_number_id=RPN24D8... \
  -d tracking_source_id=12345...

Configure your tracking number to ring to two numbers simultaneously

curl -XPOST -u$key:$sec https://$host/api/v1/accounts/$account/numbers/TPNC..../update_number.json \
  -d name='test' \
  -d dial_route='number' \
  -d multi_route_preference='simultaneous' \
  -d numbers_id[]=RPN24D8... \
  -d numbers_id[]=RPN34D8...

Configure your tracking number to ring to three numbers simultaneously and associate a schedule to one of the numbers.

curl -XPOST -u$key:$sec https://$host/api/v1/accounts/$account/numbers/TPNC..../update_number.json \
  -d name='test' \
  -d dial_route='number' \
  -d multi_route_preference='simultaneous' \
  -d default_physical_phone_number=RPN11D11C1F11... \
  -d numbers_id[]=RPN11D11C1F11... \
  -d numbers_id[]=RPN22D22C2F22... \
  -d numbers_id[]=RPN33D33C3F33... \
  -d schedules[]= \
  -d schedules[]=357 \
  -d schedules[]= \
  -d tracking_source_id=37363

Configuring Tracking Number

POST https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/numbers/{number_id}/update_number.json

IMPORTANT Before your tracking number will be activated, you must provide both tracking number and a default receiving number. This can be done by posting default_physical_phone_number_id=RPN34D8AC… or a new number default_physical_phone_number=5555555555 & default_physical_phone_number_country=US and the tracking source as tracking_source_id=….

Call Settings

GET https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/call_settings.json

Call settings can be associated to one or more tracking number and describe aspects of how the number will handle an inbound or outbound call. This controls the whisper message people hear when dialing into a tracking number or the whisper message played when answering on a receiving number.

Create Call Settings

POST https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/call_settings.json

curl -XPOST https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/call_settings.json \
  --data-urlencode "name=Your settings name" \
  --data-urlencode "play_message=play:https://example.com/your.mp3" \
  --data-urlencode "recordings_on=1" \
  --data-urlencode "outbound_recording_on=1" \
  --data-urlencode "premium_callerid_enabled=1" \
  --data-urlencode "callerid_enabled=1"

New call settings can be created by sending a POST request. The play_message string uses the format play:https://example.com/your.wav or say:alice:en-US:your text to speech to play back here.

Assign multiple tracking numbers to a call settings object

curl -XPUT https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/call_settings.json \
  --data-urlencode "virtual_phone_number_ids[]=TPN111111..." \
  --data-urlencode "virtual_phone_number_ids[]=TPN122222..." \
  --data-urlencode "virtual_phone_number_ids[]=TPN133333..."

Update an individual tracking number to point to a single call settings object.

curl -XPUT https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/numbers/{number_id}/update_number.json
  --data-urlencode "number_config_id=NCF111111"

Updating is similar but should include the settings ID string and use the PUT method.

To associate a tracking number to a call settings object, you can either set multiple tracking numbers to the Call Settings API via an update or individually using the configuration endpoint.

Add Receiving Number

POST https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/numbers/{number_id}/receiving_numbers.json

curl -d 'number=+1dddddddddd' https://api.calltrackingmetrics.com/api/v1/accounts/46488/numbers/{number_id}/receiving_numbers.json

Request Params

Parameter Required Description
number * receiving number where you would like phone calls to be forwarded once received by the tracking number

Sample successful response JSON

{
 "status":"success",
 "receiving_number":{
    "id":ddddd,
    "tracking_number_id":ddddd,
    "receiving_number_id":ddddd,
    "account_id":ddddd,
    "schedules":{"sun":[],"mon":[],"tue":[],"wed":[],"thu":[],"fri":[],"sat":[]}
  }
}

Numbers JSON Response

Response data will be JSON encoded.

Add Tracking Source

POST https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/numbers/{number_id}/tracking_sources

curl -X POST https://api.calltrackingmetrics.com/api/v1/\
accounts/{account_id}/numbers/{number_id}/tracking_sources.json
  --data-urlencode "name=tracking source name"
  --data-urlencode "position=101"
  --data-urlencode "landing_url=param=testing"
  --data-urlencode "online=true"

Sample successful response JSON

{
  "status": "success",
  "source": {
    "id": 12345,
    "name": "tracking source name",
    "account_id": 54321,
    "referring_url": "",
    "not_referrer_url": null,
    "landing_url": "param=testing",
    "not_landing_url": null,
    "position": 101,
    "online": true,
    "crm_tag": "",
    "url": "https://api.ctmdev.us/api/v1/accounts/18600/sources/12345.json"
  }
}

Request params

Request parameters are sent via an HTTP POST and should be URL Encoded.

Parameter Required Description
account_id * the account id
number_id * the tracking number ID (TPN)
name * name of the tracking source
referring_url pattern to match on the referring website for matching the current visitor. e.g., document.referrer; should be a valid regular expression without the leading / and trailing /
landing_url pattern to match on the current website location for the current visitor. e.g., window.location; should be a valid regular expression without the leading / and trailing /
position numeric value to indicate how this source should be evaluated with respect to all other sources, with lower values having higher precedence
crm_tag map this tracking source to campaign in CRM

Batch Geoprocessing

curl -XPUT-uAPI:SEC --upload-file commands.txt https://api.calltrackingmetrics.com/api/v1/accounts/46488/geo_routes/{geo_router_id}/batch

You can use the Batch Geoprocessing interface to easily setup a large geo router using a simple command based interface to add, update, and remove receiving numbers from your geo router.

PUT https://api.calltrackingmetrics.com/api/v1/accounts/{aid}/geo_routes/batch?post_back_url=http://yourservice.com/&post_back_email=your@email.com

commands.txt

create +15555553232 todd cell phone
update +15555553232 updated phone label
addzip +15555553232 21146 21144
delzip +15555553232 21144
clearzips +15555553232
remove +15555553232
mark   +15555553232
purge log

The following options can be included in your request URL to adjust how we process each command

  1. global, when passed as 1 - we will treat receiving numbers as global to your account instead of scoping to the geo router.
  2. create, when passed as 1 - will always create a new receiving number, otherwise create will actually just operate like update. The default 0 is usually what you want.

Sample successful response JSON

{"status":"queued"}

Numbers JSON Response

Response data will be JSON encoded.

Adding a post_back_url or a post_back_email will trigger a web service POST request to the post_back_url include the resulting status of the transaction of batched commands.

Command Description
create find or create the number associating it to the geo router
update update the provided numbers label
addzip add one or more zip codes to the provided number
delzip delete one or more zip codes from the provided number
clearzips remove all associated zipcode data from the provided number
remove remove the provided number from the given geo router
mark mark this number so it is not purged
purge purge will remove, delete or log to indicate which numbers were not marked that exist within the geo router

Mark and Purge

Mark and Purge work together allowing you to indicate the numbers you want to retain by calling mark (number) and at the end of your file calling purge will remove any non-marked numbers from the geo router

Command Description
mark number marks this number to keep it any number not marked will be eligible for purge
purge remove removes the number but does not delete it from your geo router
purge delete deletes the number and removes it from your geo router
purge log logs the number we would delete log will include purge_list in the post_back_url request json data
curl -X DELETE https://api.calltrackingmetrics.com/api/v1/accounts/46488/numbers/{nid}.json

Release Number

DELETE https://api.calltrackingmetrics.com/api/v1/accounts/{aid}/numbers/{nid}.json

Sample successful response JSON

{"number":"+1dddddddddd","released":true}

Numbers JSON Response

Response data will be JSON encoded.

List Receiving Numbers

GET https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/receiving_numbers.json

curl -ukey:sec https://api.calltrackingmetrics.com/api/v1/accounts/46488/receiving_numbers.json

Request Params

Request parameters are sent via an HTTP GET query string and should be URL Encoded.

You can filter by number (e.g. ?number=8005771872). Number filtering should not include the country code.

Sample successful response JSON

{
  "total_entries": 9,
  "total_pages": 1,
  "next_page": "https://api.calltrackingmetrics.com/api/v1/accounts/46488/receiving_numbers.json",
  "previous_page": "https://api.calltrackingmetrics.com/api/v1/accounts/46488/receiving_numbers.json",
  "receiving_numbers": [
    {
      "url": "/api/v1/accounts/46488/receiving_numbers/RPN93F974B7xddddd",
      "id": "RPN93F974B77xddddd",
      "name": "Main Line"
      "number": "+18005771872",
      "display_number": "(800) 577-1872",
      "account_id": {account_id},
      "filter_id": 2199,
      "country_code": "1",
      "split": [
        "1",
        "800",
        "577",
        "1872"
      ],
      "formatted": "800-577-1872"
    },
    {
      "url": "/api.calltrackingmetrics.com/api/v1/accounts/46488/receiving_numbers/RPN93F974B77xddddd",
      "id": "RPN93F974B77xddddd",
      "name": "Sales Line"
      ...
    },
    ...
  ]
}

Receiving Number JSON Response

Response data will be JSON encoded.

Create Receiving Number

POST https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/receiving_numbers.json

curl -XPOST -u$KEY:$SEC https://api.calltrackingmetrics.com/api/v1/accounts/46488/receiving_numbers.json \
--data-urlencode "number=+15555553333" \
--data-urlencode "name=Your Number"

Request params

Request parameters are sent via an HTTP POST URL encoded string.

Sample successful response JSON

{
  "status": "success",
  "receiving_number": {
    "id": "RPN34D8AC3F61E8848FEA6",
    "filter_id": 40109,
    "name": "Your Number",
    "number": "+15555553333",
    "display_number": "(555) 555-3333",
    "account_id": 46488,
    "country_code": "1",
    "split": [
      "1",
      "555",
      "555",
      "3333"
    ],
    "formatted": "555-555-3333",
    "url": "/api/v1/accounts/46488/receiving_numbers/RPN34D8AC3F61E8848FE"
  }
}

Receiving Number JSON Response

Response data will be JSON encoded.

Delete Receiving Number

DELETE https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/receiving_numbers/{receiving number}.json

curl -XDELETE -u$KEY:$SEC https://api.calltrackingmetrics.com/api/v1/accounts/46488/receiving_numbers/RPN34D8AC3F61E8848FE.json

Request params

Request parameters are sent via an HTTP DELETE URL encoded string.

Sample successful response JSON

{
  "status": "success"
}

Receiving Number JSON Response

Response data will be JSON encoded.

List Voice Menus

GET https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/voice_menus.json

curl -ukey:sec https://api.calltrackingmetrics.com/api/v1/accounts/46488/voice_menus.json

Request params

Request parameters are sent via an HTTP GET query string and should be URL Encoded.

Sample successful response JSON

{
  "total_entries": 9,
  "total_pages": 1,
  "next_page": "https://api.calltrackingmetrics.com/api/v1/accounts/46488/voice_menus.json",
  "previous_page": "https://api.calltrackingmetrics.com/api/v1/accounts/46488/voice_menus.json",
  "menus": [
    {
      "url": "https://api.calltrackingmetrics.com/api/v1/accounts/46488/voice_menus/VOM93F974B7xddddd",
      "id": "VOM93F974B77xddddd",
      "name": "After Hours"
    },
    {
      "url": "https://api.calltrackingmetrics.com/api/v1/accounts/46488/voice_menus/VOM93F974B77xddddd",
      "id": "VOM93F974B77xddddd",
      "name": "Line Test"
    },
    ...
  ]
}

Voice Menu JSON Response

Response data will be JSON encoded.

Create Voice Menus

POST https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/voice_menus.json

curl -XPOST -u$KEY:$SEC https://api.calltrackingmetrics.com/api/v1/accounts/46488/voice_menus.json
  -d '{
        "name":"test",
        "voice_prompt_text":"test",
        "items":[
           {
              "keypress":1,
              "action":"dial",
              "receiving_number":"RPN34D8AC3F61E8848Fxdddddd"
           },
           {
              "keypress":2,
              "action":"dial",
              "receiving_number":"RPN34D8AC3F61E8848Fxdddddd"
           }
        ],
        "tracking_numbers":[
           "TPNC3C4B23C348AEC2EE54Exdddddd"
        ]
     }'

Request params

Request parameters are sent via an HTTP POST JSON encoded string.

Sample successful response JSON

{
  "url": "https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/voice_menus/VOM93F9xdddd",
  "id": "VOM93F974B7707B2xdddd",
  "name": "test",
  "menu_items": [
    {
      "id": "VMI93F9xdddd",
      "url": "https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/voice_menus/VOM93F97xddddd/voice_menu_items/VMI93Fxddddd"
    },
    {
      "id": "VMI93F97xdddd",
      "url": "https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/voice_menus/VOM93F974xddddd/voice_menu_items/VMI93F9xddddd"
    }
  ],
  "voice_prompt_type": "text",
  "voice_prompt_text": "test",
  "voice_prompt_audio_url": null,
  "prompt_retries": 5,
  "input_maxkeys": null,
  "input_timeout": 7
}

Voice Menu JSON Response

Response data will be JSON encoded.

Delete Voice Menus

DELETE https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/voice_menus/{voicemenuid}.json

curl -XDELETE -u$KEY:$SEC https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/voice_menus/VOM93F974xddddd.json

Request params

Request parameters are sent via an HTTP POST JSON encoded string.

Sample Successful Response JSON

{
  "status": "destroyed",
  "id": "VOM93F974xddddd"
}

Voice Menu JSON Response

Response data will be JSON encoded.

Add Local Number Addresses

A local address must be provided before purchasing local numbers for certain countries. Within the web application you will see a prompt before purchasing is allowed, or you can use the API to manage your addresses.

Adding Number Address

Adding a local address

# add the address
curl -XPOST  -u$KEY:$SEC https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/number_address \
--data-urlencode 'country=Germany' \
--data-urlencode 'street=Allee Der Kosmonauten 37' \
--data-urlencode 'city=Berlin' \
--data-urlencode 'region=Brandenburg' \
--data-urlencode 'postal_code=12681'

Request params

Request parameters are sent via an HTTP POST JSON encoded string.

Sample Successful Response JSON json { "sid": "ADc9cd30ec09a472e2d3b2da285335bac4", "name": "queue test1", "customer_name": "queue test1", "street": "Allee Der Kosmonauten 37", "city": "Berlin", "region": "Brandenburg", "postal_code": "12681", "iso_country": "DE" }

JSON Response

Response data will be JSON encoded.

List Local Number Addresses

curl -XGET  -u$KEY:$SEC https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/number_address

Sample Successful Response JSON json [ { "sid": "ADc9cd30ec09a472e2d3b2da285335bac4", "name": "queue test1", "customer_name": "queue test1", "street": "Allee Der Kosmonauten 37", "city": "Berlin", "region": "Brandenburg", "postal_code": "12681", "iso_country": "DE" } ]

JSON Response

Response data will be JSON encoded.

SMS

SMS (Text Messaging) API

The SMS API allows you to search, send, and manage text messaging triggers for all capable numbers.

curl https://api.calltrackingmetrics.com/api/v1/accounts/45522/sms.json?auth_token=token-string

List Text Messages

GET https://api.calltrackingmetrics.com/api/v1/accounts/:aid/sms.json

You can include a start_time and end_time filters.

For example to get a paginated list of messages for January 2016 start_time=2016-01-01&end_time=2016-02-01

Sample successful response JSON

{
  messages: [
      {
      "account_id": {account_id},
      "billed_amount": 2,
      "billed_at": "2013-07-16T12:42:57Z",
      "body": "thank you for the call today",
      "callerid": null,
      "created_at": "2013-07-16T12:42:56Z",
      "direction": "outbound",
      "from_city": null,
      "from_country": null,
      "from_number": "+1dddddddddd",
      "from_state": null,
      "from_zip": null,
      "id": "",
      "number_id": "TPNC3C4B23C348AEC2EE54EFD301979CD2E6A5F098F136B68834B8D03C511710DDA",
      "parent_id": null,
      "child_type": null,
      "status": "completed",
      "to_city": null,
      "to_country": null,
      "to_number": "+1dddddddddd",
      "to_state": null,
      "to_zip": null,
      "tracking_source_id": null
    },
  ...
  ],
  total_entries: 1963,
  total_pages: 197,
  next_page: "https://api.calltrackingmetrics.com/api/v1/accounts/:account_id/sms.json?page=2",
  previous_page: "https://api.calltrackingmetrics.com/api/v1/accounts/:account_id/sms.json"
}
curl https://api.calltrackingmetrics.com/api/v1/accounts/45522/sms/.json?auth_token=token-string

Display Text message

GET https://api.calltrackingmetrics.com/api/v1/accounts/:aid/sms/:sms_id.json

Sample successful response JSON

{
  "account_id": {account_id},
  "billed_amount": 2,
  "billed_at": "2013-07-16T12:42:57Z",
  "body": "thank you for the call today",
  "callerid": null,
  "created_at": "2013-07-16T12:42:56Z",
  "direction": "outbound",
  "from_city": null,
  "from_country": null,
  "from_number": "+1dddddddddd",
  "from_state": null,
  "from_zip": null,
  "id": "",
  "number_id": "TPNC3C4B23C348AEC2EE54EFD301979CD2E6A5F098F136B68834B8D03C511710DDA",
  "parent_id": null,
  "child_type": null,
  "status": "completed",
  "to_city": null,
  "to_country": null,
  "to_number": "+1dddddddddd",
  "to_state": null,
  "to_zip": null,
  "tracking_source_id": null
}

Sending SMS Text Messages

POST https://api.calltrackingmetrics.com/api/v1/accounts/:account_id/sms.json

curl -XPOST \
     --data-urlencode 'from=TPNC3C4B23C348AEC2EE54EFD301979CD2E6A5F098F136B68834B8D03C511710DDA' \
     --data-urlencode 'msg=My SMS Text Message' \
     --data-urlencode 'to=+1dddddddddd' \
     'https://api.calltrackingmetrics.com/api/v1/accounts/45522/sms.json?auth_token=token-string'

Request params

Request parameters are sent via an HTTP GET query string and should be URL Encoded.

Parameter Description
from tracking_number_id, the ID of the tracking number e.g. TPN…
to destination phone number, the digits of the phone number e.g. +1dddddddddd
msg the text message to send, limited to 160 characters
status a status call back is a web request we can send you after the message has been delivered. e.g. http://example.com/your-web-service

Sample successful response JSON

{
  "status": "processing",
  "id": ""
}

Create a trigger group

curl -XPOST \
     --data-urlencode 'trigger_group={"name":"My Response Groups","sms_tracking_numbers":["TPNC3C4B23C348AEC2EE54EFD301979CD2E6A5F098F136B68834B8D03C511710DDA"],"triggers":[{"cond_position":0,"cond_operator":"eq","cond_value":10,"trigger_actions":[{"type":"TriggerEmail", "value":"your@example.com"}, {"type":"TriggerSmsReply", "value":"we got your message"}]}]}' \
    'https://api.calltrackingmetrics.com/api/v1/accounts/45522/sms/create_trigger.json?auth_token=token-string'

Update a trigger group

curl -XPUT \
     --data-urlencode 'id=dd' \
     --data-urlencode 'trigger_group={"name":"My Response Groups","sms_tracking_numbers":["TPNC3C4B23C348AEC2EE54EFD301979CD2E6A5F098F136B68834B8D03C511710DDA"],"triggers":[{"cond_position":0,"cond_operator":"eq","cond_value":10,"trigger_actions":[{"type":"TriggerEmail", "value":"your@example.com"}, {"type":"TriggerSmsReply", "value":"we got your message"}]}]}' \
    'https://api.calltrackingmetrics.com/api/v1/accounts/45522/sms/update_trigger.json?auth_token=token-string'

Delete a trigger group

curl -XDELETE \
     --data-urlencode 'id=dd' \
    'https://api.calltrackingmetrics.com/api/v1/accounts/45522/sms/delete_trigger.json?auth_token=token-string'

Sample Successful Response JSON

{ "status": "success", "id": ddd }

SMS Triggers

Triggers allow you to define how to react when receiving a text message. Examples include auto responding with a message, forwarding the message to another phone, sending an email, etc.

POST https://api.calltrackingmetrics.com/api/v1/accounts/:account_id/sms/create_trigger.json

PUT https://api.calltrackingmetrics.com/api/v1/accounts/:account_id/sms/update_trigger.json

DELETE https://api.calltrackingmetrics.com/api/v1/accounts/:account_id/sms/delete_trigger.json

Accounts

REST Accounts API

The accounts API allows you to create and manage accounts.

List Accounts

GET https://api.calltrackingmetrics.com/api/v1/accounts.json

curl https://api.calltrackingmetrics.com/api/v1/accounts.json?auth_token=token-string

Request params

Request parameters are sent via an HTTP GET query string and should be URL Encoded.

Parameter Description
page the page offset to query

Sample successful response JSON

{
  "page":1,
  "per_page":10,
  "total_entries":1,
  "total_pages":1,
  "next_page":"http://www.example.com/api/v1/accounts.json",
  "previous_page":"http://www.example.com/api/v1/accounts.json",
  "accounts":[
    {
      "id":329,
      "name":"Test 1",
      "user_role":"agency_admin",
      "stats":{"calls":0,"tracking_numbers":0},
      "url":"http://www.example.com/api/v1/accounts/329",
      "balance":{"cents":2500,"currency":"USD","precision":2}
    }
  ]
}

Accounts JSON Response

Response data will be JSON encoded.

Add Account

POST https://api.calltrackingmetrics.com/api/v1/accounts.json

curl -d 'account[name]=test' -d 'billing_type=existing' https://api.calltrackingmetrics.com/api/v1/accounts.json?auth_token=token-string

Request params

Request parameters are sent via an HTTP POST and should be URL Encoded.

Parameter Description
account[name] (required) the name for the new account
account[website_url] (optional) set the website URL for an account
billing_type (required) the type of billing for this account either, existing or new, when new is selected additional payment profile options are required.
account[payment_profiles_attributes][0][address] new billing address
account[payment_profiles_attributes][0][city] new billing city
account[payment_profiles_attributes][0][zip] new billing postal code
account[payment_profiles_attributes][0][country] new billing country, e.g. “United States”, “Canada”, “Mexico”, “United Kingdom”, etc…
account[payment_profiles_attributes][0][first_name] first name on credit card
account[payment_profiles_attributes][0][last_name] last name on credit card
account[payment_profiles_attributes][0][card_type] type of credit card one of visa, master, american_express, or discover.
account[payment_profiles_attributes][0][card_number] credit card number
account[payment_profiles_attributes][0][verification_value] credit card verification number
account[payment_profiles_attributes][0][month] credit card expiration month
account[payment_profiles_attributes][0][year] credit card expiration year

Sample Successful Response JSON

{
  "status":"success",
  "id":329
}

Accounts JSON Response

Response data will be JSON encoded.

GET https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/ga/link.json

curl -ukey:sec https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/ga/link.json

Sample response

{
  "id": 7902,
  "default": "UA-2222222-4",
  "gavar": "ga",
  "email": "example@gmail.com",
  "options": {
    "record": true,
    "offline": true,
    "sales": true,
    "dynamic": false,
    "both": false
  },
  "uacodes": [
    {
      "account": "....",
      "view": "...",
      "webproperty": "UA-11111111-1"
    },
...
  ]
}

POST https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/ga/link.json

Agencies can also reuse an existing link by passing the link_id parameter set to the link id from another account.

options are all passed as parameters prefixed with the opt_ key.

curl -XPOST -ukey:sec https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/ga/link.json
-d link_id={link_id}
-d opt_dynamic=1
-d opt_offline=1
-d opt_record=1

Users

REST Users API

The users API allows you to create and manage users.

List Users

GET https://api.calltrackingmetrics.com/api/v1/accounts/:aid/users.json

curl https://api.calltrackingmetrics.com/api/v1/accounts/:aid/users.json?auth_token=token-string

Request params

Request parameters are sent via an HTTP GET query string and should be URL Encoded.

Parameter Description
page the page offset to query

Sample Successful Response JSON

{
 "page":1,
 "per_page":10,
 "total_entries":2,
 "total_pages":1,
 "next_page":"http://www.example.com/api/v1/accounts/329/users.json",
 "previous_page":"http://www.example.com/api/v1/accounts/329/users.json",
 "users":[
   {"id":1,
    "first_name":"Test",
    "last_name":"Testerson",
    "email":"test1@test.com",
    "url":"https://api.calltrackingmetrics.com/api/v1/accounts/:aid/users/:uid.json"
   },
   {"id":2,
    "first_name":"foo",
    "last_name":"bar",
    "email":"foo@bar.com",
    "url":"https://api.calltrackingmetrics.com/api/v1/accounts/:aid/users/:uid.json"
   }
  ]
}

Users JSON Response

Response data will be JSON encoded.

Add User

POST https://api.calltrackingmetrics.com/api/v1/accounts/:aid/users.json

curl -d 'user[email]=user@example.com' -d 'user[first_name]=FirstName' -d 'user[last_name]=LastName' -d 'user[password]=secretpassword' https://api.calltrackingmetrics.com/api/v1/accounts/:aid/users.json?auth_token=token-string

Request params

Request parameters are sent via an HTTP POST and should be URL Encoded.

Parameter Description
user[email] (required) email address for user
user[first_name] (required) first name for user
user[last_name] (required) last name for user
user[password] (required) password for user
user[role] how the user can access the account, one of: ‘admin’(default), 'report_manager’, 'report_viewer’

Sample Successful Response JSON

{
    "id": uid,
    "first_name": "foo",
    "last_name": "bar",
    "email": "foo@bar.com",
    "url": "https://api.calltrackingmetrics.com/api/v1/accounts/:aid/users/:uid.json"
}

Users JSON Response

Response data will be JSON encoded.

Add Role

POST https://api.calltrackingmetrics.com/api/v1/accounts/:aid/users/:uid/add_role.json

curl -d 'role=admin' -d 'account_id=:aid' https://api.calltrackingmetrics.com/api/v1/accounts/:aid/users/:uid/add_role.json?auth_token=token-string

Request params

Request parameters are sent via an HTTP POST and should be URL Encoded.

Parameter Description
role (required) how the user can access the account, 'admin’, 'report_manager’, 'report_viewer’
account_id (required) the account_id to grant this user access.

Sample Successful Response JSON

{
    "id": uid,
    "first_name": "foo",
    "last_name": "bar",
    "email": "foo@bar.com",
    "url": "https://api.calltrackingmetrics.com/api/v1/accounts/:aid/users/:uid.json"
}

Users JSON Response

Response data will be JSON encoded.

JavaScript Events API

This API allows you to send a tracking event to our analytics service. Doing this allows you to track that a visitor has seen a given number. It also allows you to attach custom variables to website visitors for additional third party tracking tools.

(window.__ctm_loaded || []).push(function() {
  // access __ctm variables because our JS file has loaded
  // e.g. get the users session id __ctm.config.sid
});

Tracking Ready Event

When loading our JavaScript you may need to know when it’s ready to interact with. This can be done by attaching a __ctm_loaded method.

Event Tracking

These functions should be invoked within the CTMSourceEvent callback. javascript window.ptTrackVisitor("dddddddddd", "eeeeeeeeee"); window.ptTrackVisitor

This function should only be called once per page, and can be useful to call when swapping images on a page to ensure we track the visitor.

window.ptTrackEvent("dddddddddd", "eeeeeeeeee", "visible");

window.ptTrackEvent

This function can be called multiple times per page, and is useful for indicating whether the number was visible to the visitor or whether the number clicked on by the visitor.

NOTE: in both examples, “ddddddddd” is the receiving number and “eeeeeeeeee” is the tracking number. Additionally, both numbers do NOT include a country code.

__jctm(window).bind("ctm.form.success", function(evt) { console.log(evt.formData); });

FormReactor Events

After a form is submitted within FormReactor there are a number of events you can subscribe to.

Parameter Description
ctm.form.success trigger after a form is successfully submited to a CTM server.
ctm.form.limited trigger when a customer was rate limited e.g. has already or recently submited the form successfully.
ctm.form.error trigger when a customer has an error with their submission see evt.fields for a list of fields that are not valid.
ctm.form.failure trigger when a CTM server fails to handle the submission successfully.

JavaScript Images API

PhoneNumber Embedded Images JavaScript

To replace an image with a phone number, all you need is to hook into the CTMSourceEvent function.

// javascript within account settings - tracking script
window.CTMSourceEvent = function(event) {
  if (event.state != 'before') { return; }
  var numberMap = {
    "4103949424": "/images/samples/ctm-logo-4103949424.png", // direct visits
    "4106954857": "/images/samples/ctm-logo-4106954857.png"  // this demo
  }
  var swapNumber = numberMap[event.new_number]
  if (swapNumber) {
    document.getElementById("yournumber").src = swapNumber;
  }
}

Replacing Images

First locate the image you want to replace, either by adding a class or ID attribute. If you have a library such as jQuery this is fairly easy but will also work with native DOM functions.

You do not need to update your embedded code - you can add all of this code within account settings.

The example assumes you have an image element with the ID attribute “yournumber”. It has a mapping table, that associates each tracking number to a specific CallTrackingMetrics tracking number.

Cufon and sIFR Number Replacement

In the past, we had a specific set of code we recommended for handling these types of fonts. However, now our code will handle this natively. Contact our support team if you find otherwise.

JavaScript Tracking API

Client JavaScript API

This document describes the interface to our client side JavaScript API. With this API you can dynamically update images based on the chosen tracking number for the current visitor. You can adjust phone number formats, set custom variables and more.

Tracking Code

First be sure to have our tracking code installed on each page of your website. Even if the phone number is not found on the page, it’s important because we use cookies in order to preserve the visitors first touch source. This ensures we always show each website visitor a consistent phone number.

Install Tracking Code

Call Back API

window.CTMSourceEvent = function(event) {
  if (event.state == 'after') {
    // update DOM after number replacement
  }
}

The primary interface to our client side code is through a global call back function, CTMSourceEvent. This function will be invoked to signal different events or stages of the number replacement and tracking process.

As the tracking code works to locate and update phone numbers automatically, it will call this method before replacing a number and after replacing a number. This will allow you to 'hook’ into the number replacement flow, such that you can manipulate the output format, identify which phone number was selected for tracking, and other customizations.

For example, the following CTMSourceEvent function could be defined within the account settings dashboard under “tracking script” in order to add an additional DOM element under the update phone number.

The event object passed to this method includes the following attributes

Parameter Description
event.state before: The event is fired before the number swap algorithm is run against your web page DOM tree; after: The event is fired after our number swap algorithm is run against your web page DOM tree
event.current_number The current number found in your website’s DOM tree, this number is the receiving number that was present on your website before any tracking code is executed.
event.new_number This is the new number that will replace the “current_number”, this is the tracking number.

Custom Variables

<script>
  var __ctm_cvars = __ctm_cvars || [];
  __ctm_cvars.push({uservar1: 'test'});
</script>

You can assign custom variables to each visitor tracked by initializing a variable __ctm_cvars. Set the variables before loading the embed code. For example,

The value that you push into the Array can be either a String or an Object. When the value is an Object it will be serialized to JSON before being stored with the visitor.

Conversion Tracking

var __ctmi = __ctmi || [];
(window.__ctm_loaded || []).push(function() {
__ctmi.push(['form.conversion', "+15555555555", "address@example.com", 282.28]);
});

PHP example:

<script>
var __ctmi = __ctmi || [];
(window.__ctm_loaded || []).push(function() {
__ctmi.push(["form.conversion", "<?php echo $number ?>","<?php echo $email ?>"]);
});
</script>

Ruby example:

<script>
var __ctmi = __ctmi || [];
(window.__ctm_loaded || []).push(function() {
__ctmi.push(["form.conversion", "<%= number %>","<%= email %>"]);
});
</script>

To track form conversions back to calls, CallTrackingMetrics provides an interface to record information about the form conversion such as the phone number, email and value of the conversion. The global variable __ctmi is used to track conversions. See the example to the right:

The first argument tells __ctmi you want to track a form conversion. The next arguments are some information about the form entry that allows us to better match each form entry to a previous caller. The last argument after the phone number and email arguments is the value of the conversion.

Setting it up:

To setup the conversions tracking code above, you should place it on the thank you or confirmation page of your form.

Here are some examples in PHP and Ruby of how you could retrieve the values to track in the CTM conversion code.

Preventing Number Swapping

<p class="ctm-no-swap">(555) 555-5555</p>

In some cases, you will have the phone number on the page but you will not want us to replace it. To support this case, you can add a class name around the parent DOM Element “ctm-no-swap”. For example: