telmetricsV3

Marchex Marketing Edge API Developer Documentation

Welcome to the Marchex Marketing Edge developer hub. You'll find comprehensive guides and documentation to help you start working with our API as quickly as possible.

Get Started    

Lead Tracking

Introduction

The Telmetrics Lead Tracking API allows users to submit a Lead Tracking Tag when phone numbers are displayed to website visitors. When a phone call or text message is received within the user-specified match period, it will be automatically be associated with the Lead Tracking Tag for attribution purposes.

Integrations

Phone calls and text messages matched to a Lead Tracking Tag are can be automatically uploaded to the following integrations:

  • Adobe Analytics
  • Google Analytics
  • Google Ads

For additional information on how to configure one or more these integrations for the Lead Tracking API, please contact customer support.

Posting Lead Tracking Tags to Lead Tracker API

Lead Tracking Tags are sent to Telmetrics via an HTTP post. The following fields must be passed:

  • key - this is value is used to authorize that the Lead Tracking Tag belongs to your organization. To obtain this value, please contact your customer support representative
  • tracking_numbers - an array of tracking numbers to monitor for phone calls or text conversations
  • session_match_period - a value (in seconds) that determines how long we should wait for a phone call or text conversation to start on any of the numbers passed in the array of tracking_numbers
  • tag_data - an open text field that contains information that can be used associate a view of a phone number to a phone call/text conversation

A wide range of additional fields may also be added to your Lead Tracking Tag, please see the field definitions for more information.

Your Lead Tracking Tag may be sent Telmetrics using the following endpoint: POST https://api.telmetrics.com/v3/api/leadtracking/setTag

Below is a sample request:

{
  "key": "0b29471f-5240-457c-ac5c-9800ea46dabc",
  "tag_data": "Custom Value",
  "tracking_numbers": ["8005623816"],
  "session_match_period": 60,
  "referrer": "https://www.google.com/",
  "landing_page": "http://123company.net?gclid=123&utm_campaign=fallpromo",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/67.0.3396.99 Safari/537.36",
  "latitude": 43.6532,
  "longitude": 79.3832,
  "utm_parameters": {
    "utm_source": "google",
    "utm_term": "pizza",
    "utm_campaign": "fallpromo"
  },
  "adobe_analytics": {
    "channel": "channelxyz",
    "visitor_id": "123abc",
    "campaign": "campaignAbc",
    "page_name": "abc"
  },
  "adobe_analytics": {
    "channel": "channelxyz",
    "visitor_id": "123abc",
    "campaign": "campaignAbc",
    "page_name": "abc"
    },
  "google_ads": {
    "gclid": "23423423423432432"
  },
  "google_analytics": {
    "client_id": "123abc",
    "userId": "abcxyz",
    "page": "%2foo",
    "dimension_1": "abc",
    "metrics_1": "xyz",
    "hit_type": "pageView",
    "gclid": "123"
  }
}

Field Definitions:

FieldDescriptionRequired
keyA Telmetrics supplied value that validates the tag. Contact your account manager to obtain this value.Yes
tracking_numbersAn array of tracking numbers that will be associated with the supplied tagging data if a call occurs within the match periodYes
tag_dataAn open text field that can be used to supply data specific to your tracking and attribution needsNo
session_match_periodHow long to wait (in seconds) for a call or text conversation to occur on one of the tracking numbers supplied in the tracking_numbers fieldNo - when not supplied, your Organization default will be applied
referrerReferrer URL responsible for delivering a website visitor to the website where you are measuring attributions. Field must be passed as a valid URLNo
landing_pageLanding Page URL website visitor arrived on. Field must be passed as a valid URLNo
user_agentWebsite Visitor's user agentNo
lattitudeWebsite Visitor's LattitudeNo
longitudeWebsite Visitor's LongitudeNo
UTM Parameter -> utm_sourceWebsite Visitor's UTM_SourceNo
UTM Parameter -> utm_termWebsite Visitor's UTM_Term (keyword)No
UTM Parameter -> utm_campaignWebsite Visitor's UTM_CampaignNo
UTM Parameter -> utm_mediumWebsite Visitor's UTM_MediumNo
UTM Parameter -> utm_contentWebsite Visitor's UTM_ContentNo
adobe_analytics -> channelAdobe Analytics Channel to apply attribution toOnly required when passing Adobe Analytics object
adobe_analytics -> visitor_idAdobe Analytics Visitor IdOnly required when passing Adobe Analytics object
adobe_analytics -> campaignAdobe Analytics Campaign IdOnly required when passing Adobe Analytics object
google_ads -> gclidGoogle Ads GCLIDOnly required when passing the Google Ads object
google_analytics -> client_idGoogle Analytics client id (typically retrieve from the GA cookie)No
google_analytics -> user_idGoogle Analytics user id (typically retrieve from the GA cookie)No
google_analytics -> pageGoogle Analytics page value (typically retrieve from the GA cookie)No
google_analytics -> hit_typeGoogle Analytics hit type value (typically retrieve from the GA cookie)No
google_analytics -> custom_metric_1-20Google Analytics Custom Metric.

Support for up to 20 custom metrics
No
google_analytics -> custom_dimension_1-20Google Analytics Custom Dimension.

Support for up to 20 custom metrics
No
google_analytics -> gclidGoogle Ads GCLID valueNo

Sample Response:

{
    "tag_ids": [
        {
            "tag_id": 53930459,
            "tracking_number": "8005623816"
        }
    ],
    "session_start_time": "2018-09-28T15:35:54.5043124Z",
    "session_end_time": "2018-09-28T15:36:54.5043124Z"
}

Response Field Definitions:

PropertyDescription
tag_ids - tag_idUnique tag id generated by Telmetrics
tag_ids - tracking_numberTracking number that was tagged
session_start_timeStarting time for the specified session match period
session_end_timeEnd time for the specified session match period match period

Accessing Calls with Lead Tracking Tags

Calls that have been matched to a Lead Tracking Tag will include tag details in the Processed Call Webhook

Sample Webhook:

"Id": "205739aba3cc4a7a811cd595f57b30db",
  "Attempt": 1,
  "Properties": {
    "CollectionType": "CallDetails",
    "UTC": "2018-09-28T15:37:30",
    "Organization": "4455"
  },
  "Notifications": [
    {
      "Action": "CallDetails.CallProcessed",
      "Incomplete": false,
      "TelmetricsId": 1991914131,
      "TelmetricsStudyID": 8798050,
      "CalledNumber": "8005623816",
      "TerminationNumber": "6472289548",
      "RegisteredDNC": false,
      "StartTime": "2018-09-28T11:36:09",
      "AnswerTime": "2018-09-28T11:36:16",
      "EndTime": "2018-09-28T11:36:43",
      "AnswerStatus": "Answered",
      "RingCount": 2,
      "CallSeconds": 27,
      "CallerNumber": "9055802958",
      "CallerName": "John Smith",
      "CallerStreet": "123 Main Street",
      "CallerCity": "Thomson",
      "CallerState": "NY",
      "CallerZip": "14202",
      "TimeZone": "Eastern",
      "VoiceRecordID": "cac480ce-e978-47ce-a163-51027d47a8be",
      "Latitude": 43.4585,
      "Longitude": -79.6685,
      "VoiceMailDetected": false,
      "VoiceTrends": {
        "Lead": false,
        "VoiceMail": false,
        "CurrentCustomer": true,
        "Telemarketer": false,
        "EmploymentInquiry": false
      },
      "OrganizationID": 4455,
      "OrgGroupID": 4455,
      "OrgGroupName": "Telmetrics Inc",
      
      "AttributionDetails": {
        "SessionId": null,
        "RuleDescription": null,
        "LandingPageUrl": null,
        "ReferrerUrl": null,
        "MultisessionFlag": false,
        "ip_address": "",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/67.0.3396.99 Safari/537.36",
        "sesssion_tag": {
          "tag_id": 53930459,
          "tag_data": "Custom Value",
          "tag_date": "2018-09-28T15:35:54.503"
        }
      }
    }
  ]
}

Updated a day ago

Lead Tracking


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.