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://edgeapi.marchex.io/marketingedge/v5/api/groups/{group_id}/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://edgeapi.marchex.io/marketingedge/v5/api/groups/{group_id}/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://edgeapi.marchex.io/marketingedge/v5/api/groups/{group_id}/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://edgeapi.marchex.io/marketingedge/v5/api/campaigns/{campaign_id}/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",
    "campaign_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://edgeapi.marchex.io/marketingedge/v5/api/groups/{group_id)/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://edgeapi.marchex.io/marketingedge/v5/api/groups/{group_id}/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"
        }
    }
}