Toll-free phone numbers - search & ordering

Shows how to search and order toll-free numbers.

Use this API to find new toll-free numbers. We allow users to search for numbers based on a contains field. We allow you to search for consecutive numbers, and let you specify a quantity of numbers (up to 10 at a time).

To use Toll-free numbers there's only 2 steps - search and order, no reservation or checkout necessary.

Authentication

This function is available via our new GraphQL API. You can read more about how to authenticate to this API here.

Search for toll-free numbers

To search for numbers use the searchPhoneNumbersQuery GraphQL query, it'll return a list of numbers you can order. The numbers aren't reserved, so maybe they won't be available until you decide to order, in that case, just search for new numbers.

query searchPhoneNumbersQuery(
  $contains: String
  $quantity: Int
  $consecutive: Boolean
) {
  tollfreeNumbers(
    contains: $contains
    quantity: $quantity
    consecutive: $consecutive
  ) {
    numbers
  }
}

Example variables

{
  "contains":"888xxxxxxx",
  "quantity":2,
  "consecutive":false
}

Example response

{
  "data": {
    "tollfreeNumbers": {
      "numbers": [
        "18886834580",
        "18886834690"
      ]
    }
  }
}

Order toll-free numbers

To order toll-free numbers, pass the numbers from the previous call and set smsEnable to true or false, depending if you want to enable the numbers for SMS.

It usually takes about 10 minutes for voice service activation. For SMS you need to submit a Verified Sender form for ordered numbers.

mutation orderTollfreeNumbersMutation(
  $numbers: [String]
  $smsEnable: Boolean
) {
  orderTollfreeNumbers(numbers: $numbers, smsEnable: $smsEnable) {
    numbers
    orderId
  }
}

Example variables

{
  "numbers": ["18886830411"],
  "smsEnable":true
}

Example response

{
  "data": {
    "orderTollfreeNumbers": {
      "numbers": ["18886830411"],
      "orderId":"999000261-ORD"
    }
  }
}

Remember: After ordering toll-free numbers, you should register a campaign for them using the Toll-Free Verified Sender Form, you can find the form here.

More info on campaign registration can be here.

Disconnecting toll-free numbers

To disconnect a toll-free number, check the following section.

Disconnect Number