Search for Purchasable Phone Numbers

This endpoint lets you search for purchasable phone numbers by state or rate center, or by your specified search value.

Endpoint

GET /numbers/available

Query Parameters

  • limit
    integer

    Limits the number of items to retrieve. A maximum of 200 items can be retrieved with 10 being the default value if not specified.

  • starts_with
    integer

    Filters by and displays phone numbers that start with your specified value. The default assumes a Country code of1 unless the user specifies a different '+'country code.

  • contains
    integer

    Filters by and displays phone numbers that contain your specified value.

  • ends_with
    integer

    Filters by and displays phone numbers that end with your search value.

  • rate_center
    string

    Filters by and displays phone numbers in the specified case-insensitive abbreviated rate center, not the full name as differentiated in the NPA Rate Center Reports.

  • state
    string

    Filters by and displays phone numbers in the specified case-insensitive 2-letter abbreviated US state or Canadian province or territory. For example, WA for Washington State, USA and AB for Alberta, Canada.

  • number_type
    string

    Allows filtering for either Toll-free only, or Longcode only. For example, number_type='toll-free' will only return numbers that are toll-free.

    Allowed values are 'toll-free' and 'longcode'.

  • iso_country
    string

    Allows filtering for specific countries. For example, iso_country='BE' will only return numbers that are in Belgium.

    Allowed values are found in the 'ISO 3166-1 alpha-2' specification.

  • order_by
    string

    Allows ordering of the query results.

    Allowed Ordering types are:

    • monthly_cost
    • iso_country
    • number_type

      Toll-free or longcode.

    • state
    • rate_center
    • number, value, tn

      These all equate to ordering by the phone number.

    Along with the ordering field, you need to include the direction of the ordering, asc, or desc.

    For example, order_by=iso_country,asc & order_by=monthly_cost,asc.

  • offset
    integer

    Offsets the list of phone numbers by your specified value. For example, if you have 4 phone numbers and you entered 1 as your offset value, then only 3 of your phone numbers will be displayed in the response.

Response Fields

On success, the HTTP status code in the response header is 200 OK and the response body contains an array of phone number objects in JSON format. On error, the header status code is an error code and the response body contains an array of error objects.

  • data
    array

    An array of purchasable phone number objects that satisfy your query.

    • attributes
      object

      Phone number object composed of the following properties:

      • monthly_cost float- Recurring monthly charge for the phone number in USD.

      • number_type string- Phone number type. Possible values are longcode and toll-free.

      • rate_center string- The rate center associated with the area code and exchange code (NPANXX). This is represented by the abbreviated value, not the full name as differentiated in the NPA Rate Center Reports.

      • setup_cost float- Initial one-time setup cost in USD for the purchasable phone number.

      • state string- The 2-letter abbreviated US state or Canadian province or territory in which the area code and exchange code (NPANXX) is located. For example, WA for Washington State, USA and AB for Alberta, Canada.

      • iso_country string- The 2-letter abbreviated country code where the number is located. For example, BE for Belgium and US for the United States.

      • value integer- 10-digit North American phone number with the prefix 1 for the country code.

      • tier string- The Tier associated with this number. For example, Standard.

      • inbound_rate string- The Inbound Rate associated with this number. For what kind of rate this is, see rate_type below. For example, 0.01200 for Standard DIDs.

      • rate_type string- The type of inbound rate associated with this number.
        Inbound Local - the rate for inbound calls for this number: inbound local.
        Toll-Free - the lower US 48 states rate for this number: lower US 48 states.
        International Local (ITL) - the rate for the local country for this number: international local.
        International Toll-Free (ITFS) - The blended rate for country for this number: international in-country toll-free. ITFS numbers also support OLI codes and rates will differ based on supported OLI codes.

    • id
      integer

      ID of the phone number object which is equal to its value.

    • links
      object

      Links object pointing to the phone number's URI. For example, https://api.flowroute.com/v2/numbers/12012061234.

    • type
      string

      This will always be number.

  • links
    object

    Links object pointing to your search and a link to the next page if any. For example, https://api.flowroute.com/v2/numbers?starts_with=1206&limit=10&offset=0.

Example Request

                                GET /v2/numbers/available?starts_with=650&limit=3 HTTP/1.1
	Content-Type: application/vnd.api+json
	Accept: application/vnd.api+json
                                
                            

Example Request

                            curl -X GET "https://api.flowroute.com/v2/numbers/available?starts_with=650&limit=3" -u accessKey:secretKey
                        

Example Responses

200 OK

                            {
  "data": [
    {
      "attributes": {
        "monthly_cost": 1.25,
        "number_type": "longcode",
        "rate_center": "millbrae",
        "inbound_rate": 0.01200,
        "rate_type": "local",
        "tier": "Standard",
        "setup_cost": 3.99,
        "state": "ca",
        "iso_country": "US",
        "value": "16502390199"
      },
      "id": "16502390199",
      "links": {
        "related": "https://api.flowroute.com/v2/numbers/16502390199"
      },
      "type": "number"
    },
    {
      "attributes": {
        "monthly_cost": 1.25,
        "number_type": "longcode",
        "rate_center": "millbrae",
        "inbound_rate": 0.01200,
        "rate_type": "local",
        "tier": "Standard",
        "setup_cost": 3.99,
        "state": "ca",
        "iso_country": "US",
        "value": "16502390211"
      },
      "id": "16502390211",
      "links": {
        "related": "https://api.flowroute.com/v2/numbers/16502390211"
      },
      "type": "number"
    },
    {
      "attributes": {
        "monthly_cost": 1.25,
        "number_type": "longcode",
        "rate_center": "millbrae",
        "inbound_rate": 0.01200,
        "rate_type": "local",
        "tier": "Standard",
        "setup_cost": 1.0,
        "state": "ca",
        "iso_country": "US",
        "value": "16502390214"
      },
      "id": "16502390214",
      "links": {
        "related": "https://api.flowroute.com/v2/numbers/16502390214"
      },
      "type": "number"
    }
  ],
  "links": {
    "next": "https://api.flowroute.com/v2/numbers/available?starts_with=1650&limit=3&offset=3",
    "self": "https://api.flowroute.com/v2/numbers/available?starts_with=1650&limit=3&offset=0"
  }
}
                        
                        

422 UNPROCESSABLE ENTITY

                            {
  "errors": [
    {
      "detail": "Invalid type: `limit` must have a numeric value.",
      "id": "1dbcc038-fa1c-4c42-9934-0d8218036035",
      "status": 422
    }
  ]
}