REST Calls API

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 paramaters are sent via an HTTP GET query string and should be URL Encoded.

  • page the page offset to query
  • filter a search string to look for calls with specific callerid, caller_number, called_number, source name, etc...
  • multi_tags[] you can use this query param to filter results by one or tag
  • multi_agents[] you can use this query param to filter results by agent user id.
  • menu_key_press you can use this query param to filter results by a specific menu key
  • filter_visitor_data you can use this query param to filter results by either calls that include visitor data or calls that lack visitor data. e.g. filter_visitor_data=1 to include visitor data or filter_visitor_data=2 to exclude visitor data
  • start_date a starting date offset to query
  • end_date a ending date offset to query
curl -XGET https://api.calltrackingmetrics.com/api/v1/accounts/{{account_id}}/calls.json

Calls JSON Response

Response data will be JSON encoded.

Sample Successful Response JSON

{
  calls: [
  {
    id: ":call_id",
    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"
}
  

GET Call Detail

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

Request params

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

curl -XGET https://api.calltrackingmetrics.com/api/v1/accounts/{{account_id}}/calls/{{insert call id}}.json

Calls JSON Response

Response data will be JSON 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"
    }
  }
  

POST Sale Record

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

Request params

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

  • score a number between 1 and 5 to indicate the quality of the call.
  • value a numeric value to represent, the total worth of the call in dollars.
  • conversion a boolean flag (1 or 0) to indicate whether the call resulted in a sale.
  • sale_date when a sale occurred as a result of this call.
  • name Sets the reporting tag within the call log can be used as a product name or sales person name.
curl -XPOST https://api.calltrackingmetrics.com/api/v1/accounts/{{account_id}}/calls/{{insert call id}}/sale
          --data-urlencode 'name=Name' \
          --data-urlencode 'score=4' \
          --data-urlencode 'conversion=1' \
          --data-urlencode 'value=850.0'

Sale Record JSON Response

Response data will be JSON encoded.

Sample Successful Response JSON

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

POST Modify Call Data

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

Request params

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

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

Calls JSON Response

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

Sample Successful Response JSON

  {"status": "true"}
  

POST FormReactor Server Side Request

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

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.

 curl -u'account_key:account_secret' \
      -XPOST https://api.calltrackingmetrics.com/api/v1/formreactor/INSERT_ID_OF_FORM_REACTOR \
      --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'
caller_nameA name you want to associate with the customers phone number.
country_codeThe country code of the customers phone number.
phone_numberThe base digits of the customers phone number, this should not include the country code.
emailAn optional email can be captured with the FormReactor call.
visitor_sidThe 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_numberthis is the base digits of a tracking number (no country code) you want to use as the callerid for the FormReactor calls.
receiving_numberthis field allows you to modfiy 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_field1custom field should start with custom_ prefix and be followed by the label name in web interface.
custom_field2you can have multiple custom fields
messagewhen triggering a text messsage you can override the default message and make it custom to this form submission
triggeroptional when present and equal to yes force sending the message otherwise when present and equal to no avoid sending the message

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

Webhook API

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 to under the "Email menu within "account settings". From "account settings" click on "Advanced setting" then go to "webhooks". 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

The Request body we send to your service is a 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)

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

POST Create a WebHook

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

Request params

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

curl -d 'weburl=http://your-server.com/webhook/path' https://api.calltrackingmetrics.com/api/v1/accounts/{{account_id}}/webhooks.json

WebHook JSON Response

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

Sample Successful Response JSON

  {"status": "true", "id": <webhook-id>}
  

DELETE Delete a WebHook

DELETE https://api.calltrackingmetrics.com/api/v1/accounts/{account_id}/webhooks/{webhook-id}.json

Request params

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

curl -XDELETE https://api.calltrackingmetrics.com/api/v1/accounts/{{account_id}}/webhooks/:id.json

WebHook JSON Response

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

Sample Successful Response JSON

  {"status": "deleted"}
  

Trigger Custom Events to Google Analytics

this feature allows you to trigger events for a call to google analytics

POST https://api.calltrackingmetrics.com/api/v1/ga/:call_id.json

Request params

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

curl -XPOST https://api.calltrackingmetrics.com/api/v1/ga/:call_id.json
ga_category 'YourCategory'
ga_action 'YourAction'
ga_label 'YourLabel'
ga_value '[0-9]*'
uacode '[0-9]*'optional

GA JSON Response

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

Sample Successful Response JSON

  {"status": "queued"}