Finding Local Numbers

Using the Available Numbers API end-point you can search for local numbers.

Click here for additional resources related to AvailableNumbers

Searching for Local Numbers

The most common search technique is to set the localtonumber URL parameter to the number you're trying to match. In the example below, we're searching for numbers that are local to the phone number: (212) 343-2049

curl -H "x-organization-token: {authorization_token}" \
      -H "subscription-key: {subscription_key}" \
      -X GET \
      "https://edgeapi.marchex.io/marketingedge/v5/api/availablenumbers?type=local&localtonumber=2123432049"

The resulting response will only return numbers local to the number set in localtonumber

[
    {
        "sms_capable": false,
        "number": "3322552586",
        "area_code": "332",
        "exchange": "255",
        "suffix": "2586",
        "city": "New York City Zone 01",
        "state": "NY"
    },
    {
        "sms_capable": false,
        "number": "3322552630",
        "area_code": "332",
        "exchange": "255",
        "suffix": "2630",
        "city": "New York City Zone 01",
        "state": "NY",
    }
]

For details on how to provision a number returned by this request, refer to the Creating a Number portion of this documentation.

Searching for Numbers local to Geographic Area

When searching for a number that is local to a geographic area, you must supply the following fields:

city - A US or Canadian city
state - A valid 2 letter US State or Canadian province
type - local

In the example below, we're searching for a number local to Atlanta, Georgia:

curl -H "x-organization-token: {authorization_token}" \
      -H "subscription-key: {subscription_key}" \
      -X GET \
      "https://edgeapi.marchex.io/marketingedge/v5/api/availablenumbers?type=local&city=atlanta&state=GA"

The resulting response will only return numbers local to the city/state provided in the request:

[
    {
        "sms_capable": true,
        "number": "4043411118",
        "area_code": "404",
        "exchange": "341",
        "suffix": "1118",
        "city": "Atlanta",
        "state": "GA"
    },
    {
        "sms_capable": true,
        "number": "4043411266",
        "area_code": "404",
        "exchange": "341",
        "suffix": "1266",
        "city": "Atlanta",
        "state": "GA"
    }
  ]

For details on how to provision a number returned by this request, refer to the Creating a Number portion of this documentation.

Filtering Search Results by Area Code (NPA) & Exchange (NXX)

In situations where a specific Area Code (NPA) and/or Exchange (NXX) is required, they may be provided in your request as:

area_code - a 3 digit number
nxx - a 3 digit number

Please note, that these additional filter criteria may reduce the quantity of numbers that are returned.

In the following example, we are submitting a request for a number in Atlanta Georgia, that matches the area code 404, and exchange 341:

curl -H "x-organization-token: {authorization_token}" \
      -H "subscription-key: {subscription_key}" \
      -X GET \
      "https://edgeapi.marchex.io/marketingedge/v5/api/availablenumbers?type=local&city=atlanta&state=GA&area_code=404&exchange=341"

The following response will return only numbers matching the supplied search criteria:

[
    {
        "sms_capable": true,
        "number": "4043411118",
        "area_code": "404",
        "exchange": "341",
        "suffix": "1118",
        "city": "Atlanta",
        "state": "GA"
    },
    {
        "sms_capable": true,
        "number": "4043411266",
        "area_code": "404",
        "exchange": "341",
        "suffix": "1266",
        "city": "Atlanta",
        "state": "GA"
    }
]