Geographic (Local) Numbers

Geographic Numbers Local to a City/Region

Geographic numbers 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 local to a city, submit a request similar to the following:

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

{
  "name": "ABC Company 123",
  "phone_number_request": {
    "number_type": "international",
    "match_type": "geographic",
    "city": "London",
    "iso_country": "GB"
  },
  "call_routes": {
    "route_type": "Basic",
    "route": {
      "termination_number": "+441634567700",
      "features": {
        "call_record": {
          "enabled": true,
          "notification_text": "this call will be recorded",
          "require_confirmation": false,
          "record": true,
          "redaction_enabled": false
        },
        "whisper": {
          "enabled": true,
          "notification_text": "call brought to you by xyz"
        }
      }
    }
  }
}

Response

{
    "id": 9570223,
    "name": "ABC Company 123",
    "group_id": 12462424,
    "status": "Active",
    "phone_number": "+442036950193",
    "created_datetime": "2020-07-30T18:48:43.711Z",
    "modified_datetime": "2020-07-30T18:48:43.711Z",
    "sms_routes": {
        "route_type": "None"
    },
    "call_routes": {
        "route_type": "Basic",
        "route": {
            "id": 31777269,
            "termination_number": "+441634567700",
            "features": {
                "call_record": {
                    "enabled": true,
                    "notification_text": "this call will be recorded",
                    "require_confirmation": false,
                    "record": true,
                    "redaction_enabled": false
                },
                "whisper": {
                    "enabled": true,
                    "notification_text": "call brought to you by xyz"
                }
            }
        }
    }
}

Geographic Numbers Local to an Area Code

To order a Local (geographic) number 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}/numbers

{
  "name": "ABC Company 123",
  "phone_number_request": {
    "number_type": "international",
    "match_type": "geographic",
    "area_code": "0121",
    "iso_country": "GB"
  },
  "call_routes": {
    "route_type": "Basic",
    "route": {
      "termination_number": "+441634567700",
      "features": {
        "call_record": {
          "enabled": true,
          "notification_text": "this call will be recorded",
          "require_confirmation": false,
          "record": true,
          "redaction_enabled": false
        },
        "whisper": {
          "enabled": true,
          "notification_text": "call brought to you by xyz"
        }
      }
    }
  }
}

Response

{
    "id": 9570224,
    "name": "ABC Company 123",
    "group_id": 12462424,
    "status": "Active",
    "phone_number": "+441213681256",
    "created_datetime": "2020-07-30T18:52:00.056Z",
    "modified_datetime": "2020-07-30T18:52:00.056Z",
    "sms_routes": {
        "route_type": "None"
    },
    "call_routes": {
        "route_type": "Basic",
        "route": {
            "id": 31777270,
            "termination_number": "+441634567700",
            "features": {
                "call_record": {
                    "enabled": true,
                    "notification_text": "this call will be recorded",
                    "require_confirmation": false,
                    "record": true,
                    "redaction_enabled": false
                },
                "whisper": {
                    "enabled": true,
                    "notification_text": "call brought to you by xyz"
                }
            }
        }
    }
}

Field Definitions

FieldDescriptionRequired
nameA unique name that identifies the numberYes
phone_number_request -> number_typeFor international number ordering, this field must be set to: internationalYes
phone_number_request -> match_typeFor Toll Free numbers, this value must be set to: tollfreeYes
phone_number_request -> cityCity that the number must be local toYes (or alternatively area code)
phone_number_request -> regionRegion/Province/State/Territory that the city is locatedVaries from country to country
phone_number_request ->dialling code as defined in: https://www.ofcom.org.uk/phones-telecoms-and-internet/advice-for-consumers/advice/telephone-area-codes-toolYes (or alternatively city/region)
phone_number_request -> iso_countryProvide the two letter ISO country abbreviation where the number should be provisioned from. For details refer to our list of Supported CountriesYes
phone_number_request -> owner_address_detailsThe owner_address_details portion of the request defines a physical address and name for the purposes of number registration. Many countries require these details to be provided when creating a tracking number.Yes
phone_number_request -> owner_address_details -> salutationSalutation of the person the number will be registered to (Mr/Mrs/Ms/etc)Yes
phone_number_request -> owner_address_details -> first_nameFirst name of the person the number will be registeredYes
phone_number_request -> owner_address_details -> last_nameLast name of the person the number will be registeredYes
phone_number_request -> owner_address_details -> registration_nameBusiness entity that the number will be registered toYes
phone_number_request -> owner_address_details -> building_numberMailing address building numberYes
phone_number_request -> owner_address_details -> streetMailing address street nameYes
phone_number_request -> owner_address_details -> cityMailing address cityYes
phone_number_request -> owner_address_details -> regionMailing address regionYes
phone_number_request -> owner_address_details -> postal_codeMailing address postal codeYes
phone_number_request -> owner_address_details -> iso_countryMailing address country. Please note that the owner address details must correspond to the value specified in: phone_number_request -> iso_countryYes
call_routes -> route_typeAt this time, only "Basic" routing is supported for international orderingYes
call_routes -> route -> termination_numberThe phone number where all calls will be forwarded to. Please note that the termination_number must be located within the country specified in: phone_number_request -> iso_countryYes