ruby-bandwidth-iris

Ruby Client library for IRIS / BBS API

Release Notes

Release Version	Notes
1.0.5	Fixed incorrect generation of XML for a Disconnect request

Install

Run

gem install ruby-bandwidth-iris

Usage

require 'ruby-bandwidth-iris'

# Using  directly
client = BandwidthIris::Client.new('accountId', 'userName', 'password')
sites = BandwidthIris::Site.list(client)

# Or you can use default client instance (do this only once)
BandwidthIris::Client.global_options = {
  :account_id => 'accountId',
  :username => 'userName',
  :password => 'password'
}

# Now you can call any functions without first arg 'client'

sites = BandwidthIris::Site.list()

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 the examples:

$ cd examples
$ cp config.yml.example config.yml

Edit the config.yml to match your IRIS credentials and run the examples individually. e.g.

ruby covered_rate_centers.rb

If the examples take command line parameters, you will get the usage by just executing the individual script.

API Objects

General principles

When fetching objects from the API, it will always return an object that has the client instantiated so that you can call dependent methods as well as update, delete.

Example:

site = BandwidthIris::Site.create({siteObject})

# or

site = BandwidthIris::Site.create(client, {siteObject})

Each entity has a get, list, create, update and delete method if appropriate.

All properties are underscored and low-cased for Ruby readability, and are converted on the fly to the proper case by the internals of the API when converted to XML.

Available Numbers

list = BandwidthIris::AvailableNumbers.list(query)

Available NpaNxx

list = BandwidthIris::AvailableNpaNxx.list({:area_code => "818", :quantity =>5})

Cities

list = BandwidthIris::City.list({:available => true, :state =>"CA"})

Covered Rate Centers

BandwidthIris::CoveredRateCenter.list({:zip => "27601"})

Disconnected Numbers

Retrieves a list of disconnected numbers for an account

BandwidthIris::DiscNumber.list({:area_code => "919"})

Disconnect Numbers

The Disconnect object is used to disconnect numbers from an account. Creates a disconnect order that can be tracked

Create Disconnect

BandwidthIris::Disconnect.create("Disconnect Order Name", ["9195551212", "9195551213"])

Add Note to Disconnect

order.add_note({:user_id => "my id", :description => "Test"})

Get Notes for Disconnect

order.get_notes()

Dlda

Create Ddla

dlda = {
  :customer_order_id => "Your Order Id",
  :dlda_tn_groups => [
    :dlda_tn_group => {
      :telephone_numbers => ["9195551212"],
      :subscriber_type => "RESIDENTIAL",
      :listing_type => "LISTED",
      :listing_name => {
        :first_name => "John",
        :last_name => "Smith"
      },
      :list_address => true,
      :address => {
        :house_number => "123",
        :street_name => "Elm",
        :street_suffix => "Ave",
        :city => "Carpinteria",
        :state_code => "CA",
        :zip => "93013",
        :address_type => "DLDA"
      }
    }
  ]
}

BandwidthIris::Dlda.create(dlda)

Get Dlda

dlda = Bandwidth::Dlda.get(id)

Get Dlda History

dlda.get_history()

List Dldas

BandwidthIris::Dlda.list({:telephone_number => "9195551212"})

Import To Account

This path is generally not available to Bandwidth accounts, and as such is not documented in this API

In Service Numbers

List InService Numbers

BandwidthIris::InServiceNumber.list({:area_code => "919"})

Get InService Number Detail

BandwidthIris::InServiceNumber.get("9195551212")

Lidb

Create

data = {
  :customer_order_id => "A test order",
  :lidb_tn_groups => {
    :lidb_tn_group => {
      :telephone_numbers => ["8048030097", "8045030098"],
      :subscriber_information => "Joes Grarage",
      :use_type => "RESIDENTIAL",
      :visibility => "PUBLIC"
    }
  }
}
BandwidthIris::Lidbs.create(data)

Get Lidb

BandwidthIris::Lidbs.get(id)

List Lidbs

BandwidthIris::Lidbs.list({:telephone_number => "9195551212"})

LNP Checker

Check LNP

numbers = ["9195551212", "9195551213"]
full_check = true
BandwidthIris::LnpChecker.check(numbers, full_check)

LSR Orders

Create LSR Order

data = {
  :pon => "Some Pon",
  :customer_order_id => "MyId5",
  'sPID' => "123C",
  :billing_telephone_number => "9192381468",
  :requested_foc_date => "2015-11-15",
  :authorizing_person => "Jim Hopkins",
  :subscriber => {
    :subscriber_type => "BUSINESS",
    :business_name => "BusinessName",
    :service_address => {
      :house_number => "11",
      :street_name => "Park",
      :street_suffix => "Ave",
      :city => "New York",
      :state_code => "NY",
      :zip => "90025"
    },
    :account_number => "123463",
    :pin_number => "1231"
  },
  :list_of_telephone_numbers => {
    :telephone_number => ["9192381848", "9192381467"]
  }
}

BandwidthIris::LsrOrder.create(data)

Get LSR Order

BandwidthIris::LsrOrder.get(id)

List LSR Orders

BandwidthIris::LsrOrder.list({:pon =>"Some Pon"})

Update LSR Order

order.requestedFocDate = "2015-11-16"
BandwidthIris::LsrOrder.update(order)

Get LSR Order History

order.get_history()

Get LSR Order Notes

order.get_notes()

Add LSR Order Note

var note = {:user_id => "my id", :description => "Test"}
order.add_note(note)

Orders

Create Order

order = {
  :name => "A Test Order",
  :site_id => 1111,
  :existing_telephone_number_order_type => {
    telephone_number_list =>
      {
        :telephone_number => ["9195551212"]
      }
    
  }
}

BandwidthIris::Order.create(order)

Get Order

BandwidthIris::Order.get(id)

List Orders

BandwidthIris::Order.list(query)

Order Instance Methods

// get Area Codes
order.get_area_codes()

// add note to order
var note = {:user_id => "my id", :description => "Test"}
order.add_note(note)

//get Npa Nxxs
order.get_npa_nxx()

// get number totals
order.get_totals()

// get all Tns for an order
order.get_tns()

// get order history
order.get_history()

// get order notes
order.get_notes()

Port Ins

Create PortIn

data = {
  :site_id =>1234,
  :peer_id => 5678,
  :billing_telephone_number => "9195551212",
  :subscriber => {
    :subscriber_type => "BUSINESS",
    :business_name => "Company",
    :service_address => {
      :house_number => "123",
      :street_name => "EZ Street",
      :city => "Raleigh",
      :state_code => "NC",
      :county => "Wake"
    }
  }, 
  :loa_authorizing_person => "Joe Blow",
  :list_of_phone_numbers => {
    :phone_number => ["9195551212"]
  },
  :billing_type => "PORTIN"
}

BandwidthIris::PortIn.create(data)

Get PortIn

BandwidthIris::PortIn.get("id", callback)

PortIn Instance methods

portIn.update(data)
portIn.delete()

PortIn File Management

# Add File
portIn.create_file(IO.read("myFile.txt"))

# Update File
portIn.update_file("myFile.txt", IO.read("myFile.txt"))

# Get File
portIn.get_file("myFile.txt")

# Get File Metadata
portIn.get_file_metadata("myFile.txt")

# Get Files
portIn.get_files()

Port Out

List PortOuts

query = {:status => "complete"}
BandwidthIris::PortOut.list(query)

Get PortOut

BandwidthIris::PortOut.get(id)

Rate Centers

List Ratecenters

query = {:available => true, :state => "CA"}
BandwidthIris::RateCenter.list(query)

SIP Peers

Create SIP Peer

data = {
  :peer_name => "A New SIP Peer",
  :is_default_peer => false, 
  :short_messaging_protocol =>"SMPP",
  :site_id => selectedSite, 
  :voice_hosts =>
    {
      :host => [{
        :host_name => "1.1.1.1"
      }]
    },
  :sms_hosts =>
    {
      :host => [{
        :host_name => "1.1.1.1"
      }]
    },
  :termination_hosts => 
    {
        :termination_host =>[{
        :host_name => "1.1.1.1",
        :port => 5060
      }]
    }
  
}

BandwidthIris::SipPeer.create(data)

Get SIP Peer

BandwidthIris::SipPeer.get("id")

List SIP Peers

BandwidthIris::SipPeer.list(siteId)

Delete SIP Peer

sipPeer.delete()

SipPeer TN Methods

# get TN for this peer
sipPeer.get_tns(number)  

# get all TNs for this peer
sipPeer.get_tns()

# Update TNs for this peer
tns = {:full_number => "123456", :rewrite_user => "test"}
sipPeer.update_tns(number, tns)

#  Move Tns to new peer
numbers_to_move = ["9195551212", "9195551213"]
sipPeer.move_tns(numbers_to_move)

Sites

Create A Site

A site is what is called Location in the web UI.

site = {
  :name =>"A new site",
  :description =>"A new description",
  :address => {
    :house_number => "123",
    :street_name => "Anywhere St",
    :city => "Raleigh",
    :state_code =>"NC",
    :zip => "27609",
    :address_type => "Service"
  }
};
BandwidthIris::Site.create(site)

Updating a Site

site.update({:name => "New name"})

Deleting a Site

site.delete()

Listing All Sites

BandwidthIris::Site.list()

### Site SipPeer Methods
```ruby
# get Sip Peers
site.get_sip_peers()

# get Sip Peer
site.get_sip_peer(id)

# create Sip Peer
sip_peer = {:name =>"SIP Peer"}
site.create_sip_peer(sipPeer)

Subscriptions

Create Subscription

subscription = {
  :order_type => "orders",
  :callback_subcription => {
    :url => "http://mycallbackurl.com",
    :user => "userid",
    :expiry => 12000
  }
}
BandwidthIris::Subscription.create(subscription)

Get Subscription

BandwidthIris::Subscription.get(id)

List Subscriptions

BandwidthIris::Subscription.list(query)

Subscription Instance Methods

# update subscription
updatedData = {:order_type => "portins"}
subscription.update(updatedData)

# delete subscription
subscription.delete()
});

TNs

Get TN

tn = BandwidthIris::Tn.get(fullNumber)

List TNs

BandwidthIris::Tn.list(query)

TN Instance Methods

# Get TN Details
tn = tn.geti_tn_details()

# Get Sites
tn.get_sites()

# Get Sip Peers
tn.get_sip_peers()

# Get Rate Center
tn.get_rate_center()

TN Reservation

Create TN Reservation

BandwidthIris::TnReservation.create({:reserved_tn => "9195551212"})

Get TN Reservation

tn = BandwidthIris::TnReservation.get(id)

Delete TN Reservation

tn.delete()