Videoscape Control Suite 3.5.0
Business Support
System/Operational Support System
Adaptor (BOA) API Guide
Overview
Introduction
This document describes the data model and API of Version 3.5-0-5 of the Cisco
Business Support System/Operational Support System Adaptor (BOA) service.
Supported Data Formats
The BOA service supports XML requests and responses.
The format of all dates and times supported in the BOA service appear in this
format:
Y — year
M — month
D — day
H — hour
m — minute
s — second
Example: 2013-06-18T14:02:22Z
Document Version
This is the second formal release of this document, which was updated for
Version 3.5 of the Videoscape Control Suite (VCS).
In This Document
2
Types ............................................................................................................................ 3
HTTP Codes ................................................................................................................ 9
Standard REST Response......................................................................................... 10
Get Response Objects ............................................................................................... 11
REST Command Guidance and Examples ............................................................ 18
BOA Common API Schema .................................................................................... 90
Purchase Report Schema ....................................................................................... 110
OL-28775-02
Types
Types
The following is a list of the types used to call the BOA. This section does not include
a description of the list objects, but they are defined in the boa.xsd file, which is
included at the end of this document.
Household
Name
Read/ Type
Write
Description
householdId
RW
String
Unique identifier of this household
householdStatus
RW
String
"ACTIVATED"
"SUSPENDED"
lastUpdateDate
R
String
Last update of this household
dateTime format
OL-28775-02
devices
RW
Object
List of devices. If a device list is included
in a household create operation, the
devices will be created at that moment.
However, the device list cannot be
manipulated through a household update
operation.
userProfiles
RW
Object
List of userProfiles. This list can be
modified, but not through the household
create/update commands. Instead, the
user profile commands must be used to
modify so that the users are defined in the
context of the household.
authorizations
RW
Object
List of authorizations for the household.
This list can be modified through the
authorization create/update/delete
commands, but cannot be modified
through the household modification
commands.
locale
RW
Object
The locale object, which contains a region
ID
enabledServices
RW
Object
This object contains a list of strings that
defines the enabled services for the
household.
preferences
RW
Object
The preferences object, which includes
household settings
npvrData
R
Object
This data is used in certain environments
to set NPVR attributes.
3
Types
Name
Read/ Type
Write
Description
spendingLimit
RW
String
The spending limit for the household
currentBalance
RW
String
The current balance for the household
Device
Name
Read/
Write
Type
Description
deviceId
RW
String
Unique identifier of this device
auxDeviceId
RW
String
Auxiliary device identifier
bssFullType
RW
String
Device type. Values include
“MANAGED” and
“UNMANAGED”
profile
RW
String
Device profile name
operateStatus
RW
String
Operational status; values include
“ACTIVE”, “INACTIVE”
jid
RW
String
Jabber ID of this device. It must
be unique.
macAddress
RW
String
MAC address of this device
ipAddress
RW
String
IP address of this device
lastUpdateDate
R
String
Last update of this device
dateTime
format
4
deviceType
R
String
Device type that is derived from
the bssFullType value
deviceFeatures
R
List of Strings
Device features derived from the
bssFullType value
deviceCategory
R
String
Device category derived from the
bssFullType value
OL-28775-02
Types
UserProfile
Name
Read/ Type
Write
Description
userProfileId
R
String
Unique identifier of this userProfile.
his value is created automatically and
is not eligible for setting with create
or update operations.
operateStatus
RW
String
Operational status; values include
“ACTIVE”, “INACTIVE".
role
RW
String
User role; values include “ADMIN”,
“NORMAL” .
favoriteChannelsUrl
R
String
Favorite channels URL for this user
displayName
RW
String
User display name
priority
RW
Integer
Priority of user, 0-10. 0 has highest
priority.
userId
RW
String
User ID. Must be unique.
lastUpdateDate
R
String
The time of the last user profile
update
dateTime
format
presenceStatus
R
String
Presence status of the user. Values
include “ONLINE”, “OFFLINE”.
Locale
The locale object encapsulates the geographic attributes of the household.
OL-28775-02
Name
Read/
Write
Type
Description
region
RW
String
The region ID
cmdcRegion
RW
String
The CMDC region
city
RW
Integer
The city code
adZone
RW
String
The ad zone
postalCode
RW
String
The postal code
marketingTarget
RW
String
The marketing target
blackoutTarget
RW
String
The blackout target
5
Types
EnabledServices
The enabled services object encapsulates the list of services, which are strings.
Name
Read/
Write
Type
Description
service
RW
String
The list of enabled services
Subscription Authorization
The subscription object encapsulates the subscription authorization attributes.
Name
Read/
Write
Type
Description
authorizationId
RW
String
The identifier string for the
authorization
authorizationType
RW
String
“SUBSCRIPTION”
“BUNDLE”
“SVOD”
“TVOD”
“PPV”
6
authorizationStatus RW
String
Authorization status values,
which include:
PURCHASE_STARTED,
PURCHASE_COMPLETED,
EXPIRED
offerKey
RW
String
The offer key, which is an
alternate identifier for the offer
offerId
R
String
The offer ID, which typically is
equivalent to the authorization
ID
OL-28775-02
Types
Title Authorization
The title object encapsulates the title authorization attributes.
Name
Read/
Write
Type
Description
authorizationId
RW
String
The identifier string for the
authorization
authorizationType
RW
String
“SUBSCRIPTION”
“BUNDLE”
“SVOD”
“TVOD”
“PPV”
OL-28775-02
authorizationStatus
RW
String
Authorization status values,
which include:
PURCHASE_STARTED,
PURCHASE_COMPLETED,
EXPIRED
expirationDate
RW
String
dateTime
format
The expiration date
purchaseId
R
String
The purchase identifier
groupId
R
String
The group identifier
startDate
R
String
dateTime
format
The start date
deviceId
R
purchaseDate
R
String
dateTime
format
The purchase date
isViewed
R
boolean
Viewing status
isReported
R
boolean
Reporting status
userProfileId
R
String
The user profile identifier
rentalTime
RW
Integer
The rental time, in days
The device identifier
7
Types
Preferences
The preferences object encapsulates household personal identification numbers
(pins) and maximum values for devices, as well as the household credit limit.
Name
Read/
Write
Type
Description
purchasePin
RW
String
The household purchase pin
parentalPin
RW
String
The household parental pin
maxDeviceCount
RW
String
The maximum number of
devices in the household
maxCreditLimit
RW
String
The maximum credit limit for
the household
NPVRData
The network personal video recorder (NPVR data), which is only used in certain
environments, includes attributes to manage the behavior of an NPVR.
Name
8
Read/
Write
Type
Description
contentRetentionP RW
eriod
Integer
The number of days to retain
content
contentDeleteDate RW
DateTime
The date when content can
safely be removed from the
NPVR
npvrCapacity
RW
Integer
The capacity of the device
npvrTunerQuota
RW
Integer
The maximum number of
tuners for the device
OL-28775-02
HTTP Codes
HTTP Codes
Every REST HTTP command returns an HTTP code.
200 OK — This code is returned when a resource is successfully updated (PUT),
deleted (DELETE), or retrieved (GET).
201 Created — This code is returned when a resource is successfully created
(POST).
204 No Content — This code is returned when there is no content to provide.
400 Bad Request — This code is returned when a request cannot be fulfilled due
to bad syntax.
404 Not Found — This code is returned when an invalid resource is requested.
500 Internal Server Error — This code is returned when there is an error
detected.
OL-28775-02
9
Standard REST Response
Standard REST Response
All Create, Update, and Delete calls respond to the caller with the StandardResponse
object for the HTTP body. This response contains an errorMessage and a body. If
there is an error, the errorMessage field will be populated; otherwise it will be
empty. When a request is successful, the body field will contain more information.
StandardResponse Schema
<xs:element name="StandardResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string" minOccurs="1"
maxOccurs="1" />
<xs:element name="body" type="string" minOccurs="0"
maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
10
OL-28775-02
Get Response Objects
Get Response Objects
Each HTTP GET request contains an errorMessage and an appropriate object in the
HTTP body.
HouseholdResponse
The errorMessage will be empty if there is no error, or filled with an error message.
If there is no error, there will be a Household object.
<xs:element name="HouseholdResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string" minOccurs="1"
maxOccurs="1" />
<xs:element name="household" type="household" minOccurs="0"
maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
DeviceResponse
The errorMessage is empty if there is no error, or else it is filled with an error
message. If there is no error, there will be a Device object.
<xs:element name="DeviceResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string" minOccurs="1"
maxOccurs="1" />
<xs:element name="device" type="device" minOccurs="0"
maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
OL-28775-02
11
Get Response Objects
DevicesResponse
The errorMessage is empty if there is no error, or else it is filled with an error
message. If there is no error, there will be an object for multiple devices.
<xs:element name="DevicesResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string" minOccurs="1"
maxOccurs="1" />
<xs:element name="devices" type="devices" minOccurs="0"
maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
UserProfileResponse
The errorMessage is empty if there is no error, or else it is filled with an error
message. If there is no error, there will be a userProfile object.
<xs:element name="UserProfileResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string" minOccurs="1"
maxOccurs="1" />
<xs:element name="userProfile" type="userProfile"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
12
OL-28775-02
Get Response Objects
UserProfilesResponse
The errorMessage is empty if there is no error, or else it is filled with an error
message. If there is no error, there will be an object for multiple user profiles.
<xs:element name="UserProfilesResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string" minOccurs="1"
maxOccurs="1" />
<xs:element name="userProfiles" type="userProfiles"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
HouseholdSubscriptionResponse
The errorMessage is empty if there is no error, or else it is filled with an error
message. If there is no error, there will be a subscription object.
<xs:element name="HouseholdSubscriptionResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="subscription" type="subscription"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
OL-28775-02
13
Get Response Objects
HouseholdAuthorizationsResponse
The errorMessage is empty if there is no error, or else it is filled with an error
message. If there is no error, there will be a list of authorizations, which includes
both the subscription and title types.
<xs:element name="HouseholdAuthorizationsResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="authorizations"
type="authorizations" minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
CreateTitleAuthorizationResponse
The errorMessage is empty if there is no error, or else it is filled with an error
message. If there is no error, there will be a purchase ID populated in the response.
<xs:element name="CreateTitleAuthorizationResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="purchaseId" type="string"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
14
OL-28775-02
Get Response Objects
TitleAuthorizationResponse
This response object is used for a title authorization retrieval. The errorMessage is
empty if there is no error, or else it is filled with an error message. If there is no
error, there will be a title authorization populated in the response.
<xs:element name="TitleAuthorizationResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="titleAuthorization"
type="titleAuthorization" minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
TitleAuthorizationsResponse
This response object is used when all title authorizations for a household are
requested. The errorMessage is empty if there is no error, or else it is filled with an
error message. If there is no error, there will be a list of title authorizations populated
in the response.
<xs:element name="TitleAuthorizationsResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="titleAuthorizations"
type="titleAuthorizations" minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
OL-28775-02
15
Get Response Objects
EnabledServicesResponse
The errorMessage is empty if there is no error, or else it is filled with an error
message. If there is no error, there will be an enabled services object.
<xs:element name="EnabledServicesResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string" minOccurs="1"
maxOccurs="1" />
<xs:element name="enabledServices" type="enabledServices"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
LocaleResponse
The errorMessage is empty if there is no error, or else it is filled with an error
message. If there is no error, there will be a locale object.
<xs:element name="LocaleResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string" minOccurs="1"
maxOccurs="1" />
<xs:element name="locale" type="locale" minOccurs="0"
maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
16
OL-28775-02
Get Response Objects
NPVRDataResponse
The errorMessage is empty if there is no error, or else it is filled with an error
message. If there is no error, there will be an NPVR data object.
<xs:element name="NPVRDataResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string" minOccurs="1"
maxOccurs="1" />
<xs:element name="npvrData" type="npvrData" minOccurs="0"
maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
HouseholdPreferencesResponse
The errorMessage is empty if there is no error, or else it is filled with an error
message. If there is no error, there will be a preferences object.
<xs:element name="HouseholdPreferencesResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string" minOccurs="1"
maxOccurs="1" />
<xs:element name="preferences" type="preferences"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
OL-28775-02
17
REST Command Guidance and Examples
REST Command Guidance and Examples
This section contains details about how each REST command is used, as well as
example requests and responses. Some of the listed object attributes are created by
default. Others must be populated in order to appear in a GET response object.
Household Commands
CreateHousehold
A household can be thought of as an account. There can be multiple devices and
userProfiles associated with a household. The only required parameter for creating a
household is a unique identifier, the “householdId”.
To activate a household, set the operateStatus to ACTIVE and the
householdStatus to ACTIVATED.
To deactivate a household, set the operateStatus to INACTIVE and the
householdStatus to SUSPENDED.
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}
HTTP Command — POST
Usage — This command takes a householdId and any additional parameters
specified in the following table, as optional, to create a household. Devices can be
created on the fly and can be associated with the new household by populating the
device object(s) in the household definition payload. A user profile is created by
default when a new household is created. The same is true for certain household
attributes.
Payload
Household object
Mandatory/
Optional
Comments
householdStatus
O
The household status, which includes
the following options:
ACTIVATED, SUSPENDED. The default
value is ACTIVATED.
18
defaultUserId
O
ID of the default user in this household.
If this value is not specified, there is no
default applied.
operateStatus
O
The operational status, which includes
the following options: ACTIVE,
INACTIVE. The default value is
ACTIVE.
address
O
The address of the household
OL-28775-02
REST Command Guidance and Examples
Household object
Mandatory/
Optional
Comments
spendingLimit
O
The household spending limit
currentBalance
O
The household current balance
locale
O
The locale object
enabledServices
O
A list of strings that represent the
enabled services for the household
devices
O
A list of device objects that can be
created at the same time as the
household. Device entries included here
must not previously exist.
Response
Name
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
body
If successful, this attribute is populated
with a success message.
201 Created
400 Bad Request
500 Internal Server Error
Sample Request/Response: Create Household
POST
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123
Content-Type: text/xml
<?xml version="1.0" encoding="UTF-8"?>
<boa:CreateHousehold
xmlns:boa="http://protocols.cisco.com/spvtg/conductor/boa/comm
onapi" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<household>
<operateStatus>ACTIVE</operateStatus>
<householdStatus>ACTIVATED</householdStatus>
<enabledServices><service>VOD</service><service>PPV</service>
</enabledServices>
<spendingLimit>30</spendingLimit>
<currentBalance>10</currentBalance>
</household>
</boa:CreateHousehold>
OL-28775-02
19
REST Command Guidance and Examples
-- response -201 Created
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
252
Tue, 28 Jan 2014 17:47:02 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>successfully created resource
[testid123]</body></ns2:StandardResponse>
UpdateHousehold
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}
HTTP Command — PUT
Usage — The household ID is required in the URL, but any of the other fields that
follow can be included in the household object to be updated. The device list
attribute, which is supported in the create operation, is not supported in the update
operation.
Payload
Household object
Mandatory/
Optional
Comments
householdStatus
O
The household status, which includes
the following options:
ACTIVATED, SUSPENDED. The default
value is ACTIVATED.
20
defaultUserId
O
ID of the default user in this household.
If this value is not specified, there is no
default applied.
operateStatus
O
The operational status, which includes
the following options: ACTIVE,
INACTIVE. The default value is
ACTIVE.
address
O
The address of the household
spendingLimit
O
The household spending limit
currentBalance
O
The household current balance
locale
O
The locale object which includes a region
ID
enabledServices
O
A list of strings that represent the
enabled services for the household
OL-28775-02
REST Command Guidance and Examples
Response
Name
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
body
If successful, this attribute is populated
with a success message.
200 OK
400 Bad Request
404 Not Found
500 Internal Server Error
Sample Request/Response: Update Household
PUT
http://209.165.200.224:8080/BillingAdaptor/api/household/testid123
Content-Type: text/xml
<?xml version="1.0" encoding="UTF-8"?>
<boa:UpdateHousehold
xmlns:boa="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<household>
<operateStatus>INACTIVE</operateStatus>
<householdStatus>SUSPENDED</householdStatus>
<address>1600 Some Ave</address>
<locale>
<cmdcRegion>cmdc33</cmdcRegion>
<region>28</region>
</locale>
</household>
</boa:UpdateHousehold>
-- response -200 OK
Server: Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
252
Tue, 28 Jan 2014 20:27:28 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>successfully updated resource
[testid123]</body></ns2:StandardResponse>
OL-28775-02
21
REST Command Guidance and Examples
Sample Request/Response: Update Household to Clear Enabled Services
PUT
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123
Content-Type: text/xml
<boa:UpdateHousehold
xmlns:boa="http://protocols.cisco.com/spvtg/conductor/boa/comm
onapi" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<household>
<enabledServices/>
</household>
</boa:UpdateHousehold>
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
application/xml
Content-Length:
Date:
249
Wed, 12 Mar 2014 21:08:46 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>successfully updated resource
[testid123]</body></ns2:StandardResponse>
DeleteHousehold
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}
HTTP Command — DELETE
Usage — This command deletes the household with the specified ID.
Payload — N/A
Response
Name
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
body
If successful, this attribute is populated
with a success message.
22
200 OK
400 Bad Request
404 Not Found
500 Internal Server Error
OL-28775-02
REST Command Guidance and Examples
Sample Request/Response: Delete Household
DELETE
http://209.165.200.224:8080/BillingAdaptor/api/household/testid123
-- response -200 OK
Server: Apache-Coyote/1.1
Content-Type:
application/xml
Content-Length:
Date:
252
Mon, 13 Jan 2014 23:10:27 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>successfully deleted resource
[testid123]</body></ns2:StandardResponse>
GetHousehold
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}
HTTP Command — GET
Usage — This command retrieves the household with the specified ID.
Payload — N/A
Response
Name
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
householdId
The unique identifier of the household
200 OK
400 Bad Request
404 Not Found
500 Internal Server Error householdStatus
The household status, which includes
the following options:
ACTIVATED, SUSPENDED. The default
value is ACTIVATED.
OL-28775-02
createDate
The date the household was created.
This attribute is controlled externally
and is read-only.
lastUpdateDate
The date when the household was last
updated. This attribute is controlled
externally and is read-only.
spendingLimit
The household spending limit
23
REST Command Guidance and Examples
Response
Name
Comments
currentBalance
The household current balance
locale
The locale object, which includes a
region ID
enabledServices
The list of strings that represent the
enabled services for the household
devices
The set of devices associated with the
household.
userProfiles
The set of user profiles associated with
the household. A user profile is created
by default, so there will always be at
least one user associated with the
household.
authorizations
The set of authorizations for the
household.
preferences
The set of preferences for the household
npvrData
The npvr attributes, which are only
applicable to certain environments
Sample Request/Response: Get Household
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
24
2065
Wed, 29 Jan 2014 00:05:33 GMT
OL-28775-02
REST Command Guidance and Examples
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><ns2:HouseholdResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><household><householdId>testid123</householdId><househ
oldStatus>ACTIVATED</householdStatus><address>1600 Pennsylvania
Ave</address><devices><device><deviceId>dev1</deviceId><type>MANAGED</type><
ipAddress>##.#.#.#</ipAddress><createDate>2014-0128T15:52:29.000Z</createDate><lastUpdateDate>2014-0128T15:52:29.000Z</lastUpdateDate><operateStatus>ACTIVE</operateStatus><prese
nceStatus>OFFLINE</presenceStatus></device><device><deviceId>dev2</deviceId>
<type>MANAGED</type><bssFullType>MANAGED</bssFullType><ipAddress>10.1.1.1</i
pAddress><createDate>2014-0128T18:51:27.000Z</createDate><lastUpdateDate>2014-0128T18:51:27.000Z</lastUpdateDate><operateStatus>ACTIVE</operateStatus><prese
nceStatus>OFFLINE</presenceStatus></device></devices><userProfiles><userProf
ile><userProfileId>testid123_0</userProfileId><favoriteChannelsUrl>http://20
9.165.200.224:6040/upm/households/testid123/userProfiles/testid123_0/favorit
eChannels</favoriteChannelsUrl><priority>0</priority><createDate>2014-0128T12:47:02.000Z</createDate><lastUpdateDate>2014-0128T12:47:02.000Z</lastUpdateDate><operateStatus>INACTIVE</operateStatus><pre
senceStatus>OFFLINE</presenceStatus><isDefault>true</isDefault></userProfile
></userProfiles><createDate>2014-0128T12:47:02.000Z</createDate><lastUpdateDate>2014-0128T18:59:10.000Z</lastUpdateDate><operateStatus>ACTIVE</operateStatus><autho
rizations/><locale><region>Southeast</region><cmdcRegion>cmdc15</cmdcRegion>
<city>19</city><adZone>az17</adZone><postalCode>30030</postalCode><marketing
Target>mt18</marketingTarget><blackoutZone>bz11</blackoutZone></locale><enab
ledServices><service>VOD</service><service>PPV</service></enabledServices><n
pvrData/><preferences><purchasePin>0</purchasePin><parentalPin>12345</parent
alPin><maxDeviceCount>5</maxDeviceCount></preferences><spendingLimit>15</spe
ndingLimit><currentBalance>10</currentBalance></household></ns2:HouseholdRes
ponse>
OL-28775-02
25
REST Command Guidance and Examples
GetEnabledServicesByHousehold
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
enabledServices
HTTP Command — GET
Usage — This command retrieves the enabled services for the specified household.
Payload — N/A
Response
Name
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
enabledServices
The list of enabled services
200 OK
400 Bad Request
404 Not Found
500 Internal Server Error
Sample Request/Response: Get Enabled Services By Household
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testid123/e
nabledServices
-- response -200 OK
Server: Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
291
Tue, 28 Jan 2014 20:31:30 GMT
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><ns2:EnabledServicesResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><enabledServices><service>VOD</service><service>PPV</s
ervice></enabledServices></ns2:EnabledServicesResponse>
26
OL-28775-02
REST Command Guidance and Examples
UpdateHouseholdParentalPin
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
preference/parentalPin/{pinValue}
HTTP Command — PUT
Usage — This command facilitates the setting of the parental pin for the specified
household.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
body
If successful, this attribute is populated
with a success message.
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Update Household Parental Pin
PUT
http://209.165.200.224:8080/BillingAdaptor/api/household/testid123/p
reference/parentalPin/12345
Content-Type: text/xml
-- response -200 OK
Server: Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
279
Mon, 13 Jan 2014 23:17:13 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>successfully updated Preference parentalPin for
resource [testid123]</body></ns2:StandardResponse>
OL-28775-02
27
REST Command Guidance and Examples
GetHouseholdParentalPin
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
parentalPin
HTTP Command — GET
Usage — This command facilitates the retrieval of the parental pin for the specified
household.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
parentalPin
The parental pin value
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get Household Parental Pin
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testid123/p
reference/parentalPin
-- response -200 OK
Server: Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
281
Mon, 13 Jan 2014 23:17:47 GMT
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><ns2:HouseholdPreferencesResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><preferences><parentalPin>12345</parentalPin></prefere
nces></ns2:HouseholdPreferencesResponse>
28
OL-28775-02
REST Command Guidance and Examples
UpdateHouseholdPurchasePin
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
preference/purchasePin/{pinValue}
HTTP Command — PUT
Usage — This command facilitates the setting of the purchase pin for the specified
household.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
body
If successful, this attribute is populated
with a success message.
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Update Household Purchase Pin
PUT
http://209.165.200.224:8080/BillingAdaptor/api/household/testid123/p
reference/purchasePin/12345
Content-Type: text/xml
-- response -200 OK
Server: Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
279
Mon, 13 Jan 2014 23:18:31 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>successfully updated Preference purchasePin for
resource [testid123]</body></ns2:StandardResponse>
OL-28775-02
29
REST Command Guidance and Examples
GetHouseholdPurchasePin
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
preference/purchasePin
HTTP Command — GET
Usage — This command facilitates the retrieval of the purchase pin for the specified
household.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
purchasePin
The purchase pin value for the
household
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get Household Purchase Pin
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/preference/purchasePin
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
281
Mon, 13 Jan 2014 23:19:00 GMT
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><ns2:HouseholdPreferencesResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><preferences><purchasePin>12345</purchasePin></prefere
nces></ns2:HouseholdPreferencesResponse>
30
OL-28775-02
REST Command Guidance and Examples
UpdateHouseholdMaxDeviceCount
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
preference/maxDeviceCount/{deviceCount}
HTTP Command — PUT
Usage — This command facilitates the setting of the maximum number of devices
for the specified household.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
body
If successful, this attribute is populated
with a success message.
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Update Household Max Device Count
PUT
http://209.165.200.224:8080/BillingAdaptor/api/household/testid123/p
reference/maxDeviceCount/5
Content-Type: text/xml
-- response -200 OK
Server: Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
282
Mon, 13 Jan 2014 23:20:31 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>successfully updated Preference maxDeviceCount
for resource [testid123]</body></ns2:StandardResponse>
OL-28775-02
31
REST Command Guidance and Examples
GetHouseholdMaxDeviceCount
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
preference/maxDeviceCount
HTTP Command — GET
Usage — This command facilitates the retrieval of the maximum number of devices
for the specified household.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
maxDeviceCount
The maximum number of devices
allowed in the household
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get Household Max Device Count
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testid123/p
reference/maxDeviceCount
-- response -200 OK
Server: Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
283
Mon, 13 Jan 2014 23:20:55 GMT
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><ns2:HouseholdPreferencesResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><preferences><maxDeviceCount>5</maxDeviceCount></prefe
rences></ns2:HouseholdPreferencesResponse>
32
OL-28775-02
REST Command Guidance and Examples
UpdateHouseholdMaxCreditLimit
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
preference/maxCreditLimit/{creditLimit}
HTTP Command — PUT
Usage — This command facilitates the setting of the maximum credit limit for the
specified household.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
body
If successful, this attribute is populated
with a success message.
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Update Household Max Credit Limit
PUT
http://209.165.200.224:8080/BillingAdaptor/api/household/testid123/p
reference/maxCreditLimit/10
Content-Type: text/xml
-- response -200 OK
Server: Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
282
Mon, 13 Jan 2014 23:21:39 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>successfully updated Preference maxCreditLimit
for resource [testid123]</body></ns2:StandardResponse>
OL-28775-02
33
REST Command Guidance and Examples
GetHouseholdMaxCreditLimit
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
preference/maxCreditLimit
HTTP Command — GET
Usage — This command facilitates the retrieval of the credit limit for the specified
household.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
maxCreditLimit
The credit limit for the household
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get Household Max Credit Limit
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testid123/p
reference/maxCreditLimit
-- response -200 OK
Server: Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
284
Mon, 13 Jan 2014 23:22:02 GMT
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><ns2:HouseholdPreferencesResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><preferences><maxCreditLimit>10</maxCreditLimit></pref
erences></ns2:HouseholdPreferencesResponse>
34
OL-28775-02
REST Command Guidance and Examples
UpdateHouseholdSpendingLimit
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
spendingLimit/{spendingLimit}
HTTP Command — PUT
Usage — This command facilitates the setting of the household spending limit.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Update Household Spending Limit
PUT
http://209.165.200.224:8080/BillingAdaptor/api/household/testid123/s
pendingLimit/15
Content-Type: text/xml
-- response -200 OK
Server: Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
198
Tue, 28 Jan 2014 23:58:53 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage></ns2:StandardResponse>
OL-28775-02
35
REST Command Guidance and Examples
GetHouseholdSpendingLimit
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
spendingLimit
HTTP Command — GET
Usage — This command facilitates the retrieval of the household spending limit.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
body
The household spending limit value
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get Household Spending Limit
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testid123/s
pendingLimit
-- response -200 OK
Server: Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
213
Wed, 29 Jan 2014 00:02:22 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>15</body></ns2:StandardResponse>
36
OL-28775-02
REST Command Guidance and Examples
UpdateHouseholdCurrentBalance
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
currentBalance/{currentBalance}
HTTP Command — PUT
Usage — This command facilitates the setting of the household current balance.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Update Household Current Balance
PUT
http://209.165.200.224:8080/BillingAdaptor/api/household/testid123/c
urrentBalance/10
Content-Type: text/xml
-- response -200 OK
Server: Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
198
Tue, 28 Jan 2014 23:59:10 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage></ns2:StandardResponse>
OL-28775-02
37
REST Command Guidance and Examples
GetHouseholdCurrentBalance
URL —
http://<host:port>/BillingAdaptor/api/household/{householdId}/currentBalance
HTTP Command — GET
Usage — This command facilitates the retrieval of the household current balance.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
body
The household current balance value
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get Household Current Balance
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testid123/c
urrentBalance
-- response -200 OK
Server: Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
213
Wed, 29 Jan 2014 00:04:42 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>10</body></ns2:StandardResponse>
38
OL-28775-02
REST Command Guidance and Examples
GetHouseholdIds
URL — http://<host:port>/BillingAdaptor/api/householdIds
HTTP Command — GET
Usage — This command facilitates the retrieval of all stored household IDs.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
householdIds
The list of all household IDs
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get Household ID List
GET
http://209.165.200.224:8080/BillingAdaptor/api/householdIds
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
311
Tue, 28 Jan 2014 20:41:41 GMT
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><ns2:HouseholdIdsResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><householdIds><id>VHH_cpems_cpekeychains</id><id>VHH_c
pems_cpetypes</id><id>testid123</id></householdIds></ns2:HouseholdIdsRespons
e>
OL-28775-02
39
REST Command Guidance and Examples
Device Commands
CreateDevice
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
device/{deviceId}
HTTP Command — POST
Usage — This command takes a deviceId and any additional attributes specified in
the following table as optional to create a device. The device is created within the
context of the household.
Payload
40
Name/Device
Object
Mandatory/
Optional
Comments
auxDeviceId
O
The auxiliary device ID
onlineUserId
O
The online user of this device
bssFullType
O
The device type, which includes the
following options: MANAGED,
UNMANAGED
profile
O
A profile name defined by the user
operateStatus
O
The operational status, which
includes the following options:
ACTIVE, INACTIVE. The default
value is ACTIVE.
jid
O
The Jabber ID of this device, which
must be unique
macAddress
O
The MAC address of this device
serialNo
O
The serial number of this device
ipAddress
O
The IP address of this device
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
body
If successful, this attribute is populated
with a success message.
201 Created
400 Bad Request
500 Internal Server
Error
OL-28775-02
REST Command Guidance and Examples
Sample Request/Response: Create Device
POST
http://209.165.200.224:8080/BillingAdaptor/api/household/testid123/d
evice/dev2
Content-Type: text/xml
<?xml version="1.0" encoding="UTF-8"?>
<boa:CreateDevice
xmlns:boa="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<device>
<ipAddress>209.165.200.225</ipAddress>
<bssFullType>MANAGED</bssFullType>
</device>
</boa:CreateDevice>
-- response -201 Created
Server: Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
279
Tue, 28 Jan 2014 23:51:27 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>successfully created resource
[HouseholdId=testid123, DeviceId=dev2]</body></ns2:StandardResponse>
OL-28775-02
41
REST Command Guidance and Examples
Sample Request/Response: Create Device Where Household Doesn’t Exist
POST
http://209.165.200.224:8080/BillingAdaptor/api/household/testid1_NOT
EXIST/device/dev1
Content-Type: text/xml
<?xml version="1.0" encoding="UTF-8"?>
<boa:CreateDevice
xmlns:boa="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<device>
<deviceId>dev1</deviceId>
<ipAddress>209.165.200.225</ipAddress>
</device>
</boa:CreateDevice>
-- response -404 Not Found
Server: Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
287
Mon, 13 Jan 2014 23:25:10 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage>Request processing failed. Household with id=testid1_NOTEXIST does
not exist</errorMessage><body></body></ns2:StandardResponse>
42
OL-28775-02
REST Command Guidance and Examples
UpdateDevice
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
device/{deviceId}
HTTP Command — PUT
Usage — This command takes the deviceId in the URL and any additional
parameters specified in the following table, as optional, to update a device.
Payload
Name/Device
Object
Mandatory/
Optional
Comments
auxDeviceId
O
The auxiliary device ID
onlineUserId
O
The online user of this device
bssFullType
O
The device type, which includes the
following options: MANAGED,
UNMANAGED
profile
O
A profile name defined by the user
operateStatus
O
The operational status, which
includes the following options:
ACTIVE, INACTIVE. The default
value is ACTIVE.
jid
O
The Jabber ID of this device, which
must be unique
macAddress
O
The MAC address of this device
serialNo
O
The serial number of this device
ipAddress
O
The IP address of this device
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
body
If successful, this attribute is populated
with a success message.
OL-28775-02
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
43
REST Command Guidance and Examples
Sample Request/Response: Update Device
PUT
http://209.165.200.224:8080/BillingAdaptor/api/household/testid123/d
evice/dev1
Content-Type: text/xml
<?xml version="1.0" encoding="UTF-8"?>
<boa:UpdateDevice
xmlns:boa="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<device>
<ipAddress>209.165.200.225</ipAddress>
</device>
</boa:UpdateDevice>
-- response -200 OK
Server: Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
247
Mon, 13 Jan 2014 23:27:38 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>successfully updated resource
[dev1]</body></ns2:StandardResponse>
44
OL-28775-02
REST Command Guidance and Examples
DeleteDevice
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
device/{deviceId}
HTTP Command — DELETE
Usage — This command deletes the device with the specified ID.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
body
If successful, this attribute is populated
with a success message.
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: DeleteDevice
DELETE
http://209.165.200.224:8080/BillingAdaptor/api/household/testid123/d
evice/dev1
-- response -200 OK
Server: Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
279
Mon, 13 Jan 2014 23:28:30 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>successfully deleted resource
[HouseholdId=testid123, DeviceId=dev1]</body></ns2:StandardResponse>
OL-28775-02
45
REST Command Guidance and Examples
GetDevice
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
device/{deviceId}
HTTP Command — GET
Usage — This command retrieves the device with the specified ID.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
deviceId
The device identifier
auxDeviceId
The auxiliary device ID
operateStatus
The operational status, which includes
the following options: ACTIVE,
INACTIVE. The default value is
ACTIVE.
jid
The Jabber ID of this device, which
must be unique
macAddress
The MAC address of this device
ipAddress
The IP address of this device
lastUpdateDate
The time when the device was last
updated
bssFullType
The BSS full type; values include:
MANAGED, UNMANAGED
deviceType
The device type; derived from
bssFullType
deviceFeatures
The list of device features; derived from
bssFullType
deviceCategory
The device category; derived from
bssFullType
46
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
OL-28775-02
REST Command Guidance and Examples
Sample Request/Response: Get Device
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/device/dev2
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
504
Tue, 28 Jan 2014 23:53:51 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:DeviceResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><device><deviceId>dev2</deviceId><type>MANAGED</type><
bssFullType>MANAGED</bssFullType><ipAddress>209.165.200.225</ipAddress><crea
teDate>2014-01-28T18:51:27.000Z</createDate><lastUpdateDate>2014-0128T18:51:27.000Z</lastUpdateDate><operateStatus>ACTIVE</operateStatus><prese
nceStatus>OFFLINE</presenceStatus></device></ns2:DeviceResponse>
Sample Request/Response: Get Device Where Device Does Not Exist
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/device/dev2
-- response -404 Not Found
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
294
Mon, 13 Jan 2014 23:29:42 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:DeviceResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage>Resource [HouseholdId=testid123, DeviceId=dev2] does not
exist</errorMessage><device><deviceId></deviceId></device></ns2:DeviceRespon
se>
OL-28775-02
47
REST Command Guidance and Examples
GetHouseholdDevices
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
devices
HTTP Command — GET
Usage — This command retrieves all devices for the specified household.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
devices
The list of device objects associated
with the household
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get Household Devices
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/devices
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
1111
Mon, 13 Jan 2014 23:31:04 GMT209.165.200.224
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:DevicesResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><devices><device><deviceId>dev1</deviceId><type>MANAGE
D</type><zipCode>10101</zipCode><ipAddress>10.1.1.1</ipAddress><lastPresence
OnlineTime>1969-1231T23:59:59.999Z</lastPresenceOnlineTime><lastPresenceOfflineTime>1969-1231T23:59:59.999Z</lastPresenceOfflineTime><createDate>2014-0113T18:00:50.000Z</createDate><lastUpdateDate>2014-0113T18:04:14.000Z</lastUpdateDate><operateStatus>ACTIVE</operateStatus><prese
nceStatus>OFFLINE</presenceStatus></device><device><deviceId>dev2</deviceId>
<type>MANAGED</type><zipCode>10103</zipCode><ipAddress>209.165.200.225</ipAd
dress><lastPresenceOnlineTime>1969-1231T23:59:59.999Z</lastPresenceOnlineTime><lastPresenceOfflineTime>1969-1231T23:59:59.999Z</lastPresenceOfflineTime><createDate>2014-0113T18:07:01.000Z</createDate><lastUpdateDate>2014-0113T18:07:31.000Z</lastUpdateDate><operateStatus>ACTIVE</operateStatus><prese
nceStatus>OFFLINE</presenceStatus></device></devices></ns2:DevicesResponse>
48
OL-28775-02
REST Command Guidance and Examples
UserProfile Commands
CreateUserProfile
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
userProfile
HTTP Command — POST
Usage — This command takes a household ID and any additional user attributes
specified in teh following table as optional to create a user profile. A unique user
profile ID is generated externally so a user profile can be created with just an empty
user profile object. The generated user profile ID is included in the response for a
successful create operation. The format for this ID is {householdId}_{NUM}, where
the NUM is incremented for each new user profile.
Payload
OL-28775-02
UserProfile
Object
Mandatory/
Optional
Comments
operateStatus
O
The operational status, which includes the
following options: ACTIVE, INACTIVE.
The default value is ACTIVE.
role
O
The role of the user, which includes the
following options: ADMIN, NORMAL
jid
O
The Jabber ID of this device, which must be
unique
displayName
O
The user’s display name
firstName
O
The user’s first name
lastName
O
The user’s last name
email
O
The user’s email
phoneNumber
O
The user’s phone number
priority
O
The relative priority of the user, which has a
range of 0-10 with 0 as the highest priority
userId
O
The user ID. This is different than the user
profile Id, which is controlled externally
and therefore read-only.
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
49
REST Command Guidance and Examples
Response
Name/Object
Comments
body
If successful, this attribute is populated with
a success message that includes the
generated user profile ID.
201 Created
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Create User Profile
POST
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/userProfile
Content-Type: text/xml
<?xml version="1.0" encoding="UTF-8"?>
<boa:CreateUserProfile
xmlns:boa="http://protocols.cisco.com/spvtg/conductor/boa/comm
onapi" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<userProfile>
<operateStatus>ACTIVE</operateStatus>
<role>NORMAL</role>
<displayName>Brutus</displayName>
</userProfile>
</boa:CreateUserProfile>
-- response -201 Created
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
291
Mon, 13 Jan 2014 23:33:18 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>successfully created resource
[HouseholdId=testid123,
userProfileId=testid123_1]</body></ns2:StandardResponse>
50
OL-28775-02
REST Command Guidance and Examples
UpdateUserProfile
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
userProfile/{userProfileId}
HTTP Command — PUT
Usage — An update to the user profile requires the household ID, the user profile
ID, and any of the optional attributes shown in the following table.
Payload
UserProfile
Object
Mandatory/
Optional
Comments
operateStatus
O
The operational status, which includes the
following options: ACTIVE, INACTIVE.
The default value is ACTIVE.
role
O
The role of the user, which includes the
following options: ADMIN, NORMAL
jid
O
The Jabber ID of this device, which must be
unique
displayName
O
The user’s display name
firstName
O
The user’s first name
lastName
O
The user’s last name
email
O
The user’s email
phoneNumber
O
The user’s phone number
priority
O
The relative priority of the user, which has a
range of 0-10 with 0 as the highest priority
userId
O
The user ID. This is different than the user
profile Id, which is controlled externally
and therefore read-only.
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
body
If successful, this attribute is populated
with a success message that includes
the generated user profile ID.
OL-28775-02
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
51
REST Command Guidance and Examples
Sample Request/Response: Update User Profile
PUT
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/userProfile/testid123_1
Content-Type: text/xml
<?xml version="1.0" encoding="UTF-8"?>
<boa:UpdateUserProfile
xmlns:boa="http://protocols.cisco.com/spvtg/conductor/boa/comm
onapi" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<userProfile>
<role>ADMIN</role>
<firstName>FIRSTNAME</firstName>
<lastName>LASTNAME</lastName>
<email>[email protected]</email>
</userProfile>
</boa:UpdateUserProfile>
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
254
Mon, 13 Jan 2014 23:34:57 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>successfully updated resource
[testid123_1]</body></ns2:StandardResponse>
52
OL-28775-02
REST Command Guidance and Examples
DeleteUserProfile
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
userProfile/{userProfileId}
HTTP Command — DELETE
Usage — This command deletes the user profile identified by its ID and its
associated household ID.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
body
If successful, this attribute is populated
with a success message.
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request Response: Delete User Profile
DELETE
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/userProfile/testid123_2
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
291
Mon, 13 Jan 2014 23:39:43 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>successfully deleted resource
[HouseholdId=testid123,
UserProfileId=testid123_2]</body></ns2:StandardResponse>
OL-28775-02
53
REST Command Guidance and Examples
GetUserProfile
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
userProfile/{userProfileId}
HTTP Command — GET
Usage — To retrieve a user profile, specify its user profile ID and associated
household ID in the URL.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
userProfileId
The user profile identifier
operateStatus
The operational status, which includes
the following options: ACTIVE,
INACTIVE. The default value is
ACTIVE.
role
The role of the user, which includes the
following options: ADMIN, NORMAL
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
favoriteChannelsUrl The URL to access the user’s favorite
channels
54
displayName
The user’s display name
priority
The relative priority of the user, which
has a range of 0-10 with 0 as the highest
priority
userId
The user ID. This is not the user profile
ID, which is controlled externally and is
therefore read-only.
lastUpdateDate
The last update time of the user profile.
This attribute is controlled externally
and is therefore read-only.
presenceStatus
The current presence status of the user
profile, which is either ONLINE or
OFFLINE. This attribute is controlled
externally and is therefore read-only.
OL-28775-02
REST Command Guidance and Examples
Sample Request/Response: Get User Profile
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/userProfile/testid123_1
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
733
Mon, 13 Jan 2014 23:36:49 GMT
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><ns2:UserProfileResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><userProfile><userProfileId>testid123_1</userProfileId
><favoriteChannelsUrl>http://209.165.200.225:6040/upm/userProfiles/testid123
_1/favoriteChannels</favoriteChannelsUrl><displayName>Brutus</displayName><e
mail>[email protected]</email><firstName>FIRSTNAME</firstName><lastName>LASTN
AME</lastName><role>ADMIN</role><priority>0</priority><createDate>2014-0113T18:09:54.000Z</createDate><lastUpdateDate>2014-0113T18:11:33.000Z</lastUpdateDate><operateStatus>ACTIVE</operateStatus><prese
nceStatus>OFFLINE</presenceStatus></userProfile></ns2:UserProfileResponse>
OL-28775-02
55
REST Command Guidance and Examples
GetHouseholdUserProfiles
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
userProfiles
HTTP Command — GET
Usage — This command retrieves all user profiles for the specified household.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
userProfiles
The list of user profile objects associated
with the household.
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get Household User Profiles
GET http://209.165.200.224:8080/BillingAdaptor/api/
householdid/testid123/userProfiles
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
56
1744
Tue, 14 Jan 2014 17:43:00 GMT
OL-28775-02
REST Command Guidance and Examples
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><ns2:UserProfilesResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><userProfiles><userProfile><userProfileId>testid123_2<
/userProfileId><favoriteChannelsUrl>http://209.165.200.225:6040/upm/userProf
iles/testid123_2/favoriteChannels</favoriteChannelsUrl><displayName>Chris</d
isplayName><role>NORMAL</role><priority>0</priority><userId>testid123_2</use
rId><createDate>2014-01-14T17:42:26.000Z</createDate><lastUpdateDate>20140114T17:42:26.000Z</lastUpdateDate><operateStatus>ACTIVE</operateStatus><jid>t
[email protected]</jid><presenceStatus>OFFLINE</presenceStatus></user
Profile><userProfile><userProfileId>testid123_1</userProfileId><favoriteChan
nelsUrl>http://10.90.186.203:6040/upm/userProfiles/testid123_1/favoriteChann
els</favoriteChannelsUrl><displayName>Brutus</displayName><role>NORMAL</role
><priority>0</priority><userId>testid123_1</userId><createDate>2014-0114T17:42:08.000Z</createDate><lastUpdateDate>2014-0114T17:42:08.000Z</lastUpdateDate><operateStatus>ACTIVE</operateStatus><jid>t
[email protected]</jid><presenceStatus>OFFLINE</presenceStatus></user
Profile><userProfile><userProfileId>testid123_0</userProfileId><favoriteChan
nelsUrl>http://10.90.186.203:6040/upm/households/testid123/userProfiles/test
id123_0/favoriteChannels</favoriteChannelsUrl><priority>0</priority><userId>
testid123_0</userId><createDate>2014-0114T17:30:07.000Z</createDate><lastUpdateDate>2014-0114T17:30:07.000Z</lastUpdateDate><operateStatus>INACTIVE</operateStatus><jid
>[email protected]</jid><presenceStatus>OFFLINE</presenceStatus><isD
efault>true</isDefault></userProfile></userProfiles></ns2:UserProfilesRespon
se>
Authorization Commands
This portion of the API deals with household level authorizations. There are two
types of household authorizations supported in the BOA: subscription
authorizations and title authorizations.
CreateSubscriptionAuthorization
URL —
http://<host:port>/BillingAdaptor/api/household/{householdId}/authorization/s
ubscription/{authorizationId}
HTTP Command — POST
Usage — This command takes the specified authorization ID in the URL and the
type in the payload to create a subscription authorization.
Payload
OL-28775-02
Subscription
Authorization
Object
Mandatory/
Optional
Comments
authorizationType
O
The type of authorization,
which, for a subscription
authorization, includes:
SUBSCRIPTION, SVOD
57
REST Command Guidance and Examples
Subscription
Authorization
Object
Mandatory/
Optional
Comments
authorizationStatus
O
The current status of the
authorization, which
includes the following
options:
PURCHASE_STARTED,
PURCHASE_COMPLETED
, EXPIRED
offerKey
O
The offer key value, which
is an alternate offer
identifier
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
body
If successful, this attribute is populated
with a success message.
201 Created
400 Bad Request
500 Internal Server
Error
Sample Request/Response: Create Subscription Authorization
POST
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/authorization/subscription/100
Content-Type: text/xml
<boa:CreateHouseholdSubscription
xmlns:boa="http://protocols.cisco.com/spvtg/conductor/boa/comm
onapi" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<subscription>
<authorizationType>SUBSCRIPTION</authorizationType>
</subscription>
</boa:CreateHouseholdSubscription>
-- response -201 Created
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
58
260
Tue, 07 Jan 2014 21:50:24 GMT
OL-28775-02
REST Command Guidance and Examples
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>successfully created resource [100,
SUBSCRIPTION]</body></ns2:StandardResponse>
UpdateSubscriptionAuthorization
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
authorization/subscription/{authorizationId}
HTTP Command — PUT
Usage — This command takes the specified authorization ID in the URL and the
type in the payload to create a subscription authorization.
Payload
Subscription
Authorization
Object
Mandatory/
Optional
Comments
authorizationType
O
The type of authorization,
which, for a subscription
authorization,includes:
SUBSCRIPTION, SVOD
authorizationStatus
O
The current status of the
authorization, which
includes the following
options:
PURCHASE_STARTED,
PURCHASE_COMPLETED
, EXPIRED
offerKey
O
The offer key value, which
is an alternate offer
identifier
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
body
If successful, this attribute is populated
with a success message.
OL-28775-02
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
59
REST Command Guidance and Examples
Sample Request/Response: Create Subscription Authorization
PUT
http://209.165.200.224:8080/BillingAdaptor/api/household/testid123/a
uthorization/subscription/100
Content-Type: text/xml
<boa:UpdateHouseholdSubscription
xmlns:boa="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<subscription>
<authorizationType>SUBSCRIPTION</authorizationType>
<offerKey>subPkg123</offerKey>
<authorizationStatus>PURCHASE_COMPLETED</authorizationStatus>
</subscription>
</boa:UpdateHouseholdSubscription>
-- response -200 OK
Server: Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
257
Mon, 17 Mar 2014 20:29:59 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>successfully updated authorization with ID
100</body></ns2:StandardResponse>
60
OL-28775-02
REST Command Guidance and Examples
DeleteSubscriptionAuthorization
URL —
http://<host:port>/BillingAdaptor/api/household/{householdId}/authorization/s
ubscription/{authorizationId}
HTTP Command — DELETE
Usage — This command deletes the subscription authorization by specifying both its
associated household Id and its authorization ID.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
body
If successful, this attribute is populated
with a success message.
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Delete Subscription Authorization
DELETE
http://209.165.200.224:8080/BillingAdaptor/api/household/
testid123/authorization/200
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
282
Tue, 07 Jan 2014 21:55:34 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>successfully deleted resource
[HouseholdId=ehTest, AuthorizationId=200]</body></ns2:StandardResponse>
OL-28775-02
61
REST Command Guidance and Examples
GetSubscriptionAuthorization
URL —
http://<host:port>/BillingAdaptor/api/household/{householdId}/authorization/s
ubscription/{authorizationId}
HTTP Command — GET
Usage — To retrieve a subscription authorization, specify its authorization ID and
associated household ID in the URL.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
authorizationId
The authorization ID
authorizationType
The type of authorization, which
includes the following options:
SUBSCRIPTION, BUNDLE, SVOD,
TVOD, PPV
authorizationStatus
The current status of the authorization,
which includes the following options:
PURCHASE_STARTED,
PURCHASE_COMPLETED, EXPIRED
offerId
The offer identifier, which is typically
the same as the authorization ID
offerKey
The offer key value, which is an
alternate offer identifier
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get Subscription Authorization
GET http://209.165.200.224:8080/BillingAdaptor/api/household/
testid123/authorization/subscription/100
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
62
342
Tue, 07 Jan 2014 21:51:26 GMT
OL-28775-02
REST Command Guidance and Examples
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><ns2:HouseholdSubscriptionResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><subscription><authorizationId>100</authorizationId><a
uthorizationType>SUBSCRIPTION</authorizationType></subscription></ns2:Househ
oldSubscriptionResponse>
GetSubscriptionAuthorizations
URL —
http://<host:port>/BillingAdaptor/api/household/{householdId}/authorization/s
ubscriptions
HTTP Command — GET
Usage — This API provides access to the list of all subscription authorizations for
the specified household.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
authorizations
The list of subscription objects
associated with the specified household
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get Subscription Authorizations
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/authorization/subscriptions
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
496
Wed, 29 Jan 2014 14:55:18 GMT
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><ns2:HouseholdAuthorizationsResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><authorizations><subscription><authorizationId>100</au
thorizationId><authorizationType>SUBSCRIPTION</authorizationType></subscript
ion><subscription><authorizationId>33</authorizationId><authorizationType>SU
BSCRIPTION</authorizationType></subscription></authorizations></ns2:Househol
dAuthorizationsResponse>
OL-28775-02
63
REST Command Guidance and Examples
CreateTitleAuthorization
URL —
http://<host:port>/BillingAdaptor/api/household/{householdId}/authorization/t
itle
HTTP Command — POST
Usage — This command takes the specified household ID and the attributes in the
payload to create a title authorization. Note that there is no authorization ID
provided in the URL and that a purchase ID is returned from the create operation.
Payload
64
Title Authorization
Object
Mandatory/
Optional
Comments
authorizationId
M
The authorization ID
expirationDate
M
The expiration date of the
title authorization
authorizationType
O
The type of authorization,
which, for a title
authorization, includes:
TVOD, PPV, BUNDLE
authorizationStatus
O
The authorization status,
which includes the
following options:
PURCHASE_STARTED,
PURCHASE_COMPLETED,
EXPIRED
rentalTime
O
The rental time duration in
days
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
purchaseId
If successful, the purchase ID is
provided in the response. This value is
used for updating, retrieving, or
deleting an individual title
authorization.
201 Created
400 Bad Request
500 Internal Server
Error
OL-28775-02
REST Command Guidance and Examples
Sample Request/Response: Create Title Authorization
POST
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/authorization/title
Content-Type: text/xml
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><ns2:CreateTitleAuthorization
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/comm
onapi"><titleAuthorization><authorizationId>1991</authorizatio
nId><authorizationStatus>ACTIVATED</authorizationStatus><expir
ationDate>2031-1231T12:00:00Z</expirationDate><rentalTime>3</rentalTime></title
Authorization></ns2:CreateTitleAuthorization>
-- response -201 Created
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
291
Tue, 07 Jan 2014 21:22:33 GMT
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><ns2:CreateTitleAuthorizationResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><purchaseId>92e891e8-6e7d-4355-b2c182909fac0a21</purchaseId></ns2:CreateTitleAuthorizationResponse>
OL-28775-02
65
REST Command Guidance and Examples
UpdateTitleAuthorization
URL —
http://<host:port>/BillingAdaptor/api/household/{householdId}/authorization/t
itle/{purchaseId}
HTTP Command — PUT
Usage — This command requires the associated household ID and the purchase ID
that was returned from the create operation in the URL. The data in the URL
combined with the desired payload attributes complete the update request.
Payload
Title Authorization
Object
Mandatory/
Optional
Comments
authorizationId
M
The authorization ID
expirationDate
M
The expiration date of the
title authorization
authorizationType
O
The type of authorization,
which, for a title
authorization, includes:
TVOD, PPV, BUNDLE
authorizationStatus
O
The authorization status,
which includes the following
options:
PURCHASE_STARTED,
PURCHASE_COMPLETED,
EXPIRED
rentalTime
O
The rental time duration in
days
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
66
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
OL-28775-02
REST Command Guidance and Examples
Sample Request/Response: Update Title Authorization
PUT
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/authorization/title/92e891e8-6e7d-4355-b2c1-82909fac0a21
Content-Type: text/xml
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><ns2:UpdateTitleAuthorization
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/comm
onapi"><titleAuthorizationUpdate><authorizationId>1991</author
izationId><rentalTime>2033</rentalTime><expirationDate>201402-23T07:01:23.00005:00</expirationDate></titleAuthorizationUpdate></ns2:UpdateT
itleAuthorization>
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
application/xml
Content-Length:
Date:
198
Tue, 07 Jan 2014 21:34:22 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage></ns2:StandardResponse>
DeleteTitleAuthorization
URL —
http://<host:port>/BillingAdaptor/api/household/{householdId}/authorization/t
itle/{purchaseId}
HTTP Command — DELETE
Usage — This command deletes the title authorization by specifying both its
associated household ID and its purchase ID.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
body
If successful, this attribute is populated
with a success message.
OL-28775-02
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
67
REST Command Guidance and Examples
Sample Request/Response: Delete Title Authorization
DELETE
http://209.165.200.224:8080/BillingAdaptor/api/household/
testid123/authorization/title/92e891e8-6e7d-4355-b2c182909fac0a21
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
312
Tue, 07 Jan 2014 21:41:01 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>successfully deleted resource
[HouseholdId=testid123, inPurchaseId=92e891e8-6e7d-4355-b2c182909fac0a21]</body></ns2:StandardResponse>
68
OL-28775-02
REST Command Guidance and Examples
GetTitleAuthorization
URL —
http://<host:port>/BillingAdaptor/api/household/{householdId}/authorization/t
itle/{purchaseId}
HTTP Command — GET
Usage — To retrieve a title authorization, specify its purchase ID and associated
household ID in the URL.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
400 Bad Request
authorizationId
The authorization identifier
404 Not Found
authorizationStatus
The authorization status, which can be
one of the following:
PURCHASE_STARTED,
PURCHASE_COMPLETED, EXPIRED
authorizationType
The type of authorization, which
includes the following options:
SUBSCRIPTION, BUNDLE, SVOD,
TVOD, PPV
purchaseId
The purchase identifier
purchaseDate
The purchase date
rentalTime
The rental time
isViewed
A flag indicating viewing status
isReported
A flag indicating reporting status
200 OK
500 Internal Server
Error
Sample Request/Response: Get Title Authorization
GET http://209.165.200.224:8080/BillingAdaptor/api/household/
testid123/authorization/title/92e891e8-6e7d-4355-b2c182909fac0a21
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
OL-28775-02
535
Tue, 07 Jan 2014 21:28:32 GMT
69
REST Command Guidance and Examples
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><ns2:TitleAuthorizationResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><titleAuthorization><authorizationId>1991</authorizati
onId><expirationDate>2031-12-31T12:00:00.00005:00</expirationDate><rentalTime>3</rentalTime><purchaseId>92e891e8-6e7d4355-b2c1-82909fac0a21</purchaseId><purchaseDate>2014-01-07T16:22:33.00005:00</purchaseDate><isViewed>false</isViewed><isReported>false</isReported>
</titleAuthorization></ns2:TitleAuthorizationResponse>
GetTitleAuthorizations
URL —
http://<host:port>/BillingAdaptor/api/household/{householdId}/authorization/t
itles
HTTP Command — GET
Usage — This API provides access to the list of all title authorizations for the
specified household.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
titleAuthorizations
The list of title authorization objects
associated with the specified household
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get Title Authorizations
GET http://209.165.200.224:8080/BillingAdaptor/api/household/
testid123/authorization/titles
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
514
Tue, 07 Jan 2014 21:31:09 GMT
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><ns2:TitleAuthorizationsResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><titleAuthorizations><titleAuthorization><authorizatio
nId>1991</authorizationId><expirationDate>2031-1231T12:00:00.000Z</expirationDate><rentalTime>3</rentalTime><purchaseId>92e89
1e8-6e7d-4355-b2c1-82909fac0a21</purchaseId><purchaseDate>2014-0107T16:22:33.000Z</purchaseDate></titleAuthorization></titleAuthorizations></
ns2:TitleAuthorizationsResponse>
70
OL-28775-02
REST Command Guidance and Examples
Locale Commands
UpdateRegion
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
locale/region/{region}
HTTP Command — PUT
Usage — This command sets the region value in the locale object. Note that the
region is a string.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: UpdateRegion
PUT
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/locale/region/Southeast
Content-Type: text/xml
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
198
Tue, 28 Jan 2014 22:07:25 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage></ns2:StandardResponse>
OL-28775-02
71
REST Command Guidance and Examples
GetRegion
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
locale/region
HTTP Command — GET
Usage — To retrieve the region attribute within the locale object, specify its
associated household ID in the URL.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
body
The region value, assuming no error is
detected
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get Region
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/locale/region
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
191
Tue, 28 Jan 2014 22:13:45 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><body>S
outheast</body></ns2:StandardResponse>
72
OL-28775-02
REST Command Guidance and Examples
UpdateCmdcRegion
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
locale/cmdcRegion/{cmdcRegion}
HTTP Command — PUT
Usage — This command sets the CMDC region value in the locale object. Note that
the CMDC region is a string.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: UpdateCmdcRegion
PUT
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/locale/cmdcRegion/cmdc15
Content-Type: text/xml
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
198
Tue, 28 Jan 2014 22:17:30 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage></ns2:StandardResponse>
OL-28775-02
73
REST Command Guidance and Examples
GetCmdcRegion
URL— http://<host:port>/BillingAdaptor/api/household/{householdId}/
locale/cmdcRegion
HTTP Command — GET
Usage — To retrieve the CMDC region attribute within the locale object, specify its
associated household ID in the URL.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
body
The CMDC region value, assuming no
error is detected
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get CMDC Region
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/locale/cmdcRegion
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
188
Tue, 28 Jan 2014 22:18:26 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><body>c
mdc15</body></ns2:StandardResponse>
74
OL-28775-02
REST Command Guidance and Examples
UpdateCity
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
locale/city/{city}
HTTP Command — PUT
Usage — This command sets the city value in the locale object. Note that the city
value is an integer.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Update City
PUT
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/locale/city/19
Content-Type: text/xml
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
198
Tue, 28 Jan 2014 22:21:02 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage></ns2:StandardResponse>
OL-28775-02
75
REST Command Guidance and Examples
GetCity
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
locale/city
HTTP Command — GET
Usage — To retrieve the city code attribute within the locale object, specify its
associated household ID in the URL.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
body
The city code value, assuming no error
is detected
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get City
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/locale/city
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
184
Tue, 28 Jan 2014 22:24:08 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><body>1
9</body></ns2:StandardResponse>
76
OL-28775-02
REST Command Guidance and Examples
UpdateAdZone
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
locale/adZone/{adZone}
HTTP Command — PUT
Usage — This command sets the ad zone value in the locale object. Note that the
adZone is a string.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Update Ad Zone
PUT
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/locale/adZone/az17
Content-Type: text/xml
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
198
Tue, 28 Jan 2014 23:14:16 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage></ns2:StandardResponse>
OL-28775-02
77
REST Command Guidance and Examples
GetAdZone
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
locale/adZone
HTTP Command — GET
Usage — To retrieve the ad zone attribute within the locale object, specify its
associated household ID in the URL.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
body
The ad zone value, assuming no error is
detected
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get Ad Zone
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/locale/adZone
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
186
Tue, 28 Jan 2014 23:15:48 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><body>a
z17</body></ns2:StandardResponse>
78
OL-28775-02
REST Command Guidance and Examples
UpdatePostalCode
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
locale/postalCode/{postalCode}
HTTP Command — PUT
Usage — This command sets the postal code value in the locale object. Note that the
postal code is a string.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Update Postal Code
PUT
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/locale/postalCode/30030
Content-Type: text/xml
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
198
Tue, 28 Jan 2014 23:17:51 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage></ns2:StandardResponse>
OL-28775-02
79
REST Command Guidance and Examples
GetPostalCode
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
locale/postalCode
HTTP Command — GET
Usage — To retrieve the postal code attribute within the locale object, specify its
associated household ID in the URL.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
body
The postal code value, assuming no
error is detected
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get Postal Code
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/locale/postalCode
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
187
Tue, 28 Jan 2014 23:19:34 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><body>3
0030</body></ns2:StandardResponse>
80
OL-28775-02
REST Command Guidance and Examples
UpdateMarketingTarget
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
locale/marketingTarget/{marketingTarget}
HTTP Command — PUT
Usage — This command sets the marketing target value in the locale object. Note
that the marketing target is a string.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Update Marketing Target
PUT
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/locale/marketingTarget/mt18
Content-Type: text/xml
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
198
Tue, 28 Jan 2014 23:23:24 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage></ns2:StandardResponse>
OL-28775-02
81
REST Command Guidance and Examples
GetMarketingTarget
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
locale/marketingTarget
HTTP Command — GET
Usage — To retrieve the marketing target attribute within the locale object, specify
its associated household ID in the URL.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
body
The marketing target value, assuming
no error is detected
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get Marketing Target
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/locale/marketingTarget
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
186
Tue, 28 Jan 2014 23:25:24 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><body>m
t18</body></ns2:StandardResponse>
82
OL-28775-02
REST Command Guidance and Examples
UpdateBlackoutZone
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
locale/blackoutZone/{blackoutZone}
HTTP Command — PUT
Usage — This command sets the blackout zone value in the locale object. Note that
the blackout zone is a string.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Update Blackout Zone
PUT
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/locale/blackoutZone/bz11
Content-Type: text/xml
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
198
Tue, 28 Jan 2014 23:27:13 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage></ns2:StandardResponse>
OL-28775-02
83
REST Command Guidance and Examples
GetBlackoutZone
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/
locale/blackoutZone
HTTP Command — GET
Usage — To retrieve the blackout zone attribute within the locale object, specify its
associated household ID in the URL.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
body
The blackout zone value, assuming no
error is detected
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get Blackout Zone
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/locale/blackoutZone
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
186
Tue, 28 Jan 2014 23:28:13 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><body>b
z11</body></ns2:StandardResponse>
84
OL-28775-02
REST Command Guidance and Examples
GetLocale
URL — http://<host:port>/BillingAdaptor/api/household/{householdId}/ locale
HTTP Command — GET
Usage — This command retrieves the locale for the specified household.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
locale
The locale object, assuming no error is
detected
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get Locale
GET
http://209.165.200.224:8080/BillingAdaptor/api/household/testi
d123/locale
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
406
Tue, 28 Jan 2014 23:28:49 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:LocaleResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><locale><region>Southeast</region><cmdcRegion>cmdc15</
cmdcRegion><city>19</city><adZone>az17</adZone><postalCode>30030</postalCode
><marketingTarget>mt18</marketingTarget><blackoutZone>bz11</blackoutZone></l
ocale></ns2:LocaleResponse>
OL-28775-02
85
REST Command Guidance and Examples
Purchase Reporting
Create Purchase Upload File
URL — http://<host:port>/BillingAdaptor/api
/createPurchaseUploadFile?filename={file name}
HTTP Command — POST
Usage — This command triggers the generation of a purchase report that includes
all purchases and cancellations since the previous invocation of the command. When
this command executes successfully, the file URL is provided in the response with
the expectation that the BOA client would then access the file directly via FTP. If
there are no purchase records to report, a 204 response will be provided. When a
new report is generated, there is no automatic removal of the previous report(s).
Each time the same report name is specified in the request, the previous report is
overwritten.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMessage
If an error is detected, this attribute is
populated with an error message.
body
The location from which the completed
report can be accessed
201 Created
204 No Content
400 Bad Request
500 Internal Server
Error
Sample Request/Response: Create Purchase Upload File
POST
http://209.165.200.224:8080/BillingAdaptor/api/createPurchaseU
ploadFile?filename=exampleReport
Content-Type: text/xml
-- response -201 Created
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
258
Fri, 14 Mar 2014 17:44:47 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body>ftp://10.90.187.251:21/rs/reports/exampleReport<
/body></ns2:StandardResponse>
86
OL-28775-02
REST Command Guidance and Examples
Miscellaneous API Commands
Get Services
URL — http://<host:port>/BillingAdaptor/api/services
HTTP Command — GET
Usage — This API provides access to the list of VCS services to which the BOA has
created a connection.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
400 Bad Request
key
The service name
404 Not Found
value
The service VSNS
200 OK
500 Internal Server
Error
Sample Request/Response: Get Services
GET http://209.165.200.224:8080/BillingAdaptor/api/services
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
684
Mon, 03 Jun 2013 14:57:57 GMT
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><ns2:GetServicesResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><services><entry><key>RegisterService</key><value>cond
uctor://cisco.dbds.ecs.cluster1.register</value></entry><entry><key>cvm18554
</key><value>conductor://cisco.dbds.ec.cluster1.cvm18554boss</value></entry><entry><key>dbds.loadpims</key><value>conductor://cisco.
dbds.ecs.cluster1.loadpims</value></entry><entry><key>CpeManagement</key><va
lue>conductor://cisco.dbds.ecs.cluster1.cpems</value></entry><entry><key>upm
</key><value>http://209.165.200.225:6040</value></entry></services></ns2:Get
ServicesResponse>
OL-28775-02
87
REST Command Guidance and Examples
UpdateRoutingTable
URL — http://<host:port>/BillingAdaptor/api/routingTable
HTTP Command — PUT
Usage — This API facilitates the updating of the BOA routing table that maps billing
systems to the DNCS (or EC) and DTACS pairs.
Payload
UserProfile
Object
Mandatory/
Optional
Comments
routingTable
M
Must pass the routingTable object
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Update Routing Table
PUT
http://209.165.200.224:8080/BillingAdaptor/api/routingTable
Content-Type: text/xml
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><ns2:UpdateRoutingTable
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/rtma
pping"><routingTable><routingTableElement><billingIp>209.165.2
00.225</billingIp><billingValue><dncsIp>209.165.200.226</dncsI
p><dtacsIp>209.165.200.227</dtacsIp></billingValue></routingTa
bleElement><routingTableElement><billingIp>209.165.200.228</bi
llingIp><billingValue><dncsIp>209.165.200.229</dncsIp><dtacsIp
>209.165.200.230</dtacsIp></billingValue></routingTableElement
></routingTable></ns2:UpdateRoutingTable>
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
88
211
Fri, 01 Nov 2013 21:18:21 GMT
OL-28775-02
REST Command Guidance and Examples
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:StandardResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"><errorM
essage></errorMessage><body></body></ns2:StandardResponse>
GetRoutingTable
URL — http://<host:port>/BillingAdaptor/api/routingTable
HTTP Command — GET
Usage — This API provides access to the BOA routing table that maps billing
systems to the DNCS (or EC) and DTACS pairs.
Payload — N/A
Response
Name/Object
Comments
HTTP Status Codes
errorMsg
If an error is detected, this attribute is
populated with an error message.
200 OK
400 Bad Request
404 Not Found
500 Internal Server
Error
Sample Request/Response: Get Routing Table
GET http://209.165.200.224/BillingAdaptor/api/routingTable
-- response -200 OK
Server:
Apache-Coyote/1.1
Content-Type:
Content-Length:
application/xml
Date:
541
Fri, 01 Nov 2013 20:52:20 GMT
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><ns2:RoutingTableResponse
xmlns:ns2="http://protocols.cisco.com/spvtg/conductor/boa/rtmapping"><errorM
essage></errorMessage><body><routingTableElement><billingIp>209.165.200.225<
/billingIp><billingValue><dncsIp>209.165.200.226</dncsIp><dtacsIp>209.165.20
0.227</dtacsIp></billingValue></routingTableElement><routingTableElement><bi
llingIp>209.165.200.228</billingIp><billingValue><dncsIp>209.165.200.229</dn
csIp><dtacsIp>209.165.200.230</dtacsIp></billingValue></routingTableElement>
</body></ns2:RoutingTableResponse>
OL-28775-02
89
BOA Common API Schema
BOA Common API Schema
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://protocols.cisco.com/spvtg/conductor/boa/commonapi"
xmlns="http://protocols.cisco.com/spvtg/conductor/boa/commonapi">
<!-- EDCS-1149901 BSS/OSS Adaptor XML Schema Conductor Services,
Videoscape Copyright (c) 2011-2013 by Cisco Systems, Inc.
June 4, 2012 Initial Version - Richard Winkles This schema supports the
functions embedded in the BOA component of the Videoscape system.
June 27, 2012 Added the Common BOA REST support - Denton Elliott.
May 6, 2013 Altered schema to transition from ClientDirectory to UPM Denton Elliott
Aug 22, 2013 Added Authorizations and general cleanup - Denton Elliott
September 23, 2013 Added locale and enabledServices support
Oct 7, 2013 Added npvrData
Dec 6, 2013 Added TitleAuthorizations
Dec 12, 2013 Added TitleAuthorizationUpdate and authorizationStatusType T Snapke
Jan 14, 2014 Added GetHouseholdIds - Denton Elliott
-->
<xs:simpleType name="string">
<xs:restriction base="xs:string">
<xs:maxLength value="256" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="logLevel">
<xs:restriction base="string">
<xs:enumeration value="WARN" />
<xs:enumeration value="INFO" />
<xs:enumeration value="DEBUG" />
<xs:enumeration value="TRACE" />
90
OL-28775-02
BOA Common API Schema
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="householdStatus">
<xs:restriction base="string">
<xs:enumeration value="ACTIVATED" />
<xs:enumeration value="SUSPENDED" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="operateStatus">
<xs:restriction base="string">
<xs:enumeration value="ACTIVE" />
<xs:enumeration value="INACTIVE" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="bssFullType">
<xs:restriction base="string">
<xs:enumeration value="MANAGED" />
<xs:enumeration value="UNMANAGED" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="authorizationType">
<xs:restriction base="string">
<xs:enumeration value="SUBSCRIPTION" />
<xs:enumeration value="BUNDLE" />
<xs:enumeration value="SVOD" />
<xs:enumeration value="TVOD" />
<xs:enumeration value="PPV" />
<xs:enumeration value="TIER" />
</xs:restriction>
OL-28775-02
91
BOA Common API Schema
</xs:simpleType>
<xs:simpleType name="authorizationStatusType">
<xs:restriction base="string">
<xs:enumeration value="PURCHASE_STARTED" />
<xs:enumeration value="PURCHASE_COMPLETED" />
<xs:enumeration value="EXPIRED" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="subscription">
<xs:all>
<xs:element name="authorizationId" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="offerKey" type="string" minOccurs="0"
maxOccurs="1" />
<xs:element name="offerId" type="string" minOccurs="0"
maxOccurs="1" />
<xs:element name="authorizationType"
type="authorizationType" minOccurs="0" maxOccurs="1" />
<xs:element name="authorizationStatus"
type="authorizationStatusType" minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
<xs:complexType name="authorizations">
<xs:sequence>
<xs:element name="subscription" type="subscription"
minOccurs="0" maxOccurs="unbounded" />
<xs:element name="title" type="titleAuthorization"
minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="households">
92
OL-28775-02
BOA Common API Schema
<xs:sequence>
<xs:element name="households" type="household"
minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="devices">
<xs:sequence>
<xs:element name="device" type="device" minOccurs="0"
maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="deviceFeaturesType">
<xs:sequence>
<xs:element name="deviceFeature" type="string"
minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="userProfiles">
<xs:sequence>
<xs:element name="userProfile" type="userProfile"
minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="services">
<xs:sequence>
<xs:element name="entry" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element name="key" minOccurs="0" type="string"/>
OL-28775-02
93
BOA Common API Schema
<xs:element name="value" minOccurs="0" type="string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="locale">
<xs:all>
<xs:element name="region" type="string" minOccurs="0" maxOccurs="1" />
<xs:element name="cmdcRegion" type="string" minOccurs="1"
maxOccurs="1" />
<xs:element name="city" type="xs:integer" minOccurs="0" maxOccurs="1" />
<xs:element name="adZone" type="string" minOccurs="0" maxOccurs="1" />
<xs:element name="postalCode" type="string" minOccurs="0" maxOccurs="1"
/>
<xs:element name="marketingTarget" type="string" minOccurs="0"
maxOccurs="1" />
<xs:element name="blackoutZone" type="string" minOccurs="0"
maxOccurs="1" />
</xs:all>
</xs:complexType>
<xs:complexType name="enabledServices">
<xs:sequence>
<xs:element name="service" type="string" minOccurs="0"
maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="npvrData">
<xs:all>
<xs:element name="contentRetentionPeriod" type="xs:integer"
minOccurs="0" maxOccurs="1" />
94
OL-28775-02
BOA Common API Schema
<xs:element name="contentDeleteDate" type="xs:dateTime"
minOccurs="0" maxOccurs="1" />
<xs:element name="npvrCapacity" type="xs:integer"
minOccurs="0" maxOccurs="1" />
<xs:element name="npvrTunerQuota" type="xs:integer"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
<xs:complexType name="preferences">
<xs:all>
<xs:element name="purchasePin" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="parentalPin" type="string" minOccurs="0"
maxOccurs="1" />
<xs:element name="maxDeviceCount" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="maxCreditLimit" type="string"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
<xs:complexType name="household">
<xs:all>
<xs:element name="householdId" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="householdStatus" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="defaultUserId" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="address" type="string" minOccurs="0"
maxOccurs="1" />
<xs:element name="devices" type="devices" minOccurs="0"
maxOccurs="1" />
<xs:element name="userProfiles" type="userProfiles"
minOccurs="0" maxOccurs="1" />
OL-28775-02
95
BOA Common API Schema
<xs:element name="createDate" type="xs:dateTime"
minOccurs="0" maxOccurs="1" />
<xs:element name="lastUpdateDate" type="xs:dateTime"
minOccurs="0" maxOccurs="1" />
<xs:element name="operateStatus" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="authorizations" type="authorizations"
minOccurs="0" maxOccurs="1" />
<xs:element name="locale" type="locale" minOccurs="0"
maxOccurs="1" />
<xs:element name="enabledServices" type="enabledServices"
minOccurs="0" maxOccurs="1" />
<xs:element name="npvrData" type="npvrData"
minOccurs="0" maxOccurs="1" />
<xs:element name="preferences" type="preferences"
minOccurs="0" maxOccurs="1" />
<xs:element name="spendingLimit" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="currentBalance" type="string"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
<xs:complexType name="userProfile">
<xs:all>
<xs:element name="userProfileId" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="favoriteChannelsUrl" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="displayName" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="email" type="string" minOccurs="0"
maxOccurs="1" />
<xs:element name="firstName" type="string" minOccurs="0"
maxOccurs="1" />
<xs:element name="lastName" type="string" minOccurs="0"
maxOccurs="1" />
96
OL-28775-02
BOA Common API Schema
<xs:element name="lastLoginIpAddress" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="lastLoginTime" type="xs:dateTime"
minOccurs="0" maxOccurs="1" />
<xs:element name="phoneNumber" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="role" type="string" minOccurs="0"
maxOccurs="1" />
<xs:element name="priority" type="xs:integer" minOccurs="0"
maxOccurs="1" />
<xs:element name="userId" type="string" minOccurs="0"
maxOccurs="1" />
<xs:element name="createDate" type="xs:dateTime"
minOccurs="0" maxOccurs="1" />
<xs:element name="lastUpdateDate" type="xs:dateTime"
minOccurs="0" maxOccurs="1" />
<xs:element name="operateStatus" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="jid" type="string" minOccurs="0"
maxOccurs="1" />
<xs:element name="presenceStatus" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="isDefault" type="string" minOccurs="0"
maxOccurs="1" />
</xs:all>
</xs:complexType>
<xs:complexType name="device">
<xs:all>
<xs:element name="deviceId" type="string" minOccurs="0"
maxOccurs="1" />
<xs:element name="onlineUserId" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="auxDeviceId" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="deviceType" type="string" minOccurs="0"
maxOccurs="1" />
OL-28775-02
97
BOA Common API Schema
<xs:element name="deviceFeatures"
type="deviceFeaturesType" minOccurs="0" maxOccurs="1" />
<xs:element name="deviceCategory" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="bssFullType" type="bssFullType"
minOccurs="0" maxOccurs="1" />
<xs:element name="profile" type="string" minOccurs="0"
maxOccurs="1" />
<xs:element name="macAddress" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="serialNo" type="string" minOccurs="0"
maxOccurs="1" />
<xs:element name="ipAddress" type="string" minOccurs="0"
maxOccurs="1" />
<xs:element name="createDate" type="xs:dateTime"
minOccurs="0" maxOccurs="1" />
<xs:element name="lastUpdateDate" type="xs:dateTime"
minOccurs="0" maxOccurs="1" />
<xs:element name="operateStatus" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="jid" type="string" minOccurs="0"
maxOccurs="1" />
<xs:element name="presenceStatus" type="string"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
<xs:complexType name="householdIds">
<xs:sequence>
<xs:element name="id" type="string" minOccurs="0"
maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="userIds">
<xs:sequence>
98
OL-28775-02
BOA Common API Schema
<xs:element name="userId" type="string" minOccurs="0"
maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="deviceIds">
<xs:sequence>
<xs:element name="deviceId" type="string" minOccurs="0"
maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="titleAuthorization">
<xs:all>
<xs:element name="authorizationId" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="authorizationStatus"
type="authorizationStatusType" minOccurs="0" maxOccurs="1" />
<xs:element name="expirationDate" type="xs:dateTime"
minOccurs="1" maxOccurs="1" />
<xs:element name="purchaseId" type="string" minOccurs="0"
maxOccurs="1" />
<xs:element name="groupId" type="string" minOccurs="0"
maxOccurs="1" />
<xs:element name="authorizationType"
type="authorizationType" minOccurs="0" maxOccurs="1" />
<xs:element name="price" type="string" minOccurs="0"
maxOccurs="1" />
<xs:element name="billingRecord" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="startDate" type="xs:dateTime"
minOccurs="0" maxOccurs="1" />
<xs:element name="deviceId" type="string" minOccurs="0"
maxOccurs="1" />
<xs:element name="purchaseDate" type="xs:dateTime"
minOccurs="0" maxOccurs="1" />
OL-28775-02
99
BOA Common API Schema
<xs:element name="isViewed" type="xs:boolean"
minOccurs="0" maxOccurs="1" />
<xs:element name="isReported" type="xs:boolean"
minOccurs="0" maxOccurs="1" />
<xs:element name="userProfileId" type="string"
minOccurs="0" maxOccurs="1" />
<xs:element name="rentalTime" type="xs:integer"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
<xs:complexType name="titleAuthorizationUpdate">
<xs:all>
<xs:element name="authorizationId" type="string" minOccurs="1"
maxOccurs="1" />
<xs:element name="expirationDate" type="xs:dateTime"
minOccurs="1" maxOccurs="1" />
<xs:element name="authorizationStatus"
type="authorizationStatusType" minOccurs="0" maxOccurs="1" />
<xs:element name="authorizationType"
type="authorizationType" minOccurs="0" maxOccurs="1" />
<xs:element name="rentalTime" type="xs:integer"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
<xs:complexType name="titleAuthorizations">
<xs:sequence>
<xs:element name="titleAuthorization"
type="titleAuthorization" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:element name="StandardResponse">
<xs:complexType>
<xs:all>
100
OL-28775-02
BOA Common API Schema
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="body" type="string"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="CompoundResponse">
<xs:complexType>
<xs:all>
<xs:element name="httpStatusCode" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="body" type="string"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="GetServicesResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="services" type="services"
minOccurs="1" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="HouseholdResponse">
<xs:complexType>
<xs:all>
OL-28775-02
101
BOA Common API Schema
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="household" type="household"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="HouseholdIdsResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="householdIds"
type="householdIds" minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="DeviceResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="device" type="device"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="DevicesResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
102
OL-28775-02
BOA Common API Schema
<xs:element name="devices" type="devices"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="UserProfileResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="userProfile" type="userProfile"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="UserProfilesResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="userProfiles" type="userProfiles"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="HouseholdSubscriptionResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="subscription" type="subscription"
minOccurs="0" maxOccurs="1" />
OL-28775-02
103
BOA Common API Schema
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="HouseholdAuthorizationsResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="authorizations"
type="authorizations" minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="CreateTitleAuthorizationResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="purchaseId" type="string"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="TitleAuthorizationResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="titleAuthorization"
type="titleAuthorization" minOccurs="0" maxOccurs="1" />
</xs:all>
104
OL-28775-02
BOA Common API Schema
</xs:complexType>
</xs:element>
<xs:element name="TitleAuthorizationsResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="titleAuthorizations"
type="titleAuthorizations" minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="LocaleResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="locale" type="locale"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="EnabledServicesResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="enabledServices"
type="enabledServices" minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
OL-28775-02
105
BOA Common API Schema
</xs:element>
<xs:element name="NpvrDataResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="npvrData" type="npvrData"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="HouseholdPreferencesResponse">
<xs:complexType>
<xs:all>
<xs:element name="errorMessage" type="string"
minOccurs="1" maxOccurs="1" />
<xs:element name="preferences" type="preferences"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<!-- User Profile Management Requests -->
<xs:element name="CreateUserProfile">
<xs:complexType>
<xs:all>
<xs:element name="userProfile" type="userProfile"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
106
OL-28775-02
BOA Common API Schema
<xs:element name="UpdateUserProfile">
<xs:complexType>
<xs:all>
<xs:element name="userProfile" type="userProfile"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<!-- Household Management Requests -->
<xs:element name="CreateHousehold">
<xs:complexType>
<xs:all>
<xs:element name="household" type="household"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="UpdateHousehold">
<xs:complexType>
<xs:all>
<xs:element name="household" type="household"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="CreateHouseholdSubscription">
<xs:complexType>
<xs:all>
OL-28775-02
107
BOA Common API Schema
<xs:element name="subscription" type="subscription"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="UpdateHouseholdSubscription">
<xs:complexType>
<xs:all>
<xs:element name="subscription" type="subscription"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="CreateTitleAuthorization">
<xs:complexType>
<xs:all>
<xs:element name="titleAuthorization"
type="titleAuthorization" minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="UpdateTitleAuthorization">
<xs:complexType>
<xs:all>
<xs:element name="titleAuthorizationUpdate"
type="titleAuthorizationUpdate" minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<!-- Device Management Requests -->
108
OL-28775-02
BOA Common API Schema
<xs:element name="CreateDevice">
<xs:complexType>
<xs:all>
<xs:element name="device" type="device"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="UpdateDevice">
<xs:complexType>
<xs:all>
<xs:element name="device" type="device"
minOccurs="0" maxOccurs="1" />
</xs:all>
</xs:complexType>
</xs:element>
</xs:schema>
OL-28775-02
109
Purchase Report Schema
Purchase Report Schema
The content of the purchase report, which is collected in a JSON file, is specified in
the following schema:
{
{
"id": "GetPurchaseDataResponse",
"type": "array",
"items": {
ref$:"purchaseNotification "
}
},
{
"id": "PurchaseMetadata",
"type": "object",
"properties": {
"displayPrice": {
"type": "number",
"optional": "true"
},
"authorizationType": {
"type": "string",
"optional": "true"
},
"purchasedEntity": {
"type": "string",
"optional": "true"
},
"productName": {
"type": "string",
"optional": "true"
},
110
OL-28775-02
Purchase Report Schema
"productDescription": {
"type": "string",
"optional": "true"
},
"assetTitle": {
"type": "string",
"optional": "true"
},
"startDate": {
"type": "date",
"optional": "true"
},
"endDate": {
"type": "date",
"optional": "true"
},
"profileId": {
"type": "string",
"optional": "true"
},
"purchaseStatus": {
type:"string",
enum:[
"PURCHASE_STARTED",
"PURCHASE_COMPLETED"],
"optional": "true"
},
"contentId": {
"type": "string",
"optional": "true"
},
"smsId": {
"type": "string",
OL-28775-02
111
Purchase Report Schema
"optional": "true"
},
"properties": {
"$ref": "PropertiesType",
"optional": "true"
}
}
},
{
"id": "PurchaseRecord",
"type": "object",
"properties": {
"purchaseId": {
"type": "string"
},
"itemStatus": {
type:"string",
enum:[
"purchased",
"cancelled",
"swapped"],
"optional": "true"
},
"purchasingDevice": {
"$ref": "Device",
"optional": "true"
},
"offerId": {
"type": "string",
"optional": "true"
},
"purchaseDate": {
"type": "date",
112
OL-28775-02
Purchase Report Schema
"optional": "true"
},
"price": {
"type": "decimal",
"optional": "true"
},
"billingRecord": {
"type": "string",
"optional": "true"
},
"bundleOffer": {
"optional": "true",
"offerId": {
"type": "array",
"items": {
type:"string"
}
}
},
"purchaseOption": {
“$ref”: “purchaseOption”,
"optional": "true"
},
"metadata": {
"$ref": "PurchaseMetadata",
"optional": "true"
},
"paymentInfo": {
"$ref": "PaymentInfo",
"optional": "true"
},
"isViewed": {
“type”: “boolean”,
OL-28775-02
113
Purchase Report Schema
"optional": "true"
}
}
},
{
"id": "CancellationRecord",
"type": "object",
"properties": {
"offerId": {
"type": "string"
}
"purchasingDevice": {
"$ref": "Device",
"optional": "true"
},
"purchaseId": {
"type": "string",
"optional": "true"
},
"metadata": {
"$ref": "PurchaseMetadata",
"optional": "true"
},
"cancellationDate": {
"type": "date"
}
}
},
{
"id": "purchaseNotification",
"type": "object",
114
OL-28775-02
Purchase Report Schema
"properties": {
"householdId": {
"type": "string"
},
"transactionId": {
"type": "string"
},
"cancellation": {
"type": "array",
"items": {
"$ref": "CancellationRecord"
}
},
"purchase": {
"type": "array",
"items": {
"$ref": "PurchaseRecord"
}
},
"swap": {
"type": "array",
"items": {
"type": "object",
"properties": {
"purchase": {
"$ref": "PurchaseRecord"
},
"cancellation": {
"$ref": "CancellationRecord"
}
}
}
}
OL-28775-02
115
Purchase Report Schema
}
}
}
The following is a sample purchase report:
[
{
"householdId": "Household1",
"transactionId": "065f215f-15c4-4d8e-885b-e669e32e585f",
"purchase": [{
"purchaseId": "5410d2ad-3f95-4307-0e31-250fc58",
"purchasingDevice": {
"deviceId": "951522"
},
"offerId": "60758",
"purchaseDate": "2012-01-15T11:03:00Z",
"price": "10",
"billingRecord": "<assetBillingRecord>
<providerId>bbc.co.uk</providerId>
<assetId>FOOL2003102400000001</assetId>
<providerCode>fba23</providerCode>
<assetTitle>Only Fools and Horses</assetTitle>
<parentalRating>PG</parentalRating>
</assetBillingRecord>",
"metadata": {
"authorizationType": "TVOD",
"startDate": "2012-01-15T11:03:00Z",
"endDate": "2012-04-15T11:03:00Z",
"properties": {
"property": [{
"name": "CAServiceId",
116
OL-28775-02
Purchase Report Schema
"value": "45465"
}, {
"name": "RentalPeriod",
"value": "12"
}]
}
}
}]
},
{
"householdId": "Household2",
"transactionId": "875e0915f-9fc4-a38e-955b-e6694f5e5710",
"purchase": [{
"purchaseId": "6f10eead-bfa5-4c0a-9731-25090c3",
"purchasingDevice": {
"deviceId": "2351582"
},
"offerId": "60758",
"purchaseDate": "2012-01-15T12:08:06Z",
"price": "10",
"billingRecord": "<assetBillingRecord>
<providerId>bbc.co.uk</providerId>
<assetId>WN2003102400000002</assetId>
<providerCode>fba24</providerCode>
<assetTitle>Wild Nature</assetTitle>
<parentalRating>PG</parentalRating>
</assetBillingRecord>",
"metadata": {
"authorizationType": "PPV",
"startDate": "2012-01-15T14:03:00Z",
"endDate": "2012-01-16T14:03:00Z",
OL-28775-02
117
Purchase Report Schema
"properties": {
"property": [{
"name": "CAServiceId",
"value": "45465"
}]
}
}
}]
}
]
118
OL-28775-02
For Information
If You Have Questions
If you have technical questions, contact Cisco Services for assistance. Follow the
menu options to speak with a service engineer.
Americas Headquarters
http://www.cisco.com
Cisco Systems, Inc.
Tel: 408 526-4000
170 West Tasman Drive
800 553-6387
San Jose, CA 95134-1706
Fax: 408 527-0883
USA
Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates
in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL:
www.cisco.com/go/trademarks.
Third party trademarks mentioned are the property of their respective owners.
The use of the word partner does not imply a partnership relationship between Cisco and any
other company. (1110R)
Product and service availability are subject to change without notice.
© 2013 - 2014 Cisco and/or its affiliates. All rights reserved.
May 2014
Part Number OL-28775-02
© Copyright 2026 Paperzz