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?

This guide assumes that you have an activated Flowroute account and have followed the instructions on Purchase Your First Flowroute Phone Number.


Create an inbound voice route

To assign a primary or a failover inbound voice route to a phone number, you must create a record for the inbound route first. There are four voice route types: host, number, uri, or sip-reg all in lowercase. sip-reg is the default primary route type assigned to a Flowroute phone number upon purchase. For details around valid values according to route type, see body parameters section of "Create an Inbound Route".

The Flowroute API v2 provides an alternative programmatic way for you to create a new inbound voice route. For the Manage method of creating an inbound route, visit Inbound Routes > Add New Route.

In this tutorial, we will show you two methods of creating a new inbound route and assigning that route as a primary or a failover voice route to a phone number using the Flowroute API v2:

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 POST request.
  4. curl https://api.flowroute.com/v2/routes \
    -X POST -u accessKey:secretKey \
    -d '{"data": {"type":"route", "attributes": {"route_type": "host", "value": "www.getouttahere.com", "alias":"new_route_5000"}}}' \ 
    -H 'Content-Type':'application/vnd+api.json'
  5. Replace accessKey:secretKey with your API credentials.
  6. In the JSON body parameters section of your cURL request right after the cURL -d flag, , make the following substitutions:
    • Replace route_type with your preferred route type. You can choose between host, uri, number, and sip-reg.
    • Replace value with the appropriate value according to your route type.
    • Replace alias with a unique alias for your new route.
  7. Press Enter.


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 Python

  1. To begin, follow the Requirements and Installation sections of the library guide.
  2. Open up your preferred text editor and start writing Python code.
  3. vim routes-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.
    basic_auth_user_name = "YOUR_FR_ACCESS_KEY"
    basic_auth_password = "YOUR_FR_SECRET_KEY"
  8. Next, instantiate the API Client and the routes controllers.
  9. client = FlowroutenumbersandmessagingClient(basic_auth_user_name, basic_auth_password)
    routes_controller = client.routes
  10. Lastly, specify your body parameters and invoke the Python library v3 search method.
  11. print("--Create an Inbound Route")
    request_body = '{ \
      "data": { \
        "type": "route", \
        "attributes": { \
          "route_type": "host", \
          "value": "www.getouttahere.com", \
          "alias": "new_route_5000" \
        } \
      } \
    result = routes_controller.create_an_inbound_route(request_body)
  12. You're done coding, at least for the inbound route creation portion of this tutorial. Save the file and run it.
  13. python routes-test.py

Flowroute API Create an Inbound Route Response

On success, the HTTP status code in the response header is 201 CREATED and the response body contains the newly created route object in JSON format. Make a note of the id of the inbound route in the JSON response. You will need that for the next portion.

  "data": {
    "attributes": {
      "alias": "new_route_5000",
      "route_type": "host",
      "value": "www.getouttahere.com"
    "id": "98396",
    "links": {
      "self": "https://api.flowroute.com/routes/98396"
    "type": "route"
  "links": {
    "self": "https://api.flowroute.com/routes/98396"


Set up an inbound voice route for your phone number

You may assign inbound routes that you have created as a primary or a failover voice route to any Flowroute number that you own.

Request via cURL

  1. To assign your newly created inbound route as a voice route to your Flowroute phone number, copy the following example PATCH request.
  2. Primary Voice Route

    curl https://api.flowroute.com/v2/numbers/13474165666/relationships/primary_route -X PATCH -u accessKey:secretKey -H 'Content-Type':'application/vnd.api+json' -d '{ "data": { "type":"route", "id":"98396" } }' 

    Failover Voice Route

    curl https://api.flowroute.com/v2/numbers/13474165666/relationships/failover_route -X PATCH -u accessKey:secretKey -H 'Content-Type':'application/vnd.api+json' -d '{ "data": { "type":"route", "id":"98396" } }' 
  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 associate with your inbound route.
  5. In the JSON body parameters section of your cURL request right after the cURL -d flag, replace id with the ID of your inbound route.
  6. Press Enter.