telmetricsV3

Marchex Marketing Edge API Developer Documentation

Welcome to the Marchex Marketing Edge developer hub. You'll find comprehensive guides and documentation to help you start working with our API as quickly as possible.

Get Started    

Automatic Number Assignment

Using Telmetrics automated number assignment, a Tracking Number can be automatically selected based on the criteria you specify.

You may supply search criteria that will select and order:

  • A Tracking Number local to an existing advertiser's number
  • A Tracking Number local to a geographic region
  • A Toll-Free Tracking Number

Outlined below are the methods that can be used to provision a number 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://api.telmetrics.com/v3/api/groups/{group_id}/numbers

Remember when creating a number, 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 for reporting purposes
phone_number_request -> match_typelocaltonumber
phone_number_request -> local_to_numbera 10 digit phone number used to locate a local phone number
phone_number_request -> number_match_filterOptional will restrict match results to numbers matching the supplied 3 digit Area Code(NPA), or 6 digit Area Code(NPA)/Exchange(NXX)
call_routes -> route_typebasic (see the section on Call Routing for additional information)
call_routes -> route -> termination_numberadvertiser 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://api.telmetrics.com/v3/api/{group_id}/numbers

{
  "name": "ABC Company",
  "phone_number_request": {
    "match_type": "localtonumber",
    "local_to_number": "9056372046",
    "number_match_filter": "289"
  },
  "call_routes": {
    "route_type": "Basic",
    "route": {
      "termination_number": "4165551234"
    }
  }
}

A successful post will result in the creation of a tracking number:

{
    "id": 8660466,
    "name": "ABC Company 4",
    "group_id": 11623282,
    "status": "Active",
    "phone_number": "2898122093",
    "created_datetime": "2018-04-12T00:00:00Z",
    "call_routes": {
        "route_type": "Basic",
        "route": {
            "id": 30474073,
            "termination_number": "4165551234"
        }
    }
}

2. Local to Geographic Area

This number assignment method will allow you to automatically select and order a number in the specified geographical area.

Using this number assignment method, use the following endpoint to create your Tracking Number:

POST https://api.telmetrics.com/v3/api/{group_id)/numbers

Remember when creating a number, 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 for reporting purposes
phone_number_request -> match_typelocaltocity
phone_number_request -> cityName 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 -> statea two letter state/province code where you want a local number
phone_number_request -> number_match_filterOptional will restrict match results to numbers matching the supplied 3 digit Area Code(NPA), or 6 digit Area Code(NPA)/Exchange(NXX)
call_routes -> route_typebasic (see the section on Call Routing for additional information)
call_routes -> route -> termination_numberadvertiser 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://api.telmetrics.com/v3/api/{groupid}/numbers

{
  "name": "ABC Company",
  "phone_number_request": {
    "match_type": "localtocity",
    "city":"atlanta",
    "state":"ga",
    "number_match_filter": "404"
  },
  "call_routes": {
    "route_type": "Basic",
    "route": {
      "termination_number": "4043993433"
    }
  }
}

A successful post will result in the creation of a tracking number:

{
    "id": 8660467,
    "name": "ABC Company",
    "group_id": 11623282,
    "status": "Active",
    "phone_number": "4043411266",
    "created_datetime": "2018-04-12T00:00:00Z",
    "call_routes": {
        "route_type": "Basic",
        "route": {
            "id": 30474074,
            "termination_number": "4043993433"
        }
    }
}

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 Tracking Number:

POST https://api.telmetrics.com/v3/api/groups/{groupid)/numbers

Remember when creating a number, 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 for reporting purposes
phone_number_request -> match_typetollfree
phone_number_request -> number_match_filterOptional will restrict match results to numbers matching the supplied 3 digit Area Code(NPA), or 6 digit Area Code(NPA)/Exchange(NXX)
call_routes -> route_typebasic (see the section on Call Routing for additional information)
call_routes -> route -> termination_numberadvertiser 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://api.telmetrics.com/v3/api/{groupid}

{
  "name": "ABC Company",
  "phone_number_request": {
    "match_type": "tollfree",
    "number_match_filter": "833"
  },
  "call_routes": {
    "route_type": "Basic",
    "route": {
      "termination_number": "4043993433"
    }
  }
}

A successful post will result in the creation of a tracking number:

{
    "id": 8660468,
    "name": "ABC Company 6",
    "group_id": 11623282,
    "status": "Active",
    "phone_number": "8332018273",
    "created_datetime": "2018-04-12T00:00:00Z",
    "sms_routes": {
        "route_type": "None"
    },
    "call_routes": {
        "route_type": "Basic",
        "route": {
            "id": 30474075,
            "termination_number": "4043993433"
        }
    }
}

Updated about a year ago

Automatic Number Assignment


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.