Python Numbers SDK

Needed tools

- Python >=3.7
- pip

Requires

- future
- requests

Install

pip install bandwidth-numbers-sdk

Testing

Tests require the mock and requests_mock packages. You can install them with

pip install -r test-requirements.txt

The tests can be run by issuing

pytest

Usage

from bandwidth_numbers import Account, Client

client = Client(url="https://dashboard.bandwidth.com/api", account_id=123456, username="foo",
    password="bar")

or

client = Client(filename=<path to config>)

Config format

[account]
account_id = 123456789
username   = spam
password   = ham

[rest]
url = https://dashboard.bandwidth.com/api

Examples

There is an 'examples' folder in the source tree that shows how each of the API objects work with simple example code. To run these make a copy of 'config.cfg.example', rename to 'config.cfg', edit it to match your IRIS credentials and run the examples individually, e.g.,

python available_numbers.py

If an example takes command line parameters, you will get the usage info by just executing it.

API objects

General principles

In most cases you should use an Account object as a starting point.

account = Account(client=client)

Account has related entities such as Orders, Sites, etc.

sites = account.sites.list()
for site in sites.items:
   pass

Pagination

Some resources provide paginated result sets and require the use of page/size parameters. In these cases a Links object will be provided for iterating over the results.

in_service_numbers = account.in_service_numbers.list({"page": 1, "size": 10})

total = int(account.in_service_numbers.total_count)
total_displayed = len(in_service_numbers.items)
page = None

while total_displayed <= total:
    if page is not None:
        in_service_numbers = account.in_service_numbers.list(
            {"page": page, "size": 10})
    page = account.in_service_numbers.links.next
    for phone_number in in_service_numbers.items:
        print(phone_number)
    total_displayed += len(in_service_numbers.items)

Available numbers

account.available_numbers.list({"areaCode": 818})

Available Npa-Nxx

account.available_npa_nxx.list({"state": "NJ"})

Cities

from bandwidth_numbers import Cities

cities = Cities(client=client)
cities.list({"state": "NC"})

Covered rate centers

from bandwidth_numbers import CoveredRateCenters

rate_centers = CoveredRateCenters(client=client)
rate_centers.list({"page": 1, "size": 10})

Disconnected numbers

account.disconnected_numbers.list({"areaCode": 919})

Disconnecting telephone numbers

Creating disconnect orders

disconnect = account.disconnects.create({
    "name": "test disconnect order 4",
    "customer_order_id": "Disconnect1234",
    "disconnect_telephone_number_order_type": {
        "telephone_number_list": {
            "telephone_number": ["9192755378", "9192755703"]
        }
    }
})

Getting order data

disconnect = account.disconnects.get("b902dee1-0585-4258-becd-5c7e51ccf5e1")

Adding notes

disconnect.notes.create({"user_id": "spam", "description": "ham"})

Getting all order's notes

notes = disconnect.notes.list()

Dlda

Creating orders

dlda = account.dldas.create({
    "customer_order_id": "123",
    "dlda_tn_groups": {
        "dlda_tn_group": [{
            "telephone_numbers": {
                "telephone_number": ["4352154856"]
                "account_type": "RESIDENTIAL",
                "listing_type": "LISTED",
                "list_address": "true",
                "listing_name": {
                    "first_name": "FirstName",
                    "first_name2": "FirstName2",
                    "last_name": "LastName",
                    "designation": "Designation",
                    "title_of_lineage": "TitleOfLineage",
                    "title_of_address": "TitleOfAddress",
                    "title_of_address2": "TitleOfAddress2",
                    "title_of_lineage_name2": "TitleOfLineageName2",
                    "title_of_address_name2": "TitleOfAddressName2",
                    "title_of_address2_name2": "TitleOfAddress2Name2",
                    "place_listing_as": "PlaceListingAs",
                },
                "address": {
                    "house_prefix": "HousePrefix",
                    "house_number": "915",
                    "house_suffix": "HouseSuffix",
                    "pre_directional": "PreDirectional",
                    "street_name": "StreetName",
                    "street_suffix": "StreetSuffix",
                    "post_directional": "PostDirectional",
                    "address_line2": "AddressLine2",
                    "city": "City",
                    "state_code": "StateCode",
                    "zip": "Zip",
                    "plus_four": "PlusFour",
                    "country": "Country",
                    "address_type": "AddressType"
                }
            }
        }]
    }
})

Getting order data

dlda = account.dldas.get("7802373f-4f52-4387-bdd1-c5b74833d6e2")

Retrieving dlda history

dlda.history.list()

Getting a list of dldas

account.dldas.list({"telephoneNumber": "9195551212"})

Import TN Checker

# returns an array of portable TN's
result = account.import_tn_checker(numbers=["3032281000", "9195551234"])
print(result)    # ['3032281000', '9195551234']

In-service numbers

account.in_service_numbers.list({"areaCode": "919"})

Lidb

Creating orders

lidb = account.lidbs.create({
    "lidb_tn_groups": {
        "lidb_tn_group": [{
            "telephone_numbers": {
                "telephone_number": ["4352154856"]
            },
            "subscriber_information": "Steve",
            "use_type": "RESIDENTIAL",
            "visibility": "PUBLIC"
        },
        {
            "telephone_numbers": {
                "telephone_number": ["4352154855"]
            },
            "subscriber_information": "Steve",
            "use_type": "RESIDENTIAL",
            "visibility": "PUBLIC"
        }]
    }
})

Getting order data

lidb = account.lidbs.get("7802373f-4f52-4387-bdd1-c5b74833d6e2")

Getting a list of lidbs

lidbs = account.lidbs.list({"last_modified_after": "mm-dd-yy",
    "telephone_number": "888"})

LNP Checker

account.lnpChecker(["4109255199", "9196190594"], "true")

Phone numbers orders

Creating orders

order = account.orders.create({
    "name": "Available Telephone Number order",
    "site_id": "2297",
    "customer_order_id": "123456789",
    "existing_telephone_number_order_type": {
        "telephone_number_list": {
            "telephone_number": ["9193752369", "9193752720", "9193752648"]
        }
    }
})

Getting order data

response = account.orders.get("f30a31a1-1de4-4939-b094-4521bbe5c8df")
order = response.order

Getting a list of orders

orders = account.orders.list()

Adding notes

order.notes.create({"user_id": "spam", "description": "Test Note"})

Getting order's telephone numbers

order.tns.list()

Port-ins

Creating orders

portin = account.portins.create({
    "billing_telephone_number": "6882015002",
    "subscriber": {
        "subscriber_type": "BUSINESS",
        "business_name": "Acme Corporation",
        "service_address": {
            "house_number": "1623",
            "street_name": "Brockton Ave",
            "city": "Los Angeles",
            "state_code": "CA",
            "zip": "90025",
            "country": "USA"
        }
    },
    "loa_authorizing_person": "John Doe",
    "list_of_phone_numbers": {
        "phone_number": ["9882015025", "9882015026"]
    },
    "site_id": "365",
    "triggered": "false"
})

Getting order data

portin = account.portinsget("d28b36f7-fa96-49eb-9556-a40fca49f7c6")

Getting a list of orders

portins = account.portins.list({"pon": "a pon"})

Port-in instance methods and properties

portin.save()
portin.delete()
portin.activation_status

status = portin.activation_status
status.auto_activation_date = "2014-08-30T18:30:00+03:00"
status.save()

portin.history
portin.totals
portin.notes

Port-in file management

portin.loas.list({"metadata": "true"})
fname = portin.loas.create("loa.pdf", {'content-type': 'application/pdf'})
portin.loas.update(fname, "loa.pdf", {'content-type':'application/pdf'})
portin.loas.delete(fname)
portin.loas.metadata.get(fname)
portin.loas.metadata.document_name = "text.txt"
portin.loas.metadata.document_type = "invoice"
portin.loas.metadata.save()
portin.loas.metadata.delete()

Rate Centers

from bandwidth_numbers import RateCenters
rc = RateCenters(client=client)
centers = rc.list({"state": "CA", "available": "true"})

SIP Peers

Creating a SIP peer

sip_peer = account.sites.list().items[0].sip_peers.create({
        "peer_name": name,
        "is_default_peer": "true",
        "short_messaging_protocol": "SMPP",
        "voice_hosts": {
            "host": [{
                "host_name": "92.168.181.95"
            }]
        },
        "sms_hosts": {
            "host": [{
                "host_name": "92.168.181.95"
            }]
        },
        "termination_hosts": {
            "termination_host": [{
                "host_name": "92.168.181.95",
                "port": "0",
                "customer_traffic_allowed": "DOMESTIC",
                "data_allowed": "true"
            }]
        }
    })

Getting a peer

sip_peer = account.sites.list().items[0].sip_peers.get("500651")

Getting a list of SIP peers

sip_peers = account.sites.list().items[0].sip_peers.list()

Deleting SIP peers

sip_peer.delete()

Moving telephone numbers

sip_peer.movetns.add("9192000046")
sip_peer.movetns()

Getting peer telephone numbers

tns = sip_peer.tns.list()

Getting a single phone number

tn = sip_peer.tns.get("8183386251")

Getting total number of numbers for a SIP peer

count = sip_peer.totaltns.get()

Setting telephone number options

tn = sip_peer.tns.get("8183386251")
tn.rpid_format = "e164"
tn.save()

Sites

Creating a site

site = acc.sites.create({
    "name": "test123456",
    "address": {
        "city": "Raleigh",
        "address_type": "Service",
        "house_number": "1",
        "street_name": "Avenue",
        "state_code": "NC",
        "zip": "27606"
    }
})

Updating a site

site.name = "New Name"
site.save()

Deleting a site

site.delete()

Getting a list of sites

sites = account.sites.list()

Getting a list of site orders

site.orders.list({"status": "disabled"})

Getting the total number of telephone numbers for a site

site.totaltns.get()

Getting a list of site's port-in orders

site.portins.list({"status": "disabled"})

Subscriptions

Creating subscriptions

subscription = account.subscriptions.create({
    "order_type": "portins",
    "order_id": "98939562-90b0-40e9-8335-5526432d9741",
    "email_subscription": {
        "email": "[email protected]",
        "digest_requested": "DAILY"
    }
})

Getting subscription information

subscription = account.subscriptions.get(id)

Getting a list of subscriptions

account.subscriptions.list({"orderType": "portins"})

Updating a subscription

subscription.order_type = "portins"
subscription.save()

Deleting a subscription

subscription.delete()

TNs

Getting a phone number

from bandwidth_numbers import Tns

tns = Tns(client=client)
tn = tns.get(id)

Getting a list of TNs

tns.list({"page": 1, "size": 10 })

Telephone number instance methods and properties

tn = tns.get("7576768750")
site = tn.site.get()
sip_peer = tn.sip_peer.get()
tnreservation = tn.tnreservation
tn.tndetails.get()
rc = tn.tn_rate_center.get()
lata = tn.tn_lata.get()
lca = tn.lca.get()
history = tn.history.list()

Reserving phone numbers

Create a reservation

account.tnreservation.reserved_tn = "2512027430"
account.tnreservation.save()

Getting reservation info

reservation = account.tnreservation.get("0099ff73-da96-4303-8a0a-00ff316c07aa")

Deleting a reservation

reservation.delete()

Get TN Option Orders

orders = account.tn_option_orders.list()
print(orders.total_count)
print(orders.tn_option_order_summary.items[0].account_id)

Get TN Option Order

order = account.tn_option_orders.get("order_id")
print(order.order_create_date)

Get TN Option Order (error)

order = account.tn_option_orders.get("order_id_with_error")
print(order.error_list.error.items[0].description)

Create PortOut Passcode

order = account.tn_option_orders.create({
    "customer_order_id": "custom order",
    "tn_option_groups": {
        "tn_option_group": [
            {
                "port_out_passcode": "12abd38",
                "telephone_numbers": {
                    "telephone_number": [
                        "2018551020"
                    ]
                }
            }
        ]
    }
})

print(order.order_create_date)

Create Call Forward Number

order = account.tn_option_orders.create({
    "customer_order_id": "custom order",
    "tn_option_groups": {
        "tn_option_group": [
            {
                "call_forward": "2018551022",
                "telephone_numbers": {
                    "telephone_number": [
                        "2018551020"
                    ]
                }
            }
        ]
    }
})

print(order.order_create_date)

Enable SMS

order = account.tn_option_orders.create({
    "customer_order_id": "custom order",
    "tn_option_groups": {
        "tn_option_group": [
            {
                "sms": "on",
                "telephone_numbers": {
                    "telephone_number": [
                        "2018551020"
                    ]
                }
            }
        ]
    }
})

print(order.order_create_date)