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    

Creating a Number Pool

When creating a Number Pool, you may supply search criteria that will select and order:

  • Numbers local to an existing advertiser's number
  • Numbers local to a geographic region
  • Toll-Free Tracking Numbers

Outlined below are the methods that can be used to provision a Number Pool that best suits your needs.

1. Local to Number

Using this number assignment method, you may use the following endpoint to create your number:

POST https://api.telmetrics.com/v3/api/groups/{groupid}/numberpool

Remember when creating a Number Pool, it must be assigned to a group.

The following fields are used in this request, and must be passed in your request:

FieldValue
namea unique name to identify the Number Pool for reporting purposes
phone_number_request -> match_typelocaltonumber
phone_number_request -> local_to_numbera 10 digit phone number used to locate a local phone number
phone_number_request -> number_match_filterOptional will restrict match results to numbers matching the supplied 3 digit Area Code(NPA), or 6 digit Area Code(NPA)/Exchange(NXX)
match_periodHow many minutes to hold a session open to await a phone call
quantityHow many numbers the pool should contain
replacement_configurationThis block defines which numbers should be replaced, and when the should be replaced based on the source the website visitor arrives from, and the URL parameters that are present in the landing page URL. For more details on replacement configuration, please see the Number Replacement Rules portion of this documentation.
replacement_configuration -> numbers_to _replaceAn array of alphanumeric phone numbers that will be replaced from the pool when the match criteria is met.

Example:
"numbers_to_replace": [
"905219CARS",
"4045553434"
]
replacement_configuration -> replace_all_numbersUse this option to replace all numbers on the webpage. Note that this feature cannot be used in combination with replacement_configuration -> numbers_to _replace

Example: "replace_all_numbers":true
replacement_configuration -> tracking_sourcesAn array of criteria that must be met for a number to be displayed from this pool
replacement_configuration -> tracking_sources -> referrer_domainReferrers that a website visitor must arrive from in order for number replacement to occur.

Example: Any,Bing, Google

To retrieve the full set of referrers, please refer to the DNI Referrers portion of this documentation
replacement_configuration -> tracking_sources -> url_triggersA URL parameter that must be present in order for number replacement to occur.

Example: gclid=%, utm_campaign=wintertires

This field is optional
call_routes -> route_typebasic (see the section on Call Routing for additional information).

At this time, only Basic routing is supported for Number Pools.
call_routes -> route -> termination_numberadvertiser phone number where calls should be forwarded to

Below is an example of how to request a number using the criteria outlined above:

POST https://api.telmetrics.com/v3/api/groups/{groupid}/numberpool

{
    "name": "ABC Company - Google AdWords Attribution",
    "phone_number_request": {
        "match_type": "localtonumber",
        "local_to_number": "2123932233"
    },
    "match_period": 30,
    "quantity": 3,
    "replacement_configuration": {
        "numbers_to_replace": [
            "905219CARS",
            "4045553434"
        ],
        "tracking_sources": [
            {
                "referrer_domain": "any",
                "url_triggers": [
                    "gclid=%"
                ]
            }
        ]
    },
    "call_routes": {
        "route_type": "Basic",
        "route": {
            "termination_number": "4165551234"
        }
    }
}

A successful post will result in the creation of a tracking number:

{
    "id": 867,
    "name": "ABC Company - Google AdWords Attribution",
    "group_id": 11623343,
    "status": "active",
    "match_period": 30,
    "quantity": 3,
    "numbers": [
        {
            "id": 8660626,
            "phone_number": "3322552808"
        },
        {
            "id": 8660627,
            "phone_number": "3322552809"
        },
        {
            "id": 8660628,
            "phone_number": "3322552810"
        }
    ],
    "replacement_configuration": {
        "numbers_to_replace": [
            "905219CARS",
            "4045553434"
        ],
        "tracking_sources": [
            {
                "referrer_domain": "*",
                "url_triggers": [
                    "gclid=%"
                ]
            }
        ]
    },
    "call_routes": {
        "route_type": "Basic",
        "route": {
            "termination_number": "4165551234"
        }
    }
}

2. Local to Geographic Area

This number assignment method will allow you to automatically select and order a Number Pool in the specified geographical area.

Using this number assignment method, use the following endpoint to create your Tracking Number:

POST https://api.telmetrics.com/v3/api/groups/{groupid}/numberpool

Remember when creating a number pool, it must be assigned to a group.

The following fields are used in this request, and must be passed in your request:

FieldValue
namea unique name to identify the Number Pool for reporting purposes
phone_number_request -> match_typelocaltocity
phone_number_request -> cityName of the city where you want a local number. Be aware when using this field that not all cities will map back to a local calling area
phone_number_request -> statea two letter state/province code where you want a local number
phone_number_request -> number_match_filterOptional will restrict match results to numbers matching the supplied 3 digit Area Code(NPA), or 6 digit Area Code(NPA)/Exchange(NXX)
match_periodHow many minutes to hold a session open to await a phone call
quantityHow many numbers the pool should contain
replacement_configurationThis block defines which numbers should be replaced, and when the should be replaced based on the source the website visitor arrives from, and the URL parameters that are present in the landing page URL. For more details on replacement configuration, please see the Number Replacement Rules portion of this documentation.
replacement_configuration -> numbers to replaceAn array of alphanumeric phone numbers that will be replaced from the pool when the match criteria is met.

Example:
"numbers_to_replace": [
"905219CARS",
"4045553434"
]
replacement_configuration -> tracking_sourcesAn array of criteria that must be met for a number to be displayed from this pool
replacement_configuration -> tracking_sources -> referrer_domainReferrers that a website visitor must arrive from in order for number replacement to occur.

Example: Any,Bing, Google

To retrieve the full set of referrers, please refer to the DNI Referrers portion of this documentation
replacement_configuration -> tracking_sources -> url_triggersA URL parameter that must be present in order for number replacement to occur.

Example: gclid=%, utm_campaign=wintertires

This field is optional
call_routes -> route_typebasic (see the section on Call Routing for additional information).

At this time, only Basic routing is supported for Number Pools.
call_routes -> route -> termination_numberadvertiser phone number where calls should be forwarded to

Below is an example of how to request a number using the criteria outlined above:

POST https://api.telmetrics.com/v3/api/groups/{groupid}/numberpool

{
        "name": "ABC Company - Google AdWords Tracker",
        "phone_number_request": {
            "match_type": "localtocity",
            "city": "Toronto",
          "state": "ON"
        },
        "match_period": 30,
        "quantity": 3,
        "replacement_configuration": {
            "numbers_to_replace": [
            "905219CARS",
            "4045553434"
            ],
            "tracking_sources": [
                {
                    "referrer_domain": "any",
                    "url_triggers": [
                        "gclid=%"
                    ]
                }
            ]
        },
        "call_routes": {
            "route_type": "Basic",
            "route": {
                "termination_number": "4165551234"
            }
        }
    }

A successful post will result in the creation of a tracking number:

{
    "id": 868,
    "name": "ABC Company - Google AdWords Tracker",
    "group_id": 11623343,
    "status": "active",
    "match_period": 30,
    "quantity": 3,
    "numbers": [
        {
            "id": 8660629,
            "phone_number": "4373700996"
        },
        {
            "id": 8660630,
            "phone_number": "4373701003"
        },
        {
            "id": 8660631,
            "phone_number": "4373701015"
        }
    ],
    "replacement_configuration": {
        "numbers_to_replace": [
            "905219CARS",
            "4045553434"
        ],
        "tracking_sources": [
            {
                "referrer_domain": "*",
                "url_triggers": [
                    "gclid=%"
                ]
            }
        ]
    },
    "call_routes": {
        "route_type": "Basic",
        "route": {
            "termination_number": "4165551234"
        }
    }
}

3. Toll-Free

This number assignment method will allow you to automatically select and order a Toll-Free number.

Using this number assignment method, use the following endpoint to create your Number Pool:

POST https://api.telmetrics.com/v3/api/groups{groupid)/numberpools

Remember when creating a Number Pool, it must be assigned to a group.

The following fields are used in this request, and must be passed in your request:

FieldValue
nameA unique name to identify the Number Pool for reporting purposes
phone_number_request -> match_typeTollFree
phone_number_request -> number_match_filterOptional will restrict match results to numbers matching the supplied 3 digit Area Code(NPA), or 6 digit Area Code(NPA)/Exchange(NXX)
match_periodHow many minutes to hold a session open to await a phone call
quantityHow many numbers the pool should contain
replacement_configurationThis block defines which numbers should be replaced, and when the should be replaced based on the source the website visitor arrives from, and the URL parameters that are present in the landing page URL. For more details on replacement configuration, please see the Number Replacement Rules portion of this documentation.
replacement_configuration -> numbers to replaceAn array of alphanumeric phone numbers that will be replaced from the pool when the match criteria is met.

Example:
"numbers_to_replace": [
"905219CARS",
"4045553434"
]
replacement_configuration -> tracking_sourcesAn array of criteria that must be met for a number to be displayed from this pool
replacement_configuration -> tracking_sources -> referrer_domainReferrers that a website visitor must arrive from in order for number replacement to occur.

Example: Any,Bing, Google

To retrieve the full set of referrers, please refer to the DNI Referrers portion of this documentation
replacement_configuration -> tracking_sources -> url_triggersA URL parameter that must be present in order for number replacement to occur.

Example: gclid=%, utm_campaign=wintertires

This field is optional
call_routes -> route_typebasic (see the section on Call Routing for additional information).

At this time, only Basic routing is supported for Number Pools.
call_routes -> route -> termination_numberadvertiser phone number where calls should be forwarded to

Below is an example of how to request a number using the criteria outlined above:

POST https://api.telmetrics.com/v3/api/groups/{groupid}/numberpools

{
        "name": "ABC Company - Google AdWords Tracker",
        "phone_number_request": {
            "match_type": "TollFree"
        },
        "match_period": 30,
        "quantity": 3,
        "replacement_configuration": {
            "numbers_to_replace": [
            "905219CARS",
            "4045553434"
            ],
            "tracking_sources": [
                {
                    "referrer_domain": "any",
                    "url_triggers": [
                        "gclid=%"
                    ]
                }
            ]
        },
        "call_routes": {
            "route_type": "Basic",
            "route": {
                "termination_number": "4165551234"
            }
        }
    }

A successful post will result in the creation of a tracking number:

{
    "id": 869,
    "name": "ABC Company - Google AdWords Tracker",
    "group_id": 11623343,
    "status": "active",
    "match_period": 30,
    "quantity": 3,
    "numbers": [
        {
            "id": 8660632,
            "phone_number": "8008476880"
        },
        {
            "id": 8660633,
            "phone_number": "8008511620"
        },
        {
            "id": 8660634,
            "phone_number": "8008513488"
        }
    ],
    "replacement_configuration": {
        "numbers_to_replace": [
            "905219CARS",
            "4045553434"
        ],
        "tracking_sources": [
            {
                "referrer_domain": "*",
                "url_triggers": [
                    "gclid=%"
                ]
            }
        ]
    },
    "call_routes": {
        "route_type": "Basic",
        "route": {
            "termination_number": "4165551234"
        }
    }
}

Updated 28 days ago

Creating a Number Pool


Suggested Edits are limited on API Reference Pages

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