Overview

Flowroute is proud to unveil a much more improved version of its number and route management API. For more details on the benefits of using Numbers v2 over Numbers v1, see Number Management with New API Version.

New to Number Management with Flowroute?

Flowroute has two Numbers API versions you can work with: v1 which utilizes a custom Authentication Scheme with obscurely named resources and objects and v2 with standard HTTP Basic Auth and more human-friendly resource and object names. Read on to skip the obscure bits of Numbers v1 and send your first request with Numbers v2.

Steps


Sign up and retrieve your API credentials

Sign up for your Flowroute account via the Manage portal. Make sure to activate your account to receive your API credentials.

Once your account is activated, you can find your API credentials in the Preferences > API Control tab of the Flowroute Manage portal. Your API credentials contain the following information:
Key Value
Access Key This serves as your API username and is equivalent to your Tech Prefix.
Secret Key This serves as your API password and can be reset if necessary.

Search for and purchase a phone number

The Flowroute API v2 provides an alternative programmatic way for you to search through the Flowroute inventory of phone numbers and make a purchase. For the Manage method of purchasing a phone number, see Purchase a DID.

In this tutorial, we will show you three methods of searching and buying of phone numbers via the Flowroute API v2:

Phone Number Search

Request via cURL

  1. Open a command shell session.
  2. If you haven't installed cURL previously, download your specific source package here.
  3. Copy the following example GET request.
  4. curl -X GET "https://api.flowroute.com/v2/numbers/available?starts_with=347&limit=3&contains=666" -u accessKey:secretKey
    
                        
  5. Replace accessKey:secretKey with your API credentials.
  6. In the query parameters section of your cURL request right after the question mark, https://api.flowroute.com/v2/numbers/available?, make the following substitutions:
    • Replace the starts_with value with your preferred area code.
    • Replace the limit value with your desired number. A maximum of 200 items can be retrieved with 10 being the default if not specified.
    • Replace the contains value with your favorite number or number combination.
  7. Press Enter.

Tips

To avoid errors, make sure to:

  • Enter your API credentials correctly.
  • Use vertical quotes in your request. Learn more about Unicode and and ISO 10646 standards in ASCII and Unicode quotation marks.
  • Use a backslash (\) at the end of lines to break up a long cURL statement into easier-to-read lines if you're in a UNIX environment. If you're using Windows, replace any backslash at the end of lines with the caret (^) character. Here's a great guide for installing and using cURL.

Request via Postman

Postman is a highly intuitive GUI platform that lets you build API requests very quickly. Download it for free here. Postman also has a very useful tutorial on how to send your HTTP requests.

  1. In the URL tab, copy and paste the HTTP portion of your cURL request above.
  2. In the Authorization tab, do the following:
    • Select Basic Auth for the Type.
    • Enter your accessKey in the username field, and your secretKey in the password field.
  3. Hit Send.
  4. An example GET request with the same query parameters and a 200 OK response

Request via Python

  1. To begin, follow the Requirements and Installationsections of the library guide.
  2. Open up your preferred text editor and start writing Python code.
  3. vim numbers-test.py
                
  4. Import the following required libraries.
  5. import pprint
    import os
    import json
    from flowroutenumbersandmessaging.flowroutenumbersandmessaging_client import FlowroutenumbersandmessagingClient
    
                
  6. Assign your Flowroute accessKey and secretKey to the following variables or set them as environment variables.
  7. 
    basic_auth_user_name = "YOUR_FR_ACCESS_KEY"
    basic_auth_password = "YOUR_FR_SECRET_KEY"
    
                        
  8. Next, instantiate the API Client and its controllers.
  9. client = FlowroutenumbersandmessagingClient(basic_auth_user_name, basic_auth_password)
    numbers_controller = client.numbers
    
                        
  10. Lastly, specify your query parameters and invoke the Python library v3 search method.
  11. print("--Search for Purchasable Phone Numbers")
    starts_with = 347
    contains = 666
    limit = 3
    result = numbers_controller.search_for_purchasable_phone_numbers(starts_with, contains, limit, offset)
    pprint.pprint(result)
    
                        
  12. You're done coding, at least for the search portion of this tutorial. Save the file and run it.
  13. python numbers-test.py
                

Flowroute API Search Response

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. Make a note of the id of your favorite number in the JSON response. You will need that to purchase your phone number.

Sadly, the Flowroute API only found one available phone number which contains 666, and my favorite NYC area code, 347.

{
  "data": [
    {
      "attributes": {
        "monthly_cost": 1.25,
        "number_type": "standard",
        "rate_center": "nwyrcyzn06",
        "setup_cost": 3.99,
        "state": "ny",
        "value": "13474165666"
      },
      "id": "13474165666",
      "links": {
        "related": "https://api.flowroute.com/v2/numbers/13474165666"
      },
      "type": "number"
    }
  ],
  "links": {
    "self": "https://api.flowroute.com/v2/numbers/available?contains=666&starts_with=1347&limit=3&offset=0"
  }
}

            

Phone Number Purchase

Request via cURL

  1. Copy the following example POST request.
  2. curl -X POST https://api.flowroute.com/v2/numbers/13474165666 -u accessKey:secretKey
    
                        
  3. Replace accessKey:secretKey with your API credentials.
  4. In the path parameter section of your cURL request right after numbers, https://api.flowroute.com/v2/numbers, replace the example phone number with the id of the phone number that you want to purchase.
  5. Press Enter.