Creating a Number Pool

Geographic Number Pools by City/Region

Geographic Number Pools may be assigned using the details outlined in this documentation. Callers within the local calling area for the supplied city/region will not incur long distance toll charges when calling the tracking number.

Please note that when submitting these requests that the region field may be required to further refine the tracking number search scope.

To order a Local (geographic) number, submit a request similar to the following:

POST https://edgeapi.marchex.io/marketingedge/v5/api/groups/{group_id}/numberpools

{
  "name": "ABC Company 123",
  "match_period": 30,
  "quantity": 3,
  "phone_number_request": {
    "number_type": "international",
    "match_type": "geographic",
    "city": "Bristol",
    "iso_country": "GB"
  }, 
  "replacement_configuration": {
    "numbers_to_replace": [
      "01011231234",
      "4402078395555",
      "4409011231234"
    ],
    "tracking_sources": [
      {
        "referrer_domain": "Any",
        "url_triggers": [
          "gclid=*"
        ]
      }
    ]
  },
  "call_routes": {
    "route_type": "Basic",
    "route": {
      "termination_number": "+441274792823"
    }
  }
}

{
    "id": 31849,
    "name": "ABC Company 123",
    "group_id": 12462615,
    "status": "active",
    "match_period": 30,
    "quantity": 3,
    "numbers": [
        {
            "id": 9570553,
            "phone_number": "+441174090162"
        },
        {
            "id": 9570554,
            "phone_number": "+441174090163"
        },
        {
            "id": 9570555,
            "phone_number": "+441174090165"
        }
    ],
    "replacement_configuration": {
        "numbers_to_replace": [
            "01011231234",
            "4402078395555",
            "4409011231234"
        ],
        "tracking_sources": [
            {
                "referrer_domain": "Any",
                "url_triggers": [
                    "gclid=*"
                ],
                "track_organic": false
            }
        ],
        "replace_all_numbers": false
    },
    "sms_routes": {
        "route_type": "None"
    },
    "call_routes": {
        "route_type": "Basic",
        "route": {
            "termination_number": "+441274792823"
        }
    }
}

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 -> number_type	international
phone_number_request -> match_type	geographic
phone_number_request -> city	city the number is required to be local to
phone_number_request -> region	region the number is required to be local to not required in all countries
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

Geographic Number Pools by Dialling/Area Code

To order a Local (geographic) Number Pool local to a dialling code, submit a request similar to the following (for a list of dialling codes, please refer to the country's telecom regulator. UK Example: https://www.ofcom.org.uk/phones-telecoms-and-internet/advice-for-consumers/advice/telephone-area-codes-tool):

POST https://edgeapi.marchex.io/marketingedge/v5/api/groups/{group_id}/numberpools

{
  "name": "ABC Company 123",
  "match_period": 30,
  "quantity": 3,
  "phone_number_request": {
    "number_type": "international",
    "match_type": "geographic",
    "area_code": "024",
    "iso_country": "GB"
  }, 
  "replacement_configuration": {
    "numbers_to_replace": [
      "01011231234",
      "4402078395555",
      "4409011231234"
    ],
    "tracking_sources": [
      {
        "referrer_domain": "Any",
        "url_triggers": [
          "gclid=*"
        ]
      }
    ]
  },
  "call_routes": {
    "route_type": "Basic",
    "route": {
      "termination_number": "+441274792823"
    }
  }
}

{
    "id": 31850,
    "name": "ABC Company 123",
    "group_id": 12462615,
    "status": "active",
    "match_period": 30,
    "quantity": 3,
    "numbers": [
        {
            "id": 9570557,
            "phone_number": "+442477180193"
        },
        {
            "id": 9570558,
            "phone_number": "+442477180194"
        },
        {
            "id": 9570559,
            "phone_number": "+442477180209"
        }
    ],
    "replacement_configuration": {
        "numbers_to_replace": [
            "01011231234",
            "4402078395555",
            "4409011231234"
        ],
        "tracking_sources": [
            {
                "referrer_domain": "Any",
                "url_triggers": [
                    "gclid=*"
                ],
                "track_organic": false
            }
        ],
        "replace_all_numbers": false
    },
    "sms_routes": {
        "route_type": "None"
    },
    "call_routes": {
        "route_type": "Basic",
        "route": {
            "termination_number": "+441274792823"
        }
    }
}

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 -> number_type	international
phone_number_request -> match_type	geographic
phone_number_request -> area_code	area/dialling code the number is required to be local to
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

Toll Free Number Pools

International Toll Free numbers may be assigned using the details outlined in this documentation. Calls made to these numbers will not incur toll charges.

To order a Toll Free number, submit a request similar to the following:

POST https://edgeapi.marchex.io/marketingedge/v5/api/groups/{group_id}/numberpools

{
  "name": "ABC Company 123",
  "match_period": 30,
  "quantity": 3,
  "phone_number_request": {
    "number_type": "international",
    "match_type": "tollfree",
    "iso_country": "GB"
  }, 
  "replacement_configuration": {
    "numbers_to_replace": [
      "01011231234",
      "4402078395555",
      "4409011231234"
    ],
    "tracking_sources": [
      {
        "referrer_domain": "Any",
        "url_triggers": [
          "gclid=*"
        ]
      }
    ]
  },
  "call_routes": {
    "route_type": "Basic",
    "route": {
      "termination_number": "+441274792823"
    }
  }
}

{
    "id": 31851,
    "name": "ABC Company 126",
    "group_id": 12462615,
    "status": "active",
    "match_period": 30,
    "quantity": 3,
    "numbers": [
        {
            "id": 9570560,
            "phone_number": "+448000885644"
        },
        {
            "id": 9570561,
            "phone_number": "+448000885645"
        },
        {
            "id": 9570562,
            "phone_number": "+448000885650"
        }
    ],
    "replacement_configuration": {
        "numbers_to_replace": [
            "01011231234",
            "4402078395555",
            "4409011231234"
        ],
        "tracking_sources": [
            {
                "referrer_domain": "Any",
                "url_triggers": [
                    "gclid=*"
                ],
                "track_organic": false
            }
        ],
        "replace_all_numbers": false
    },
    "sms_routes": {
        "route_type": "None"
    },
    "call_routes": {
        "route_type": "Basic",
        "route": {
            "termination_number": "+441274792823"
        }
    }
}

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 -> number_type	international
phone_number_request -> match_type	tollfree
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

National Number Pools

National numbers may be assigned using the details outlined in this documentation. These phone numbers are in ranges designated to be reachable from the entire country at the same price anywhere in the country as a local phone call. Unlike geographic phone numbers, which are tied to a particular city or region such as London or Paris, national phone numbers are not tied to a particular local area. Please note that not all countries support national numbers; additionally, these numbers may not be accessible outside of the country in which they are assigned.

To order a National number, submit a request similar to the following:

POST https://edgeapi.marchex.io/marketingedge/v5/api/groups/{group_id}/numberpools

{
  "name": "ABC Company 127",
  "match_period": 30,
  "quantity": 3,
  "phone_number_request": {
    "number_type": "international",
    "match_type": "national",
    "iso_country": "GB"
  }, 
  "replacement_configuration": {
    "numbers_to_replace": [
      "01011231234",
      "4402078395555",
      "4409011231234"
    ],
    "tracking_sources": [
      {
        "referrer_domain": "Any",
        "url_triggers": [
          "gclid=*"
        ]
      }
    ]
  },
  "call_routes": {
    "route_type": "Basic",
    "route": {
      "termination_number": "+441274792823"
    }
  }
}

{
    "id": 31852,
    "name": "ABC Company 127",
    "group_id": 12462615,
    "status": "active",
    "match_period": 30,
    "quantity": 3,
    "numbers": [
        {
            "id": 9570563,
            "phone_number": "+443308180609"
        },
        {
            "id": 9570564,
            "phone_number": "+443308180610"
        },
        {
            "id": 9570565,
            "phone_number": "+443308180611"
        }
    ],
    "replacement_configuration": {
        "numbers_to_replace": [
            "01011231234",
            "4402078395555",
            "4409011231234"
        ],
        "tracking_sources": [
            {
                "referrer_domain": "Any",
                "url_triggers": [
                    "gclid=*"
                ],
                "track_organic": false
            }
        ],
        "replace_all_numbers": false
    },
    "sms_routes": {
        "route_type": "None"
    },
    "call_routes": {
        "route_type": "Basic",
        "route": {
            "termination_number": "+441274792823"
        }
    }
}

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 -> number_type	international
phone_number_request -> match_type	national
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