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:

FieldValue
namea unique name to identify the Number Pool for reporting purposes
phone_number_request -> number_typeinternational
phone_number_request -> match_typegeographic
phone_number_request -> citycity the number is required to be local to
phone_number_request -> regionregion the number is required to be local to
not required in all countries
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

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:

FieldValue
namea unique name to identify the Number Pool for reporting purposes
phone_number_request -> number_typeinternational
phone_number_request -> match_typegeographic
phone_number_request -> area_codearea/dialling code the number is required to be local to
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

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:

FieldValue
namea unique name to identify the Number Pool for reporting purposes
phone_number_request -> number_typeinternational
phone_number_request -> match_typetollfree
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

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:

FieldValue
namea unique name to identify the Number Pool for reporting purposes
phone_number_request -> number_typeinternational
phone_number_request -> match_typenational
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