The Flowroute Python Library v3 provides methods for interacting with [Numbers v2](https://developer.flowroute.com/api/numbers/v2.0/) &endash; which includes inbound voice routes, E911 addresses, CNAM storage &endash;and [Messages v2.1](https://developer.flowroute.com/api/messages/v2.1/) and [CDR v2.0](https://developer.flowroute.com/api/cdrs/v2.0/) of the [Flowroute](https://www.flowroute.com) API.
The Flowroute Python Library v3 provides methods for interacting with [Numbers v2](https://developer.flowroute.com/api/numbers/v2.0/) and [Messages v2.1](https://developer.flowroute.com/api/messages/v2.1/) of the [Flowroute](https://www.flowroute.com) API.
**Topics**
@ -54,12 +54,10 @@ The Flowroute Python Library v3 provides methods for interacting with [Numbers v
@ -93,7 +91,7 @@ Depending on your `pip` permissions, you may be required to preface each `pip` c
* * *
Usage
------------
In Flowroute's approach to building the Python Library v3, HTTP requests are handled by controllers named after the API resources they represent: **Numbers**, **Routes**, **E911s**, **CNAMs**, and **Messages**. These controllers contain the methods used to perform messaging, number management, route management, E911 address management, and CNAM record management within the Python library.
In Flowroute's approach to building the Python Library v3, HTTP requests are handled by controllers named after the API resources they represent: **Numbers**, **Routes**, **E911s**, **CNAMs**, and **Messages**. These controllers contain the methods used to perform messaging, number management, route management, E911 address management, and CNAM record management within the Python library.
## Controllers
@ -144,22 +142,11 @@ Contains all of the methods necessary to create, update, and validate new and ex
Contains all of the methods necessary to create and delete CNAM records, view all of the CNAM records associated with your account, filter for specific CNAM records by status, review CNAM record details, and assign and unassign CNAM records to your Flowroute long code phone numbers.
* [list\_cnams()](#list_cnams) \- Returns a list of all CNAM records on your account by default. You can apply search filters using any of the available query parameters.
* [get\_cnam(cnam\_id)](#get_cnamcnam_id) \- Returns details pertaining to a specific CNAM record on your account, including long code numbers that are associated with the record.
* [create\_cnam\_record(cnam\_value)](#create_cnam_recordcnam_value) \- Lets you create a Caller ID record for your account which can then be assigned to any of your long code numbers. To assign a CNAM record to your number, see the [associate\_cnam](#associate_cnamcnam_id-number_id) method.
* [create\_cnam\_record(cnam\_value)](#create_cnam_recordcnam_value) \- Lets you create a Caller ID record for your account which can then be assigned to any of your long code numbers. To assign a CNAM record to your number, see the [associate\_cnam](#associate_cnam) method.
* [associate\_cnam(cnam\_id, number\_id)](#associate_cnamcnam_id-number_id) \- Lets you associate a CNAM record with a specified long code number on your account. Note that a CNAM record takes 1-2 days to be approved.
* [unassociate(number\_id)](#unassociate_cnamnumber_id) \- Lets you unassign a CNAM record associated with a specified long code number on your account without deleting the CNAM record itself.
* [remove\_cnam(cnam\_id)](#remove_cnamcnam_id) \- Lets you delete a CNAM record from your account. Note that this will automatically disassociate all numbers associated with the deleted CNAM record.
### CDRsController
Contains all of the methods necessary to create and retrieve CDR exports.
* [list\_cdr\_exports](#list_cdr_exports) \- Returns a list of all CDR Exports that have been created on your account.
* [create\_cdr\_export](#create_cdr_export) \- Create a CDR Export with a list of filter parameters. When this asynchronous job is done running,
Flowroute's servers will post to a callback URL if one is provided.
* [get\_cdr\_export\_status(cdr\_export\_id)](#get_cdr_export_status) \- Returns details pertaining to a specific CDR Export, including the download_url that
is required to retrieve the CDR Export data.
* [download\_cdr\_export(cdr\_export\_id)](#download_cdr_export) \- Downloads the CDR Export CSV file or GZIPPED CSV file from the Flowroute servers.
The following shows an example of a single Python file that imports the Flowroute API client and all the required modules. The Python Library v3 comes with three example demo files —**number_route_message_demo.py**, **e911_demo.py**, **cnam_demo.py**— files that you can edit and run for demonstration and testing purposes.
```python
@ -909,9 +896,13 @@ The Flowroute Python Library v3 allows you to make HTTP requests to the `e911s`
All of the E911 address management methods are encapsulated in `e911_demo.py`.
| API Reference Pages |
| ------------------- |
| The E911 and CNAM API reference pages are currently restricted to our beta customers, which means that all API reference links below currently return a `404 Not Found`. They will be publicly available during our E911 and CNAM APIs GA launch in a few weeks. |
#### list\_e911s()
The method accepts `limit`, `offset`, and `state` as parameters which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/list-account-e911-addresses/).
The method accepts `limit`, `offset`, and `state` as parameters which you can learn more about in the [API reference](https://developer.flowroute.com/api/e911s/v2.0/list-account-e911-addresses/).
##### Example Request
```python
@ -960,9 +951,9 @@ On success, the HTTP status code in the response header is `200 OK` and the resp
The method accepts an `e911_id` as a path parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/list-e911-record-details/).
The method accepts an `e911_id` as a path parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/e911s/v2.0/list-e911-record-details/).
##### Example Request
```python
@ -984,33 +975,25 @@ On success, the HTTP status code in the response header is `200 OK` and the resp
The method accepts the different attributes of an E911 address as parameters: `label`, `first_name`, `last_name`, `street_name`, `street_number`, optional `address_type` and `address_type_number`, `city`, `state`, `country`, and `zipcode`. Learn more about the different E911 attributes in the [API reference](https://developer.flowroute.com/api/e911s/v2.0/validate-e911-address/).
The method accepts the different attributes of an E911 address as parameters: `label`, `first_name`, `last_name`, `street_name`, `street_number`, `city`, `state`, `country`, and `zipcode`. Learn more about the different E911 attributes in the [API reference](https://developer.flowroute.com/api/e911s/v2.0/validate-e911-address/). Note that this method doesn't accept the `address_type` and `address_type_number` which are acceptable but not required E911 address attributes by the API.
##### Example Request
```
@ -1042,7 +1025,7 @@ HTTP response not OK.
```
#### create_address(e911_attributes)
The method accepts the different attributes of an E911 address as parameters: `label`, `first_name`, `last_name`, `street_name`, `street_number`, optional `address_type` and `address_type_number`, `city`, `state`, `country`, and `zipcode`. Learn more about the different E911 attributes in the [API reference](https://developer.flowroute.com/api/e911s/v2.0/create-and-validate-new-e911-address/).
The method accepts the different attributes of an E911 address as parameters: `label`, `first_name`, `last_name`, `street_name`, `street_number`, `city`, `state`, `country`, and `zipcode`. Learn more about the different E911 attributes in the [API reference](https://developer.flowroute.com/api/e911s/v2.0/create-and-validate-new-e911-address/). Note that this method doesn't accept the `address_type` and `address_type\_number` which are acceptable but not required E911 address attributes by the API.
##### Example Request
```
@ -1085,7 +1068,7 @@ On success, the HTTP status code in the response header is `201 Created` and the
```
#### update_address(e911_id, e911_attributes)
The method accepts an E911 record id and the different attributes of an E911 address as parameters: `label`, `first_name`, `last_name`, `street_name`, `street_number`, optional `address_type` and `address_type_number`, `city`, `state`, `country`, and `zipcode`. Learn more about the different E911 attributes that you can update in the [API reference](https://developer.flowroute.com/api/e911s/v2.0/update-and-validate-existing-e911-address/). In the following example, we will retrieve the record ID of our newly created E911 address and assign it to a variable, `record_id`. We then update the `last_name` of our selected E911 address to "Wiley".
The method accepts an E911 record id and the different attributes of an E911 address as parameters: `label`, `first_name`, `last_name`, `street_name`, `street_number`, `city`, `state`, `country`, and `zipcode`. Learn more about the different E911 attributes that you can update in the [API reference](https://developer.flowroute.com/api/e911s/v2.0/update-and-validate-existing-e911-address/). Note that this method doesn't accept the `address_type` and `address_type_number` which are acceptable but not required E911 address attributes by the API. In the following example, we will retrieve the record ID of our newly created E911 address and assign it to a variable, `record_id`. We then update the `last_name` of our selected E911 address to "Wiley".
##### Example Request
```
@ -1122,7 +1105,7 @@ On success, the HTTP status code in the response header is `200 OK` and the resp
```
#### associate(e911_id, number_id)
The method accepts an E911 record id and a phone number as parameters which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/assign-valid-e911-address-to-phone-number/). In the following example, we call the [list_account_phone_numbers](#list_account_phone_numbers) covered under Number Management and [list_e911s](#list_e911s), extract the values of the first items in the returned JSON arrays into variables `e911_id` and `did` then make the association between them.
The method accepts an E911 record id and a phone number as parameters which you can learn more about in the [API reference](https://developer.flowroute.com/api/e911s/v2.0/assign-valid-e911-address-to-phone-number/). In the following example, we call the [list_account_phone_numbers](#list_account_phone_numbers) covered under Number Management and [list_e911s](#list_e911s), extract the values of the first items in the returned JSON arrays into variables `e911_id` and `did` then make the association between them.
##### Example Request
```
@ -1147,14 +1130,11 @@ except Exception as e:
On success, the HTTP status code in the response header is `204 No Content` which means that the server successfully processed the request and is not returning any content.
```
--Associate an E911 Record and a DID
204: No Content
```
`204: No Content`
#### list_dids_for_e911(e911_id)
The method accepts an E911 record id as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/list-phone-numbers-associated-with-e911-record/). In the following example, we retrieve the list of phone numbers associated with our previously assigned `e911_id`.
The method accepts an E911 record id as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/e911s/v2.0/list-phone-numbers-associated-with-e911-record/). In the following example, we retrieve the list of phone numbers associated with our previously assigned `e911_id`.
##### Example Request
```
@ -1188,7 +1168,7 @@ On success, the HTTP status code in the response header is `200 OK` and the resp
#### disconnect(number_id)
The method accepts a phone number as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/deactivate-e911-service-for-phone-number/). In the following example, we deactivate the E911 service for our previously assigned `did`.
The method accepts a phone number as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/e911s/v2.0/deactivate-e911-service-for-phone-number/). In the following example, we deactivate the E911 service for our previously assigned `did`.
##### Example Request
```
@ -1210,7 +1190,7 @@ On success, the HTTP status code in the response header is `204 No Content` whic
```
#### delete_address(e911_id)
The method accepts an E911 record ID as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/remove-e911-address-from-account/). Note that all phone number associations must be removed first before you are able to delete the specified `e911_id`. In the following example, we will attempt to delete the previously assigned `e911_id`.
The method accepts an E911 record ID as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/e911s/v2.0/remove-e911-address-from-account/). Note that all phone number associations must be removed first before you are able to delete the specified `e911_id`. In the following example, we will attempt to delete the previously assigned `e911_id`.
##### Example Request
```
@ -1235,9 +1215,13 @@ The Flowroute Python Library v3 allows you to make HTTP requests to the `cnams`
All of the CNAM record management methods are encapsulated in `cnam_demo.py`.
| API Reference Pages |
| ------------------- |
| The E911 and CNAM API reference pages are currently restricted to our beta customers, which means that all API reference links below currently return a `404 Not Found`. They will be publicly available during our E911 and CNAM APIs GA launch in a few weeks. |
#### list\_cnams()
The method accepts `limit`, `offset`, and `is_approved` as parameters which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/list-account-cnam-records/).
The method accepts `limit`, `offset`, and `is_approved` as parameters which you can learn more about in the [API reference](https://developer.flowroute.com/api/cnams/v2.0/list-account-cnam-records/).
##### Example Request
```python
@ -1316,7 +1300,7 @@ On success, the HTTP status code in the response header is `200 OK` and the resp
```
#### get_cnam(cnam_id)
The method accepts a CNAM record ID as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/list-cnam-record-details/). In the following example, we query for approved CNAM records on your account and then extract the ID of the first record returned and retrieve the details of that specific CNAM record.
The method accepts a CNAM record ID as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/cnams/v2.0/list-cnam-record-details/). In the following example, we query for approved CNAM records on your account and then extract the ID of the first record returned and retrieve the details of that specific CNAM record.
##### Example Request
```
@ -1346,17 +1330,7 @@ On success, the HTTP status code in the response header is `200 OK` and the resp
```
#### create_cnam_record(cnam_value)
The method accepts a Caller ID value as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/create-a-new-cnam-record/). In the following example, we reuse the `random_generator()` function to generate a four-character random string which we will concatenate with FR and assign as our CNAM value.
| CNAM Storage Rules |
| ------------------- |
| You can enter up to 15 characters for your CNAM value at least one of which is a letter. |
| While most CNAM presets can be approved, the following are not allowed and must be rejected: |
| - Consist of curse words and/or is inappropriate. |
| - A phone number (CNAM must be a name not a number) |
| - If the CNAM preset which the customer has submitted appears to be misleading such as: |
| - Political Figures or Places (Obama, Barack or The White House) |
| - False or fake CNAM (Seattle Police) |
The method accepts a Caller ID value as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/cnams/v2.0/create-a-new-cnam-record/). In the following example, we reuse the `random_generator()` function to generate a four-character random string which we will concatenate with FR and assign as our CNAM value.
##### Example Request
```
@ -1373,7 +1347,7 @@ print("\nNOTE: Newly created CNAM records need to be approved first before they
##### Example Response
On success, the HTTP status code in the response header is `201 Created` and the response body contains the newly created cnam object in JSON format. Note that CNAM records take up to 48 hours to be approved on your account and further association with a phone number takes 5-7 business days.
On success, the HTTP status code in the response header is `201 Created` and the response body contains the newly created cnam object in JSON format.
```
--Create a CNAM Record
@ -1391,7 +1365,7 @@ NOTE: Newly created CNAM records need to be approved first before they can be as
```
#### associate_cnam(cnam_id, number_id)
The method accepts a CNAM record ID and a phone number as parameters which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/assign-cnam-record-to-phone-number/). In the following example, we will call `list_account_phone_numbers()` and associate the first number in the returned array with our previously assigned `cnam_id`.
The method accepts a CNAM record ID and a phone number as parameters which you can learn more about in the [API reference](https://developer.flowroute.com/api/cnams/v2.0/assign-cnam-record-to-phone-number/). In the following example, we will call `list_account_phone_numbers()` and associate the first number in the returned array with our previously assigned `cnam_id`.
##### Example Request
```
@ -1417,7 +1391,7 @@ On success, the HTTP status code in the response header is `202 Accepted` and th
```
#### unassociate_cnam(number_id)
The method accepts a phone number as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/unassign-a-cnam-record-from-phone-number/). In the following example, we will disassociate the same phone number that we've used in `associate_cnam()`.
The method accepts a phone number as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/cnams/v2.0/unassign-a-cnam-record-from-phone-number/). In the following example, we will disassociate the same phone number that we've used in `associate_cnam()`.
##### Example Request
```
@ -1437,7 +1411,7 @@ On success, the HTTP status code in the response header is `202 Accepted` and th
```
#### remove_cnam(cnam_id)
The method accepts a CNAM record ID as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/remove-cnam-record-from-account/). In the following example, we will be deleting our previously extracted `cnam_id` from the "List Approved CNAM Records" function call.
The method accepts a CNAM record ID as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/cnams/v2.0/remove-cnam-record-from-account/). In the following example, we will be deleting our previously extracted `cnam_id` from the "List Approved CNAM Records" function call.
##### Example Request
```
@ -1454,239 +1428,6 @@ On success, the HTTP status code in the response header is `204 No Content` whic
''
```
### Call Detail Record Export API
The Flowroute Python Library v3 allows you to make HTTP requests to the `cdrs` resource of Flowroute API v2: `https://api.flowroute.com/v2/cdrs`.
All of the CDR export methods are encapsulated in `cdr_demo.py`.
#### list_cdr_exports
The method accepts `status`, `limit`, and `offset` as parameters which you can learn more about in the [API reference](https://developer.flowroute.com/api/cdrexports/v2.0/list-cdrs/).
##### Example Request
```python
print("--List Completed CDR Exports")
status = 'completed'
limit = 10
offset = None
result = cdrs_controller.list_cdr_exports(status, limit, offset)
pprint.pprint(result)
```
##### Example Response
On success, the HTTP status code in the response header is `200 OK` and the response body contains an array of CDR Export objects in JSON format.
The method accepts a many query parameters, such as `start_call_start_time`, `start_call_end_time`, and `number_aliases`. Learn more about the different CDR export filter parameters in the [API reference](https://developer.flowroute.com/api/cdrexports/v2.0/query-cdrs/).
##### Example Request
```
print("\n--Create a CDR Export where the call started between a certain time from a list of number alises")
try:
filters = {
"start_call_start_time": "2019-01-01 00:00:00",
"start_call_end_time": "2019-02-01 00:00:00",
"number_aliases": ["Office 221", "Office 888"]
}
callback_url = "https://myserver.com/cdrs"
result = cdrs_controller.create_cdr(filters, callback_url)
pprint.pprint(result)
except Exception as e:
print(str(e))
print(e.context.response.raw_body)
```
##### Example Response
On success, the HTTP status code in the response header is `201 Created` and the response body contains the newly created CDR export object in JSON format. On error, a printable representation of the detailed API response is displayed.
The method accepts a CDR Export ID as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/cdrexports/v2.0/cdr-status/). In the following example, we will be retrieving the Detail Status of the CDR Export we created in the previous query.
##### Example Request
```
print("\n--Get CDR Export Detail Status")
result = cdrs_controller.get_cdr_export_status(cdrexport_id)
pprint.pprint(result)
```
##### Example Response
On success, the HTTP status code in the response header is `200 OK` and the response body contains a CDR export JSON object.
The method accepts a CDR Export ID as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/cdrexports/v2.0/cdr-status/). In the following example, we will be retrieving the file of the CDR Export we created in the previous query.
You can learn more about the format of the CDR Export Data in the [API results reference](https://developer.flowroute.com/api/cdrexports/v2.0/cdr-results/).
##### Example Request
```
print("\n--Get CDR Export Data")
result = cdrs_controller.download_cdr_export(cdrexport_id, filename)
pprint.pprint(result)
```
##### Example Response
On success, the HTTP status code in the response header is `200 OK` and a file is written to the local computer using the provided filename.
Outbound,2019-06-25 18:18:54+00,2019-06-25 18:19:31+00,18774551500,Office Line 2,+12063389999,0.00000000,UNITED STATES - TOLL FREE,N/A,,completed,200,OK,37,42,0.000000,6,6,0.00000000,0.0000,0.00000000,0.00000000,0.00000000,,53.186.152.52:5080
Inbound,2019-06-25 18:18:00+00,2019-06-25 18:18:29+00,12063389999,Office Line 2,+12069928999,0.00474784,UNITED STATES,UNITED STATES,61,completed,200,OK,29,30,0.001500,6,6,0.00075000,0.0000,0.00000000,0.00009784,0.00390000,,53.186.152.52
Outbound,2019-06-25 18:15:38+00,2019-06-25 18:17:24+00,12069928999,Office Line 1,+12063389998,0.01994112,UNITED STATES,N/A,,completed,200,OK,106,108,0.009800,6,6,0.01764000,0.0000,0.00000000,0.00230112,0.00000000,,53.186.151.52:5080
```
#### Errors
In cases of method errors, the Python library raises an exception which includes an error message and the HTTP body that was received in the request.
@ -1696,8 +1437,6 @@ In cases of method errors, the Python library raises an exception which includes
## Testing
Once you are done configuring your Flowroute API credentials and updating the function parameters, you can run any of the demo files to see them in action. The Flowroute library demo files are named after the resource they represent: `<resource_name>_demo.py`.
Once you are done configuring your Flowroute API credentials and updating the function parameters, you can run any of the demo files to see them in action. The Flowroute library demo files are named after the resource they represent: <resource_name>_demo.py.
