Python API Wrapper


The Flowroute Python API Wrapper provides methods for interacting with Number Management v1 and Messaging v2 of the Flowroute API.

Topics


Numbers SDK (v1)

View Repo

Requirements

Installation

First, clone the SDK.

git clone https://github.com/flowroute/flowroute-numbers-python.git 

            

Switch to the newly-created flowroute-numbers-python directory. The Numbers Python SDK comes with a requirements file listing the required Python libraries. Click here to learn more about different ways to install Python packages.

pip install -r requirements.txt

            

Usage

In Flowroute's approach to building the Numbers (v1) API wrapper, HTTP requests are handled by controllers, which contain the methods used to perform tasks with the Python SDK.

Controllers

  • PurchasablePhoneNumbersController

    Contains all of the methods necessary to search through Flowroute's phone number inventory.

  • TelephoneNumbersController

    Contains all of the methods necessary to purchase a new phone number and manage your owned phone number inventory.

  • InboundRoutesController

    Contains the methods required to create new routes and view your current routes.

    • list() - List existing inbound routes from your account
    • create_new_route() - Create a new inbound route that can then be assigned as either a primary or failover route for a phone number

The following shows an example of a single Python file that imports and instantiates all three Controllers. The Python SDK comes with a demo.py file as an example.

from FlowrouteNumbersLib.Controllers.InboundRoutesController import *
from FlowrouteNumbersLib.Controllers.PurchasablePhoneNumbersController import *
from FlowrouteNumbersLib.Controllers.TelephoneNumbersController import *
from FlowrouteNumbersLib.Models import *

pnc = PurchasablePhoneNumbersController()
tnc = TelephoneNumbersController()
irc = InboundRoutesController()

            

Credentials

In demo.py, replace Access Key and Secret Key with your API credentials from the Flowroute Manager.

#Pass your API credentials
Configuration.username="Access Key"
Configuration.password="Secret Key"

            

Methods

list_available_np_as()

The method accepts the limit and page parameters which you can learn more about in the API reference. The following example limits the number of NPAs returned to 2:

#List Available NPAs
response = pnc.list_available_np_as(limit=2)

            
Example Response
{
 "npas": {
   "201": {
     "nxxs": "/v1/available-tns/npanxxs/?npa=201",
    "tns": "/v1/available-tns/tns/?npa=201"
   },
   "202": {
      "nxxs": "/v1/available-tns/npanxxs/?npa=202",
      "tns": "/v1/available-tns/tns/?npa=202"
    }
  },
  "links": {
  "next": "/v1/available-tns/npas/?limit=2&page=2"
  }
}
            
            
list_area_and_exchange()

The method accepts the limit, npa, and page parameters which you can learn more about in the API reference. The following example sets the limit to 2, the npa to 206, and the display page to 2:

#List NPA and NXX
response = pnc.list_area_and_exchange(limit=2, npa=206,page=2)

            
Example Response

Results are returned in numerical order, starting with the lowest NPA number. The npaxxs parameter variable is formatted as a combination of the NPA and NXX. In the following example, 206258 is the combination of NPA 206 and NXX 258.

{
"npanxxs": {
  "206258": {
    "tns": "/v1/available-tns/tns/?npa=206&nxx=258"
   },
   "206238": {
     "tns": "/v1/available-tns/tns/?npa=206&nxx=238"
    }
  },
  "links": {
    "prev": "/v1/available-tns/npanxxs/?npa=206&limit=2&page=1",
    "next": "/v1/available-tns/npanxxs/?npa=206&limit=2&page=3"
 }
}
            
            
search()

The search() method is the most robust option for searching through Flowroute's purchasable phone number inventory. It allows you to search by NPA, NXX, Ratecenter, State, and/or TN (telephone number). The method accepts the limit, npa, nxx, and page parameters which you can learn more about in the API reference.

In the following example, a search request sets the limit to 1, the npa to 206, the nxx to 743, to display page 2, the ratecenter to "seattle", the state to "wa", and the tn to None.

#Search
response = pnc.search(limit=1,npa=206,nxx=743,page=1,ratecenter='seattle',state='wa',tn=None)

            
Example Response
{
"links": {
  "next": "/v1/available-tns/tns/?npa=206&nxx=743&state=wa&ratecenter=seattle&limit=1&page=2"
 },
 "tns": {
    "12067439178": {
     "initial_cost": "1.00",
     "monthly_cost": "1.25",
    "state": "WA",
    "ratecenter": "SEATTLE",
    "billing_methods": [
     "METERED"
   ]
   }
     }
}
            
            
purchase()

The purchase() method is used to purchase a telephone number from Flowroute's inventory. The method accepts the billing_method (within the BillingMethod object) and telephone_number parameters which you can learn more about in the API reference.

#Purchase a Telephone Number
billing = BillingMethod(billing_method="METERED")
number = "15852003968"
response = tnc.purchase(billing,number)

            
Example Response

For a successful purchase, the API returns an empty line. No other success message is displayed.

201 Created
{ }
            
            
list_account_telephone_numbers()

The method accepts the limit, page, and pattern parameters which you can learn more about in the API reference. The following example sets the limit to 5, the page to 2, and the search pattern to 206:

#List Account Telephone Numbers
response = tnc.list_account_telephone_numbers(limit=5,page=2,pattern=206)

            
Example Response
{
  "links": {
    "prev": "/v1/tns/?limit=1&page=1",
    "next": "/v1/tns/?limit=1&page=3"
 },
  "tns": {
    "12062092844": {
      "routes": [
     {
       "type": "SIP-REG",
       "name": "sip-reg"
     },
     {
       "type": "SIP-REG",
       "name": "sip-reg"
     }
   ],
   "billing_method": "METERED",
   "detail": "/v1/tns/16476998778"
 }
}
}
            
            
telephone_number_details()

The method accepts the telephone_number parameter which you can learn more about in the API reference. In the following example, details are requested for the telephone number just purchased using the purchase method.

#Telephone Number Details
response = tnc.telephone_number_details(16476998778)

            
Example Response
{
 "routes": [
  {
     "type": "SIP-REG",
     "name": "sip-reg"
   },
    {
     "type": "SIP-REG",
     "name": "sip-reg"
   }
 ],
  "billing_method": "METERED"
}
            
            

update()

The method accepts the routes and telephone_number parameters which you can learn more about in the API reference.

#Update Telephone Number Routes
rtes = [Route(name='sip-reg'), Route(name='ea4f4056663e27b082999689982e4723')]
response = tnc.update(number=16476998778, routes=rtes)

            
Example Response

An empty line is returned for a successful update. No other message is returned. You can verify that the routes were changed by calling the list method.

204 No Content
' '
            
            
list()

The method accepts the limit, page, and pattern parameters which you can learn more about in the API reference.

#List Routes
response = irc.list(limit=4, page=None)

            
Example Response
{
routes:
 {
   HOSTroute1:
        {
            type: HOST
            value => 24.239.23.40:5060
        }
   PSTNroute1:
        {
            type: PSTN
            value: 178
        }
    URIroute1:
        {
            type: URI
            value: sip:16476998778@215.122.69.152:5060
        }
    sip-reg:
        {
            type: SIP-REG
            value: sip-reg
        }
 }
}
            
            
create_new_route()

The method accepts the route_name, mtype, and value parameters which you can learn more about in the API reference. The following example shows the creation of three new routes:

#Create New Routes
response = irc.create_new_route(route_name='PSTNroute1',mtype='PSTN',value='16476998778')
response = irc.create_new_route(route_name='HOSTroute1',mtype='HOST',value='24.239.23.40:5060')
response = irc.create_new_route(route_name='URIroute1',mtype='URI',value='sip:16476998778@215.122.69.152:5060')

            
Example Response

An empty string ('') is returned for each successfully created route; no other code or message is returned. An error encountered for a specific irc.create_new_route() line does not prevent the other routes from being created.

201 Created
' '
            
            

Messaging SDK (v2)

View Repo

The Python Messaging SDK additionally requires the pprint library version 0.1 or higher.

Usage

In Flowroute's approach to building the Messaging (v2) API wrapper, HTTP requests are handled by the APIController, which contains the functions used to perform tasks with the Python SDK.

APIController

The following shows how you can import and instantiate the APIController:

#Import the Controllers
from FlowrouteMessagingLib.Models.Message import Message
from FlowrouteMessagingLib.Controllers.APIController import APIController  

#Pass your API credentials
controller = APIController(username="API_ACCESS_KEY", password="API_SECRET_KEY")

            

Credentials

In your Python file, replace API_ACCESS_KEY and API_SECRET_KEY with your API credentials from the Flowroute Manager.


#Pass your API credentials
controller = APIController(username="API_ACCESS_KEY", password="API_SECRET_KEY")

            

Methods

create_message()

The method accepts the msg, to, from, and body parameters which you can learn more about in the API reference.

#Create and Send a Message
msg = Message(to="15305557784", from_="18444205700", content="Gee, nice marmot!")
response = controller.create_message(msg)

            
Example Response
{
"data": {
    "id": "mdr1-fab29a740129404a8ca794efc1359e12'
    }
}

            
get_message_lookup()

The method accepts the record_id parameter which you can learn more about in the API reference.

# Look up the MDR
response = controller.get_message_lookup("mdr1-fab29a740129404a8ca794efc1359e12")

            
Example Response
{
"data": {
  "attributes": {
      "body": "Gee, nice marmot!",
      "direction": "outbound",
      "amount_nanodollars": 4000000,
      "message_encoding": 0,
      "timestamp": "2016-05-03T17:41:00.478893+00:00",
      "has_mms": false,
      "to": "15305557784",
      "amount_display": "$0.0040",
      "from": "18444205700",
      "callback_url": None,
      "message_type": "long-code"
                },
  "type": "message",
  "id": "mdr1-cfab29a740129404a8ca794efc1359e12"
         }
}