Lead Tracking for Number Pools

Introduction

The Marchex 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.

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 Marchex using the following endpoint: POST https://edgeapi.marchex.io/marketingedge/v5/api/numberpools/{number_pool_id}/leadtracking

{
    "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"
    },
    "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."
        }
    ]
}

Batch Retrieval and Tagging

For some implementations you may need to request numbers from multiple number pools. To facilitate this operation a bulk tagging operation may be performed.

This is accomplished by submitting an HTTP post to https://edgeapi.marchex.io/marketingedge/v5/api/leadtracking/setBulkTag containing an array of tag requests. The following fields are required:

number_pool_id - this references the number pool that you want to request a number from
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 Marchex using the following endpoint: POST https://edgeapi.marchex.io/marketingedge/v5/api/numberpools/leadtracking/setBulkTag

[
    {
        "number_pool_id": 4444,        
        "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"
        },
        "google_ads": {
            "gclid": "23423423423432432"
        },
        "google_analytics": {
            "client_id": "123abc",
            "userId": "abcxyz",
            "page": "%2foo",
            "dimension_1": "abc",
            "metrics_1": "xyz",
            "hitType": "pageView",
            "gclid": "123"
        }
    },
    {
        "number_pool_id": 5555,        
        "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"
        },
        "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 pools included in the request:

[
    {
        "index": 0,
        "session_id": 71718402,
        "tracking_number": "8332283427",
        "multisession_flag": true,
        "session_start_time": "2020-06-15T19:07:20.8055803Z",
        "session_end_time": "2020-06-15T19:07:50.8055803Z",
        "number_pool_id": 4444,
        "allowMultiSession": true,
        "has_errors": false
    },
    {
        "index": 1,
        "session_id": 71718428,
        "tracking_number": "2128046122",
        "multisession_flag": true,
        "session_start_time": "2020-06-15T19:07:20.8055803Z",
        "session_end_time": "2020-06-15T19:07:50.8055803Z",
        "number_pool_id": 5555,
        "allowMultiSession": true,
        "has_errors": false
    }
]

In the event that all numbers in a pool are assigned to a Tag, the following response will be returned (note that results will be returned in the order requested) :

[
    {
        "index": 0,
        "number_pool_id": 4444,
        "allowMultiSession": false,
        "has_errors": false,
        "errors": [
            {
                "code": 8496,
                "description": "All numbers currently assigned to a session.  Increase quantity of numbers in Number Pool to resolve. (code: 008496)"
            }
        ]
    },
    {
        "index": 1,
        "session_id": 71718428,
        "tracking_number": "2128046122",
        "multisession_flag": true,
        "session_start_time": "2020-06-15T19:07:20.8055803Z",
        "session_end_time": "2020-06-15T19:07:50.8055803Z",
        "number_pool_id": 5555,
        "allowMultiSession": true,
        "has_errors": false
    }
]

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 Marchex 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