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    

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:

Field

Value

name

a unique name to identify the Number Pool for reporting purposes

phone_number_request -> match_type

localtonumber

phone_number_request -> local_to_number

a 10 digit phone number used to locate a local phone number

phone_number_request -> number_match_filter

Optional will restrict match results to numbers matching the supplied 3 digit Area Code(NPA), or 6 digit Area Code(NPA)/Exchange(NXX)

match_period

How many minutes to hold a session open to await a phone call

quantity

How many numbers the pool should contain

replacement_configuration

This 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 _replace

An 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_numbers

Use 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_sources

An array of criteria that must be met for a number to be displayed from this pool

replacement_configuration -> tracking_sources -> referrer_domain

Referrers 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_triggers

A 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_type

basic (see the section on Call Routing for additional information).

At this time, only Basic routing is supported for Number Pools.

call_routes -> route -> termination_number

advertiser 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:

Field

Value

name

a unique name to identify the Number Pool for reporting purposes

phone_number_request -> match_type

localtocity

phone_number_request -> city

Name 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 -> state

a two letter state/province code where you want a local number

phone_number_request -> number_match_filter

Optional will restrict match results to numbers matching the supplied 3 digit Area Code(NPA), or 6 digit Area Code(NPA)/Exchange(NXX)

match_period

How many minutes to hold a session open to await a phone call

quantity

How many numbers the pool should contain

replacement_configuration

This 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 replace

An 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_sources

An array of criteria that must be met for a number to be displayed from this pool

replacement_configuration -> tracking_sources -> referrer_domain

Referrers 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_triggers

A 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_type

basic (see the section on Call Routing for additional information).

At this time, only Basic routing is supported for Number Pools.

call_routes -> route -> termination_number

advertiser 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:

Field

Value

name

A unique name to identify the Number Pool for reporting purposes

phone_number_request -> match_type

TollFree

phone_number_request -> number_match_filter

Optional will restrict match results to numbers matching the supplied 3 digit Area Code(NPA), or 6 digit Area Code(NPA)/Exchange(NXX)

match_period

How many minutes to hold a session open to await a phone call

quantity

How many numbers the pool should contain

replacement_configuration

This 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 replace

An 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_sources

An array of criteria that must be met for a number to be displayed from this pool

replacement_configuration -> tracking_sources -> referrer_domain

Referrers 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_triggers

A 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_type

basic (see the section on Call Routing for additional information).

At this time, only Basic routing is supported for Number Pools.

call_routes -> route -> termination_number

advertiser 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 3 months 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.