java-bandwidth-iris

Java Client library for IRIS / BBS API

Installing

Bandwidth Java IRIS SDK uses Maven. The jars are available from a public Maven repository

Use the following dependency in your project:

<dependency>
  <groupId>com.bandwidth.sdk</groupId>
  <artifactId>bandwidth-java-iris-sdk</artifactId>
  <version>1.0</version>
  <scope>compile</scope>
</dependency>

If you want to compile it yourself, here's how:

$ git clone [email protected]:bandwidthcom/java-bandwidth-iris.git
$ cd java-bandwidth-iris
$ mvn install

Usage

Creating the client

IrisClient client = new IrisClient(accountId, username, password);

// You can then use the client to call a particular object's methods, e.g.
Site s = new Site();
Site returnSite = Site.create(client, s);

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 each of the examples, set them as run targets in your IDE, then set the following system environment variables:

export BANDWIDTH_IRIS_ACCOUNTID=<youraccountid>
export BANDWIDTH_IRIS_USERNAME=<yourusername>
export BANDWIDTH_IRIS_PASSWORD=<yourpassword>
export BANDWIDTH_IRIS_URL=https://dashboard.bandwidth.com

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 newSite = new Site();
newSite.setName("My New Site");

Site s = Site.create(client, newSite);
s.setName("Some Other Name");
s.update();
//then
s.delete();// etc

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

Available Numbers

Map<String, Object> query = new HashMap<String, Object>();
query.put("areaCode", "205");
query.put("enableTNDetail", true);
query.put("quantity", 2);

List<TelephoneNumberDetail> numbers = (List<TelephoneNumberDetail>) AvailableNumbers.search(client, query);
for (TelephoneNumberDetail number : numbers)
{
    System.out.println(String.format("Full number: %s : Rate Center: %s", number.getFullNumber(), number.getRateCenter()));
}

Available NpaNxx

Map<String, Object> query = new HashMap<String, Object>();
query.put("areaCode", "805");
query.put("quantity", 2);
List<AvailableNpaNxx> availableNpaNxxList = AvailableNpaNxx.list(client, query);
for(AvailableNpaNxx npaNxx : availableNpaNxxList){
    System.out.println(
      String.format("City: %s | Npa: %s | Nxx: %s | State: %s ", npaNxx.getCity(), npaNxx.getNpa(),
              npaNxx.getNxx(), npaNxx.getState())
    );
}

Cities

Map<String, Object> query = new HashMap<String, Object>();
query.put("state", "NC");

List<City> cities = City.list(client, query);
for(City c : cities){
    System.out.println(String.format("Name: %s | RcAbbreviation: %s", c.getName(), c.getRcAbbreviation()));
}

Covered Rate Centers

Map<String, Object> query = new HashMap<String, Object>();
query.put("state", "NC");

List<CoveredRateCenter> rateCenters = CoveredRateCenter.list(client, query);
for(CoveredRateCenter rc : rateCenters){
    System.out.println(String.format("Name: %s | Abbreviation: %s | State: %s | Lata: %s", rc.getName(),
            rc.getAbbreviation(), rc.getState(), rc.getLata()));
}

Disconnect Numbers

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

Create Disconnect

DisconnectTelephoneNumberOrder disco = new DisconnectTelephoneNumberOrder();
disco.setName("A test order");
disco.getDisconnectTelephoneNumberOrderType().getTelephoneNumberList().add("9195551212");

DisconnectTelephoneNumberOrderResponse response = DisconnectTelephoneNumberOrder.create(client, disco);

Get Disconnect

DisconnectTelephoneNumberOrderResponse response = DisconnectTelephoneNumberOrder.get(client, "orderId");

Dlda

Create Ddla

DldaTnGroup dldaTnGroup = new DldaTnGroup();
dldaTnGroup.getTelephoneNumberList().add("9195551212");
dldaTnGroup.setAccountType("RESIDENTIAL");
dldaTnGroup.setListingType("LISTED");
DldaOrder order = new DldaOrder();
order.getDldaTnGroups().add(dldaTnGroup);

DldaOrder newOrder = DldaOrder.create(client, order);

Get Dlda

DldaOrder order = DldaOrder.get(client, "orderId");

List Dldas

Map<String, Object> query = new HashMap<String, Object>();
query.put("telephoneNumber", "9195551212");

ResponseSelectWrapper wrapper = DldaOrder.list(client, query);

In Service Numbers

List InService Numbers

Map<String, Object> query = new HashMap<String, Object>();
query.put("state", "NC");

TNs tns = InserviceNumber.list(client, query);

Lidb

Create

LidbTnGroup group = new LidbTnGroup();
group.getTelephoneNumberList().add("9195551212");
LidbOrder order = new LidbOrder();
order.getLidbTnGroupList().add(group);
order = LidbOrder.create(client, order);

Get Lidb

LidbOrder order = LidbOrder.get(client, "orderId");

LNP Checker

Check LNP

NumberPortabilityRequest request = new NumberPortabilityRequest();
request.getTnList().add("9195551212");
NumberPortabilityResponse response = LnpChecker.checkLnp(client, request, "true");
System.out.println(response.getPortableNumbers().get(0));

Orders

Create Order

Order o = new Order();
o.setName("A New Order");
ExistingTelephoneNumberOrderType existingTelephoneNumberOrderType = new ExistingTelephoneNumberOrderType();
existingTelephoneNumberOrderType.getTelephoneNumberList().add("2052865046");
o.setExistingTelephoneNumberOrderType(existingTelephoneNumberOrderType);

OrderResponse createdOrder = Order.create(client, o);

Get Order

Order o = Order.get(client, "orderId");

Order Instance Methods

order.update();
order.delete();
order.getNotes()
order.addNote(Note n);

Port Ins

Create PortIn

LnpOrder order = new LnpOrder();
order.setSiteId(getFirstSite().getId());
order.setPeerId(getFirstSipPeer().getPeerId());
order.setBillingTelephoneNumber("9195551212");
Subscriber s = new Subscriber();
s.setSubscriberType("BUSINESS");
s.setBusinessName("Company");
ServiceAddress serviceAddress = new ServiceAddress();
serviceAddress.setHouseNumber("123");
serviceAddress.setStreetName("Anywhere St");
serviceAddress.setCity("Raleigh");
serviceAddress.setStateCode("NC");
serviceAddress.setZip("27609");
s.setServiceAddress(serviceAddress);
order.setSubscriber(s);
order.setLoaAuthorizingPerson("Joe Blow");
order.getListOfPhoneNumbers().add("9195551212");

order = LnpOrder.create(client, order);

Get PortIn

LnpOrder order = LnpOrder.get(client, "orderId");

PortIn Instance methods

order.update(client, LnpOrderSupp supp);
order.delete();

PortIn File Management

order.uploadLoa(File file, LoaFileType type);
order.updateLoa(File file, LoaFileType type);
order.deleteLoa(String fileName);
order.getLoaMetaData(String fileName);
order.updateLoaMetaData(String fileName, FileMetaData metaData);
order.deleteLoaMetaData(String fileName);

Rate Centers

List Ratecenters

Map<String, Object> query = new HashMap<String, Object>();
query.put("state", "NC");
query.put("available", true);

List<RateCenter> rateCenters = RateCenter.list(client,query);
for(RateCenter rc : rateCenters){
    System.out.println(String.format("Name: %s | Abbreviation: %s", rc.getName(), rc.getAbbreviation()));
}

SIP Peers

Create SIP Peer

Host host = new Host();
host.setHostName("new host");

TerminationHost termHost = new TerminationHost();
termHost.setHostName("term host");
termHost.setPort("5060");

SipPeer peer = new SipPeer();
peer.setPeerName("A new Sip Peer");
peer.setDefaultPeer(false);
peer.setShortMessagingProtocol("SMPP");
peer.setSiteId(getFirstSite().getId());

peer.getVoiceHosts().add(host);
peer.getSmsHosts().add(host);
peer.getTerminationHosts().add(termHost);

peer = SipPeer.create(client, getFirstSite().getId(), peer);

Get SIP Peer

SipPeer peer = SipPeer.get(client, "siteId", "peerId");

List SIP Peers

List<SipPeer> peers = SipPeer.list(client, "siteId");

Delete SIP Peer

SipPeer peer = SipPeer.get(client, "peerId");
peer.delete()

SipPeer TN Methods

peer.updateTn(sipPeerTelephoneNumber);
peer.getTn("number");
peer.moveTns(sipPeerTelephoneNumbers);

Enable SMS Settings

// Zone1 for US & Canada enabled by default
SipPeerSmsFeature settings = new SipPeerSmsFeature();
settings.setTollFree(true);
settings.setShortCode(true);
peer.enableSms(settings);

Enable MMS

peer.enableMms();

Associate a SipPeer with a Messaging Application

SipPeerMessagingApplicationsSettings settings = new SipPeerMessagingApplicationsSettings();
settings.setApplicationId("abcd-1234");

peer.updateMessagingApplicationSettings(settings);

Sites

Create A Site

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

Site s = new Site();
s.setName("My New Site");

s = Site.create(client, s);

Updating a Site

Site s = Site.get(client, "siteId");
s.setName("New Name");
s.update();

Deleting a Site

Site s = Site.get(client, "siteId");
s.delete();

Listing All Sites

List<Site> sites = Site.list(client);

Subscriptions

Create Subscription

Subscription subscription = new Subscription();
subscription.setOrderType("orders");
subscription.setOrderId("orderId");
EmailSubscription emailSubscription = new EmailSubscription();
emailSubscription.setEmail("[email protected]");
emailSubscription.setDigestRequested("NONE");
subscription.setEmailSubscription(emailSubscription);
Subscription createdSubscription = Subscription.create(client, subscription);

Get Subscription

Subscription s = Subscription.get(client, "subscriptionId");

List Subscriptions

Map<String, Object> query = new HashMap<String, Object>();
query.put("orderType", "orders");

List<Subscription> subscriptions = Subscription.list(client, query);

Subscription Instance Methods

subscription.update();
subcription.delete();

TNs

Get TN

TelephoneNumberDetail detail = Tns.getTnDetails(getClient(), "9195551212");

List TNs

Map<String, Object> query = new HashMap<String, Object>();
query.put("state", "NC");

TelephoneNumbersResponse response = Tns.list(getClient(),query );

TN Reservation

Create TN Reservation

Reservation r = new Reservation();
r.getReservedTn().add("9195551212");
r = Reservation.create(client, r);

Get TN Reservation

Reservation r = Reservation.get(client, "9195551212");

Delete TN Reservation

Reservation r = Reservation.get(client, "9195551212");
r.delete();

ImportTnOrder

Create ImportTnOrder

ImportTnOrder order = new ImportTnOrder();
order.setSiteId(100);
order.setSipPeer(303);

ServiceAddress address = new ServiceAddress();
address.setHouseNumber("123");
address.setStreetName("Main st");
address.setCity("Raleigh");
address.setStateCode("NC");
address.setZip("27606");

Subscriber sub = new Subscriber();
sub.setBusinessName("test business llc");
sub.setName("Bandwidth");
sub.setFirstName("Band");
sub.setLastName("Width");
sub.setServiceAddress(address);

List<String> telephoneNumberList = new ArrayList<String>();
telephoneNumberList.add("9195551234");

order.setSiteId(14480);
order.setSipPeer(522211);
order.setTelephoneNumberList(telephoneNumberList);
order.setSubscriber(sub);
order.setLoaAuthorizingPerson("Bandwidth");

ImportTnOrderResponse response = ImportTnOrder.Create(client, order );

List ImportTnOrders

Map<String, Object> query = new HashMap<>();
query.put("CustomerOrderId", "id");

ImportTnOrders response = ImportTnOrder.List(client, query);

Get ImportTnOrder by Id

ImportTnOrder response = ImportTnOrder.Get(client, orderId );

Get ImportTnOrder History by Id

OrderHistoryWrapper response = ImportTnOrder.GetHistory(client, orderId );

RemoveImportedTnOrders

Create RemoveImportedTnOrder

List<String> tnList = new ArrayList<String>();
telephoneNumberList.add("9195551234");

RemoveImportedTnOrder order = new RemoveImportedTnOrder();
order.setTelephoneNumberList( tnList );

RemoveImportedTnOrderResponse response = RemoveImportedTnOrder.Create(client, order);

List RemoveImportedTnOrders

Map<String, Object> query = new HashMap<>();
query.put("status ", "PARTIAL");

RemoveImportedTnOrders response = RemoveImportedTnOrder.List(client, query);

Get RemoveImportedTnOrder by Id

RemoveImportedTnOrder response = RemoveImportedTnOrder.Get(client, orderId);

Get RemoveImportedTnOrder History by Id

OrderHistoryWrapper response = RemoveImportedTnOrder.GetHistory(client, orderId);

ImportTnChecker

Check Importability of Tns

ImportTnCheckerPayload payload = new ImportTnCheckerPayload();
payload.setTelephoneNumberList( tnList );

ImportTnCheckerResponse response = ImportTnChecker.Check(client, payload);

Csr Order

Create Csr

Csr csr = new Csr();
csr.setCity("Raleigh");

CsrResponse response = Csr.Create(client, csr);

Get Csr

CsrResponse response = Csr.Get(client, orderId);

Replace Csr

Csr csr = new Csr();
csr.setCity("Raleigh");

CsrResponse response = Csr.Replace(client, orderId, csr);

Get Csr Notes

Notes response = Csr.GetNotes(client, orderId);

Add Note to Csr

Note note = new Note();
note.setDescription("This is a csr note");

IrisResponse response = Csr.AddNote(client, orderId, note );

Update Note on Csr

Note note = new Note();
note.setDescription("This is a csr note");

IrisResponse response = Csr.UpdateNote(client, orderId, noteId, note );

Emergency Notification

Create Recipients

EmergencyNotificationRecipient recipient = new EmergencyNotificationRecipient();
recipient.setEmailAddress("[email protected]");

EmergencyNotificationRecipientsResponse response = EmergencyNotification.createRecipients(client, recipient);

List Recipients

Map<String, String> query = new HashMap<String, Object>();
query.add("ModifiedByUser", "jgilmore");

EmergencyNotificationRecipientsResponse response = EmergencyNotification.listRecipients(client, query);

Get Recipients

EmergencyNotificationRecipientsResponse response = EmergencyNotification.getRecipients(client, recipientsId);

Replace Recipients

EmergencyNotificationRecipient recipient = new EmergencyNotificationRecipient();
recipient.setEmailAddress("[email protected]");

EmergencyNotificationRecipientsResponse response = EmergencyNotification.replaceRecipients(client, recipient, recipientsId);

Delete Recipient

IrisResponse response = EmergencyNotification.deleteRecipients(client, recipientsId);

Create Group Orders

EmergencyNotificationGroupOrder groupOrder = new EmergencyNotificationGroupOrder();
groupOrder.setCustomerOrderId("customerId");

EmergencyNotificationGroupOrderResponse response = EmergencyNotification.createGroupOrders(client, groupOrder);

Modify Group Orders

EmergencyNotificationGroupOrderResponse response = EmergencyNotification.createGroupOrders(client, new EmergencyNotificationGroupOrder());

List Group Orders

EmergencyNotificationGroupOrderResponse response = EmergencyNotification.listGroupOrders(client, query);

Get Group Orders

EmergencyNotificationGroupOrderResponse response = EmergencyNotification.getGroupOrders(client, orderId);

List Groups

EmergencyNotificationGroupsResponse response = EmergencyNotification.listGroups(client, query);

Get Groups

EmergencyNotificationGroupsResponse response = EmergencyNotification.getGroups(client, orderId);

Create Endpoint Order

EmergencyNotificationEndpointOrderResponse response = EmergencyNotification.createEndpointOrder(client, new EmergencyNotificationEndpointOrder());

List Endpoint Orders

EmergencyNotificationEndpointOrderResponse response = EmergencyNotification.listEndpointOrders(client, query);

Get Endpoint Orders

EmergencyNotificationEndpointOrderResponse response = EmergencyNotification.getEndpointOrder(client, orderId);

Aeuis

Get Aeui

AlternateEndUserIdentifierResponse response = Aeui.get(client, id);

List Aeuis

AlternateEndUserIdentifiersResponse response = Aeui.list(client, query);

Tn Options

Tn Options Create

Creates a TN Option order to assign line features to the telephone number.

Create PortOutPasscode

TnOptionOrder order = new TnOptionOrder();
order.setTnOptionGroups(new ArrayList<>());
order.setCustomerOrderId("TnOptionOrder1");

TnOptionGroup optionGroup = new TnOptionGroup();
optionGroup.setPortOutPasscode("12abd38");// PortOutPasscode set here
optionGroup.setTelephoneNumbers(new ArrayList<>());
optionGroup.getTelephoneNumbers().add("2018551020");

order.getTnOptionGroups().add(optionGroup);

TnOptionOrderResponse response = TnOptions.create(client, order);

Create Call Forward Number

TnOptionOrder order = new TnOptionOrder();
order.setTnOptionGroups(new ArrayList<>());
order.setCustomerOrderId("TnOptionOrder1");

TnOptionGroup optionGroup = new TnOptionGroup();
optionGroup.setCallForward("2018551022");// Call Forward set here
optionGroup.setTelephoneNumbers(new ArrayList<>());
optionGroup.getTelephoneNumbers().add("2018551020");

order.getTnOptionGroups().add(optionGroup);

TnOptionOrderResponse response = TnOptions.create(client, order);

Enable SMS

TnOptionOrder order = new TnOptionOrder();
order.setTnOptionGroups(new ArrayList<>());
order.setCustomerOrderId("TnOptionOrder1");

TnOptionGroup optionGroup = new TnOptionGroup();
optionGroup.setSms("on");// SMS set true here
optionGroup.setTelephoneNumbers(new ArrayList<>());
optionGroup.getTelephoneNumbers().add("2018551020");

order.getTnOptionGroups().add(optionGroup);

TnOptionOrderResponse response = TnOptions.create(client, order);

Get Tn Option (No Error)

TnOptionOrder response = TnOptions.get(client, orderId);

Get Tn Option (With Error)

TnOptionOrder response = TnOptions.get(client, orderId);

System.out.println(response.getErrors().size());// 1
System.out.println(response.getErrors().get(0).getCode()); // 5076
System.out.println(response.getErrors().get(0).getDescription()); // Telephone number is not available.
System.out.println(response.getErrors().get(0).getTelephoneNumber());// 2018551025

List Tn Options

HashMap<String, Object> query = new HashMap<>();
query.put("tn", "9199918388");

TnOptionOrders response = TnOptions.list(client, query);