1. Understand & set up authentication with the Flowroute API.

Flowroute's API utilizes a custom authentication procedure that ensures a unique non-repeatable password is used to authenticate every API request. Authentication to the Flowroute API requires you to have your API Access Key and API Secret Key. See Authentication & Security for more information.

Key

Location

Access Key Go to Preferences > API Control on Flowroute Manage.
Secret Key Go to Preferences > API Control on Flowroute Manage.

Once you obtain the Access Key and Secret Key, set them in your code as follows:

Python
  
access_key = 12345678 # example   
secret_key = 594d7111c8916b1d94e5f189536ed971 # example
 
            

Generate your HTTP Basic Password for auth

In order to send a request to the API, you must use HTTP Basic Authentication. For the username you will need to supply your Access Key. For the password you will need to generate a signature based on the following password formula:

hex(hmac_sha1(API_secret_key, message_string))

See Authentication & Security for more information about password generation.

After adding the Access Key and Password to your code,

  1. Prep the message_string
  2. Generate the HTTP Basic Auth Password.
  3. Make the request.

Message string overview

The message string is a sequence of tokens separated by newline characters \n in a single string.

{{timestamp}}\n{{HTTP method}}\n{{md5(request body)}}\n{{canonical request-uri}}\n

The specifics of generating the MD5 hash of the body along with the Canonical Request-URI are not covered in this article, 
but can be found on the Authentication & Security page.

Steps

The following describe the steps required to send your first request. These steps require that you gather several pieces of data and assemble into a complete file.

a. Prepare the X-Timestamp header
Python
import datetime as dt

t = dt.datetime.utcnow().replace(microsecond=0)
timestamp = t.isoformat()
headers = {'X-Timestamp': timestamp}

            
b. Prepare the HTTP method
Python
method = 'GET'
            
c. Prepare the MD5 hash of the request body
Python
import hashlib
body_md5 = hashlib.md5(body).hexdigest() if body != '' else ''

            
d. Prepare the Canonical Request URI
Python
query_params = [] # Since this is a simple request, we won't set any query paramsquery_params.sort()
url_scheme = 'https'
net_location = 'api.flowroute.com'
method = 'GET'
path = '/v1/available-tns/tns/'
ordered_query_params = u'&'.join(query_params)
canonical_uri = '{0}://{1}{2}\n{3}'.format(url_scheme, net_location, path, ordered_query_params)

            
e. Combine and define the message string
Python
tokens = (timestamp, method, body_md5, canonical_uri)message_string = u'\n'.join(tokens).encode('utf-8')

            
f. Generate the password signature
Python
signature = hmac.new(secret_key, message_string, digestmod=hashlib.sha1).hexdigest()
            
g. Combine and define the password signature
Python
request_url = '{0}://{1}{2}?{3}'.format(url_scheme, net_location, path, ordered_query_params)
            

2. View available phone numbers for purchase

Generate the request URL.

Before making the API request, generate the request URL:

request_url = '{0}://{1}{2}?{3}'.format(url_scheme, net_location, path, ordered_query_params)  # append ordered query params hererequest = requests.get(request_url, auth=(access_key, signature), headers=headers)
result = json.loads(request.text)
print "Server Response: " + str(request.status_code)

            

3. Collect the information and run the script

Collect all of the information performed from all steps in Understand & set up authentication with the Flowroute API and View available telephone numbers for purchase into one file:

import requests
import hmac
import hashlib
import datetime as dt
import simplejson as json

#Get your credentials
access_key = 12345678 #example
secret_key = 594d7111c8916b1d94e5f189536ed971 #example

#Prepare the X-Timestamp header
t = dt.datetime.utcnow().replace(microsecond=0)
timestamp = t.isoformat()
headers = {'X-Timestamp': timestamp}

#Prepare the MD5 hash of the request body
body = ''
body_md5 = hashlib.md5(body).hexdigest() if body != '' else ''

#Prepare the HTTP method
method = 'GET'

# Prepare the Canonical Request URI
query_params = [] #Since this is a simple request, we won't set any query params
query_params.sort()
url_scheme = 'https'
net_location = 'api.flowroute.com'
path = '/v1/available-tns/tns/'
ordered_query_params = u'&'.join(query_params)
canonical_uri = '{0}://{1}{2}\n{3}'.format(url_scheme, net_location, path, ordered_query_params)

#Combine and define the message string
tokens = (timestamp, method, body_md5, canonical_uri)
message_string = u'\n'.join(tokens).encode('utf-8')

#Generate the password signature
signature = hmac.new(secret_key, message_string, digestmod=hashlib.sha1).hexdigest()

#Make the request
request_url = '{0}://{1}{2}?{3}'.format(url_scheme, net_location, path, ordered_query_params)  #append ordered query params here
request = requests.get(request_url, auth=(access_key, signature), headers=headers)
result = json.loads(request.text)
print "Server Response: " + str(request.status_code)

        

Once you run this script, you should receive a successful response similar to the following. This indicates that you have successfully sent your first request.

{  "tns": {
    "15065010058": {
      "initial_cost": "3.99",
      "monthly_cost": "1.25",
      "billing_methods": [
        "METERED"
      ],
      "ratecenter": "Edmundston",
      "state": "NB"
    },
    "15065010064": {
      "initial_cost": "3.99",
      "monthly_cost": "1.25",
      "billing_methods": [
        "METERED"
      ],
      "ratecenter": "Edmundston",
      "state": "NB"
    },
    "15065010061": {
      "initial_cost": "3.99",
      "monthly_cost": "1.25",
      "billing_methods": [
        "METERED"
      ],
      "ratecenter": "Edmundston",
      "state": "NB"
    },
    
    ...
    
  "links": {
    "next": "/v1/available-tns/tns/?limit=10&page=2"
  }
}