telmetricsV3

Telmetrics V3 API Developer Documentation

Welcome to the Telmetrics V3 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 for Number Pools

Introduction

The Telmetrics Lead Tracking API can be used to dynamically retrieve a Tracking Number from a Number Pool. When requesting a number, we provide the ability to submit a Lead Tracking Tag. 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.

Retrieving and Tagging a Number

Retrieving and applying a Lead Tracking Tag to a Tracking Number from a Number Pool is accomplished by submitting an HTTP post. The following fields are required:

  • 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 (please note that this is a different value than the key used to access the v3 API)
  • 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 submitted to Telmetrics using the following endpoint: POST https://api.telmetrics.com/v3/api/numberpools/{number_pool_id}/leadtracking

Below is a sample request:

{
    "key": "0b29468f-5240-457c-ac5c-9800ea46x23d",
    "tag_data": "listingId=123&LNX=456",
    "session_match_period": 15,
    "allow_multi_session": false,
    "referrer": "google.com",
    "landing_page": "http://123company.net?gclid=123&utm_campaign=summersale",
    "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",
        "hitType": "pageView",
        "gclid": "123"
    }
}

A successful request will generate a response containing a number from the number pool:

{
    "session_id": 63790075,
    "tracking_number": "8005551748",
    "multisession_flag": false,
    "session_start_time": "2019-06-06T15:26:39.2507548Z",
    "session_end_time": "2019-06-06T15:26:54.2507548Z"
}

In the event that all numbers in the pool are assigned to a Tag, the following response will be returned:

{
    "status": 404,
    "errors": [
        {
            "code": 105,
            "description": "All numbers currently assigned to a session.  Increase quantity of numbers in Number Pool to resolve."
        }
    ]
}

Reporting

Calls and Text conversations that are matched to a Lead Tracking tag will contain the tag details. Please refer to: Webhooks and Retrieving Phone Call Details for additional details.

Field Definitions

Field
Description
Required

key

A Telmetrics supplied value that validates the tag. Contact your account manager to obtain this value.

Yes

tracking_numbers

An array of tracking numbers that will be associated with the supplied tagging data if a call occurs within the match period

Yes

tag_data

An open text field that can be used to supply data specific to your tracking and attribution needs

No

allow_multi_session

Boolean field used to determine if a number should be returned if all numbers in the Number Pool are allocated to another Lead Tracking Tag.

No - when not supplied, will default to false

session_match_period

How long to wait (in seconds) for a call or text conversation to occur on one of the tracking numbers supplied in the tracking_numbers field

No - when not supplied, your Organization default will be applied

referrer

Referrer URL responsible for delivering a website visitor to the website where you are measuring attributions. Field must be passed as a valid URL

No

landing_page

Landing Page URL website visitor arrived on. Field must be passed as a valid URL

No

user_agent

Website Visitor's user agent

No

lattitude

Website Visitor's Lattitude

No

longitude

Website Visitor's Longitude

No

UTM Parameter -> utm_source

Website Visitor's UTM_Source

No

UTM Parameter -> utm_term

Website Visitor's UTM_Term (keyword)

No

UTM Parameter -> utm_campaign

Website Visitor's UTM_Campaign

No

UTM Parameter -> utm_medium

Website Visitor's UTM_Medium

No

UTM Parameter -> utm_content

Website Visitor's UTM_Content

No

adobe_analytics -> channel

Adobe Analytics Channel to apply attribution to

Only required when passing Adobe Analytics object

adobe_analytics -> visitor_id

Adobe Analytics Visitor Id

Only required when passing Adobe Analytics object

adobe_analytics -> campaign

Adobe Analytics Campaign Id

Only required when passing Adobe Analytics object

google_ads -> gclid

Google Ads GCLID

Only required when passing the Google Ads object

google_analytics -> client_id

Google Analytics client id (typically retrieve from the GA cookie)

No

google_analytics -> user_id

Google Analytics user id (typically retrieve from the GA cookie)

No

google_analytics -> page

Google Analytics page value (typically retrieve from the GA cookie)

No

google_analytics -> hit_type

Google Analytics hit type value (typically retrieve from the GA cookie)

No

google_analytics -> custom_metric_1-20

Google Analytics Custom Metric.

Support for up to 20 custom metrics

No

google_analytics -> custom_dimension_1-20

Google Analytics Custom Dimension.

Support for up to 20 custom metrics

No

google_analytics -> gclid

Google Ads GCLID value

No

Lead Tracking for Number Pools


Suggested Edits are limited on API Reference Pages

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