# Toll-free phone numbers - search & ordering

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

{% hint style="info" %}
This function is available via our new GraphQL API. You can read more about how to authenticate to this API [here](/graphql-api-and-authentication.md).
{% endhint %}

## 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.

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

### Example variables

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

### Example response

```json
{
  "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.

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

### Example variables

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

### Example response

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

{% hint style="info" %}
**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](https://customer-portal.tsgglobal.com/tf-verification-form).

More info on campaign registration can be [here](https://support.tsgglobal.com/hc/en-us/articles/5872363711387-New-Toll-Free-SMS-MMS-Verified-Sender-Requirements).
{% endhint %}

## Disconnecting toll-free numbers

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

{% content-ref url="/pages/V4CG3FJf8ZuPBSmAK8gZ" %}
[Disconnect Number](/api-reference/phone-numbers/disconnect-number.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tsgglobal.com/api-reference/phone-numbers/toll-free-phone-numbers-search-and-ordering.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.