Open API Project
USCC AMP Subscriber Profile REST
Developer Guide
Document Version 1.3
Document Revision History
Rev #
Date
Description
1.0
June 28 2013
Created based on USCC-NaaS-Sub-Profile_API_v1.0.doc.
1.1
Sept 12 2013
Added Sandbox section as an Appendix.
1.2
Nov 1 2013
Replaced URLs, code examples, param lists to match
production platform.
1.3
Mar 31 2015
Updated for Prepaid Flag CR. Sections 4.3.1, 4.3.2, 4.4.2
and A2.1
Developer Guide
Page 2
© Intel Corporation 2015. All rights reserved.
Legal Information
No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by
this document.
Intel disclaims all express and implied warranties, including without limitation, the implied warranties of
merchantability, fitness for a particular purpose, and non-infringement, as well as any warranty arising from
course of performance, course of dealing, or usage in trade.
This document contains information on products, services and/or processes in development. All information
provided here is subject to change without notice. Contact your Intel representative to obtain the latest
forecast, schedule, specifications and roadmaps.
The products and services described may contain defects or errors known as errata which may cause
deviations from published specifications. Current characterized errata are available on request.
Copies of documents which have an order number and are referenced in this document may be obtained by
calling 1-800-548-4725 or by visiting www.intel.com/design/literature.htm .
Aepona, Intel and the Intel logo are trademarks of Intel Corporation in the U.S. and/or other countries.
*Other names and brands may be claimed as the property of others.
© 2015 Intel Corporation.
Developer Guide
Page 3
© Intel Corporation 2015. All rights reserved.
Table of Contents
1
Subscriber Profile REST Overview
2
Authentication
3
Methods
3.1
URIs
4
Get Subscriber Profile
4.1
Retrieve Subscriber Profile Request
4.1.1
Request Example - Single Subscriber
4.1.2
Request Example - Multiple Subscribers
4.2
Request Parameters
4.3
Retrieve Subscriber Profile Responses
4.3.1
Response Example - One CTN - Success
4.3.2
Response Example - Multiple CTNs - Partial Success
4.3.3
Response Example - Unsuccessful
4.4
Response Parameters
4.4.1
subscriberProfileList /subscriberProfile Elements
4.4.2
inventoryData Structure Elements
4.4.3
errorInformation Structure Elements
4.5
Response Data Structure Diagrams
5
Response Codes and Exceptions
5.1
HTTP Response Codes
5.2
Exceptions
5.2.1
Service Exceptions
5.2.2
Policy Exceptions
A
Sandbox Service
A.1
Sandbox Service Design
A.1.1
Sandbox URI
A.2
Sandbox Scenarios
A.2.1
Successful Scenarios
Developer Guide
Page 4
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
A.2.2
Unsuccessful Scenarios
Developer Guide
Page 5
© Aepona 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
1
Subscriber Profile REST Overview
The U.S. Cellular Open API User Subscriber Profile web service allows an application to
query subscriber profile information of one or more U.S. Cellular subscribers identified by
their CTN. The service is accessible via the RESTful API, which is described in this
document.
2
Authentication
Connection to the US Cellular AMP Subscriber Profile web service by a TPA is made using
one-way TLS, where a server side certificate is required plus HTTP Basic Authentication.
3
Methods
The following method is available:
·
retrieve subscriber profile of one or more subscribers - section 4.1
HTTP GET command is used.
3.1
URIs
The URI of the resource is as follows:
address={address}
The following standard URL variables apply:
Name
Description
apiVersion
The Version of the API that the client is accessing: in this case, v1.
address
Address (CTN) of U.S. Cellular subscriber, in the format comprising:
1) 'tel:' protocol identifier,
2) country code of one preceded by '+',
3) ten digit CTN preceded by 1, for example, tel:+15087300001
Developer Guide
Page 6
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
Finally, the address must be must be URL-escaped where %3A represents
':' and %2B represents '+'.
Example: %3A%2B15087300001
4
Get Subscriber Profile
4.1
Retrieve Subscriber Profile Request
This operation is used by the TPA to request the subscriber profile of one or more U.S.
Cellular subscribers.
4.1.1 Request Example - Single Subscriber
%2B15087300001
HTTP/1.1
Accept: application/json
Host: developerportal.uscellular.com
Authorization: Basic QWVwb25hVfdghfdghdfghdfgWF6eHN3MjNl
4.1.2 Request Example - Multiple Subscribers
%2B15087300001&address=tel3A%2B15087300002 HTTP/1.1
Accept: application/json
Host: developerportal.uscellular.com
Authorization: Basic QWVwb25hVfdghfdghdfghdfgWF6eHN3MjNl
4.2
Request Parameters
Parameter
Data Type
Description
Optional
address
String
Address (CTN) of U.S. Cellular subscriber, in
No; one
the format comprising:
or more
Developer Guide
Page 7
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
1) 'tel:' protocol identifier,
2) country code of one preceded by '+',
3) ten digit CTN preceded by 1, for example,
tel:+15087300001
Finally, the address must be must be URL-
escaped where %3A represents ':' and %2B
represents '+'.
Example: %3A%2B15087300001
4.3
Retrieve Subscriber Profile Responses
The response content type for the Subscriber Profile API is application/json.
As a general practice, null elements are not returned in the responses.
The following types of responses are listed in this section:
· Successful response with subscriber profile for one CTN returned - section below
· Successful response with some of the subscriber profiles for the CTNs returned -
section 4.3.2
· Unsuccessful response with no external call made to retrieve subscriber profile -
4.3.3
Error information structures are summarised diagrammatically in section 4.5.
4.3.1 Response Example - One CTN - Success
HTTP/1.1 200 OK
Date: Thu, 31 Oct 2013 09:03:44 GMT
Server: Jetty(7.5.4.v20111024)
Content-Type: application/json
Content-Length: 684
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
{
Developer Guide
Page 8
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
"subscriberProfileList" : [ {
"address" : "tel:+15087300001",
"profileRetrievalStatus" : "RETRIEVED",
"inventoryData" : {
"prepaidFlag": true,
"subscriberHandsetSalesChannelCapableList" : {
"shscc" : [ "YES" ]
},
"subscriberHomeSwitchTimeZoneList" : {
"shstz" : [ "6" ]
},
"subscriberStatusList" : {
"ss" : [ "ACTIVE" ]
},
"subscriberAccountTypeList" : {
"sat" : [ "I" ]
},
"subscriberAccountSubTypeList" : {
"sast" : [ "R" ]
},
"subscriberPrimaryMDNindList" : {
"spmi" : [ "N" ]
},
"subscriberAccountList" : {
"sa" : [ "123456789" ]
}
}
} ]
}
Developer Guide
Page 9
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
4.3.2 Response Example - Multiple CTNs - Partial
Success
The example below returns some of the subscriber profiles successfully, and others not,
as indicated by the profileRetrievalStatus parameter value.
HTTP/1.1 200 OK
Date: Thu, 31 Oct 2013 09:03:44 GMT
Server: Jetty(7.5.4.v20111024)
Content-Type: application/json
Content-Length: 684
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
{
"subscriberProfileList" : [
"address" : "tel:+16309700001",
"profileRetrievalStatus" : "NOT_RETRIEVED",
"errorInformation" : {
"messageId" : "SVC0005",
"text" : "An external service error occurred. No profile information is available for %1",
"variables" : [ "tel:+16309700001" ]
}
}, {
"address" : "tel:+15087300001",
"profileRetrievalStatus" : "RETRIEVED",
"inventoryData" : {
"subscriberHandsetSalesChannelCapableList" : {
"shscc" : [ "YES" ]
},
"subscriberHomeSwitchTimeZoneList" : {
"shstz" : [ "6" ]
},
"prepaidFlag": true,
Developer Guide
Page 10
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
"subscriberStatusList" : {
"ss" : [ "ACTIVE" ]
},
"subscriberAccountTypeList" : {
"sat" : [ "I" ]
},
"subscriberAccountSubTypeList" : {
"sast" : [ "R" ]
},
"subscriberPrimaryMDNindList" : {
"spmi" : [ "N" ]
},
"subscriberAccountList" : {
"sa" : [ "123456789" ]
}
}
} , {
"address" : "tel:+15087300002",
"profileRetrievalStatus" : "RETRIEVED",
"inventoryData" : {
"subscriberHandsetSalesChannelCapableList" : {
"shscc" : [ "YES" ]
},
"subscriberHomeSwitchTimeZoneList" : {
"shstz" : [ "6" ]
},
"prepaidFlag": false,
"subscriberStatusList" : {
"ss" : [ "ACTIVE" ]
},
"subscriberAccountTypeList" : {
"sat" : [ "I" ]
Developer Guide
Page 11
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
},
"subscriberAccountSubTypeList" : {
"sast" : [ "E" ]
},
"subscriberPrimaryMDNindList" : {
"spmi" : [ "Y" ]
},
"subscriberAccountList" : {
"sa" : [ "999996789" ]
}
}
}, {
"address" : "tel:+1234567890",
"profileRetrievalStatus" : "ERROR",
"errorInformation" : {
"messageId" : "SVC0001",
"text" : "A service error occurred."
}
}]
}
4.3.3 Response Example - Unsuccessful
The exception in this unsuccessful example was thrown before Aepona made the external
call to retrieve the required subscriber profile. Therefore no subscriber profile content is
returned. Policy violations can result in exceptions of this type. See section 5.2 for the list
of policy and service error codes.
HTTP 400 Bad Request
Content-Type: application/json
Content-Length: 1234
Date: Thu, 04 Jun 2009 02:51:59 GMT
Developer Guide
Page 12
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
{"requestError": {
"serviceException": {
"messageId": "SVC0004",
"text": "No valid addresses provided in message part %1",
"variables": "%1 - request URI"
}
}}
4.4
Response Parameters
Successful responses are returned using the following hierarchy of data structures:
subscriberProfileList - an array, containing one or more
---subscriberProfile element - containing subscriber profile information per CTN, containing
----inventoryData element - with optional
----sub-elements - as supplied by the ESB, each of which can contain one or more
optional
----sub-element
----ProfileRetrievalStatus element - indicates status: Retrieved, Not Retrieved, with error
information, or Error (service or policy exception)
The details of each structure and sub-elements are described in the following sections.
4.4.1 subscriberProfileList /subscriberProfile Elements
Parameter
Data
Description
Usage
Type
subscriberProfileList
Object
All of the following
If the subscriber profile
[..1]
parameters are nested within
information is
'subscriberProfleList'
successfully retrieved
for a least one address
(CTN), then this
element must be
included. If the
subscriber profile
information isn't
successfully retrieved
Developer Guide
Page 13
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
Parameter
Data
Description
Usage
Type
for any of the
addresses, then a non-
200 HTTP response
code is returned, with a
Service or Policy
exception (see section
5.2) as applicable.
subscriberProfile
Object
This element is an array
If 'subscriberProfileList'
[1..N]
where each element in the
object is included, then
array either contains a) if
this object is
successfully retrieved, the
mandatory.
Subscriber Profile information
for a given address (CTN)
OR
b) if not successfully
retrieved, the error
information.
This object contains the
following elements:
1) 'address'
2) 'profileRetrievalStatus'
3) either a) the
'inventoryData', if the profile
information is successfully
retrieved for the specified
'address' OR b)
'errorInformation' if there is
an error in profile retrieving
the information for the
specified 'address'
address
String
The CTN of the U.S. Cellular
If 'subscriberProfile'
subscriber. See description
object is included, then
Developer Guide
Page 14
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
Parameter
Data
Description
Usage
Type
and example in section 4.1.
this object is
mandatory.
inventoryData
Object
For a given address (CTN), it
If the profile
contains the Subscriber
information is
profile information. This
successfully retrieved
object's elements are defined
for the specified
in section 4.4.2.
'address', then this
object is mandatory
errorInformation
Object
For a given address (CTN), it
If the profile
contains the error
information is not
information. This object's
successfully retrieved
elements are defined in
for the specified
section 4.4.3.
'address', then this
object is mandatory
profileRetrievalStat
String
If the profile information is
If 'subscriberProfile'
us
successfully retrieved for the
object is included, then
specified 'address', then this
this object is
element's value is
mandatory.
RETRIEVED.
If the profile information is
not successfully retrieved,
then this element's value is
NOT_RETRIEVED (when an
exception is returned from
the external subscriber profile
provider).
If an internal error or
external subscriber profile
provider timeout occurs, then
the value ERROR is returned.
Developer Guide
Page 15
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
4.4.2 inventoryData Structure Elements
The table below contains the full list of elements in this structure that may be returned in
the response. Of these, the ones currently sent by USCC are noted in black characters;
those not sent by USCC are in grey.
Parameter
Data
Description
Usage
Type
subscriberHandsetSale
Object
Defines whether or not a
An optional
sChannelCapableList
wireless device is capable of
element of
supporting a service on it. This
'inventoryData'
element contains the
object.
'subscriberHandsetSalesChannel
Capable' element.
subscriberHandsetSale
String
This element is an array where
If
sChannelCapable
[1..
each element in the array has a
'subscriberHandse
unbound
value of one of the following:
tSalesChannelCap
ed]
ableList' object is
a) YES
included, then
this object is
b) NO
mandatory, one
or more.
c) UNKNOWN
subscriberHomeSwitch
Object
Provides information on the
An optional
TimeZoneList
subscriber's home switch time
element of
zone. This element contains
'inventoryData'
the
object.
'subscriberHomeSwitchTimeZon
e' element.
subscriberHomeSwitch
String
This element is an array where
If
TimeZone
[1..
each element in the array is a
'subscriberHomeS
unbound
string.
witchTimeZoneLis
ed]
t' object is
included, then
this object is
mandatory, one
ore more.
Developer Guide
Page 16
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
prepaidFlag
Boolean
Provides information on the
An optional
subscriber's account type:
element of
'inventoryData'
a) true - Prepaid
object.
b) false - not Prepaid
Information not
available will
return an
SVC0005 error.
subscriberStatusList
Object
Provides information on the
An optional
subscriber's status. This
element of
element contains the
'inventoryData'
'subscriberStatus' element.
object.
subscriberStatus
String
This element is an array where
If
[1..
each element in the array has a
'subscriberStatusL
unbound
value of one of the following:
ist' object is
ed]
included, then
a) ACTIVE
this object is
mandatory, one
b) CANCELLED
or more.
c) RESERVED
d) SUSPENDED
e) UNKNOWN
subscriberAccountType
Object
Provides information on the
An optional
List
subscriber's account type. This
element of
element contains the
'inventoryData'
'subscriberAccountType'
object.
element.
subscriberAccountType
String
This element is an array where
If
[1..
each element in the array is a
'subscriberAccoun
unbound
string.
tTypeList' object
ed]
is included, then
this object is
mandatory, one
or more.
Developer Guide
Page 17
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
subscriberAccountSub
Object
Provides information on the
An optional
TypeList
subscriber's account sub-type.
element of
This element contains the
'inventoryData'
'subscriberAccountSubType'
object.
element.
subscriberAccountSub
String
This element is an array where
If
Type
[1..
each element in the array is a
'subscriberAccoun
unbound
string.
tSubTypeList'
ed]
object is included,
then this object is
mandatory, one
or more.
subscriberPrimaryMDN
Object
Provides information on the
An optional
indList
subscriber's MDN indicator.
element of
This element contains the
'inventoryData'
'subscriberPrimaryMDNind'
object.
element.
subscriberPrimaryMDN
String
This element is an array where
If
ind
[1..
each element in the array is a
'subscriberPrimar
unbound
string.
yMDNindList'
ed]
object is included,
then this object is
mandatory, one
or more.
subscriberAccountList
Object
Provides information on the
An optional
subscriber's account. This
element of
element contains the
'inventoryData'
'subscriberAccount' element.
object.
subscriberAccount
String
This element is an array where
If
[1..
each element in the array is a
'subscriberAccoun
unbound
string.
tList' object is
ed]
included, then
this object is
mandatory, one
or more.
Developer Guide
Page 18
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
subscriberFullNamList
Object
Provides information on the
An optional
subscriber's name. This
element of
element contains the
'inventoryData'
'subscriberFullNam' element.
object.
subscriberFullNam
String
This element is an array where
If
[1..
each element in the array is a
'subscriberFullNa
unbound
string.
mList' object is
ed]
included, then
this object is
mandatory, one
or more.
subscriberMDNList
Object
Provides information on the
An optional
subscriber's MDN. This element
element of
contains the 'subscriberMDN'
'inventoryData'
element.
object.
subscriberMDN
String
This element is an array where
If
[1..
each element in the array is a
'subscriberMDNLis
unbound
string.
t' object is
ed]
included, then
this object is
mandatory, one
or more.
subscriberMEIDList
Object
Provides information on the
An optional
subscriber's MEID. This
element of
element contains the
'inventoryData'
'subscriberMEID' element.
object.
subscriberMEID
String
This element is an array where
If
[1..
each element in the array is a
'subscriberMEIDLi
unbound
string.
st' object is
ed]
included, then
this object is
mandatory, one
or more.
subscriberMSIDList
Object
Provides information on the
An optional
subscriber's MSID. This
element of
element contains the
'inventoryData'
'subscriberMEID' element.
object.
Developer Guide
Page 19
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
subscriberMSID
String
This element is an array where
If
[1..
each element in the array is a
'subscriberMSIDLi
unbound
string.
st' object is
ed]
included, then
this object is
mandatory, one
or more.
subscriberESNList
Object
Provides information on the
An optional
subscriber's ESN. This element
element of
contains the 'subscriberMEID'
'inventoryData'
element
object.
subscriberESN
String
This element is an array where
If
[1..
each element in the array is a
'subscriberESNList
unbound
string.
' object is
ed]
included, then
this object is
mandatory, one
or more.
subscriberBillingCycleL
Object
Provides information on the
An optional
ist
subscriber's billing cycle. This
element of
element contains the
'inventoryData'
'subscriberBillingCycle' element.
object.
subscriberBillingCycle
String
This element is an array where
If
[1..
each element in the array is a
'subscriberBillingC
unbound
string.
ycleList' object is
ed]
included, then
this object is
mandatory, one
or more.
subscriberAccountAge
Object
Provides information on the
An optional
List
subscriber's account age. This
element of
element contains the
'inventoryData'
'subscriberAccountAge'
object.
element.
Developer Guide
Page 20
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
subscriberAccountAge
String
This element is an array where
If
[1..
each element in the array is a
'subscriberAccoun
unbound
string.
tAgeList' object is
ed]
included, then
this object is
mandatory, one
or more.
subscriberHandsetAge
Object
Provides information on the
An optional
List
subscriber's handset age. This
element of
element contains the
'inventoryData'
'subscriberHandsetAge'
object.
element.
subscriberHandsetAge
String
This element is an array where
If
[1..
each element in the array is a
'subscriberHandse
unbound
string.
tAgeList' object is
ed]
included, then
this object is
mandatory, one
or more.
subscriberBillingZipCo
Object
Provides information on the
An optional
deList
subscriber's billing zip code.
element of
This element contains the
'inventoryData'
'subscriberBillingZipCode'
object.
element.
subscriberBillingZipCo
String
This element is an array where
If
de
[1..
each element in the array is a
'subscriberBillingZ
unbound
string.
ipCodeList' object
ed]
is included, then
this object is
mandatory, one
or more.
subscriberRatePlanCod
Object
Provides information on the
An optional
eList
subscriber's rate plan code.
element of
This element contains the
'inventoryData'
'subscriberRatePlanCode'
object.
element.
subscriberRatePlanCod
String
This element is an array where
If
Developer Guide
Page 21
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
eCode
[1..
each element in the array is a
'subscriberRatePla
unbound
string.
nCodeList' object
ed]
is included, then
this object is
mandatory, one
or more.
subscriberServiceList
Object
Provides information on the
An optional
subscriber's rate plan code.
element of
This element contains the
'inventoryData'
'subscriberService' element.
object.
subscriberServiceCode
String
This element is an array where
If
[1..
each element in the array is a
'subscriberService
unbound
string.
List' object is
ed]
included, then
this object is
mandatory, one
or more.
4.4.3 errorInformation Structure Elements
Parameter
Data Type
Description
Usage
MessageId
String
Message identifier.
Mandatory
element
Text
String
Message text, with replacement variables
Mandatory
marked with %#, for example %1 for
element
variable 1.
Variable
String
Variables to substitute into Text string.
Optional
[0..unbounde
element
d]
4.5
Response Data Structure Diagrams
This section provides information on the exception scenarios and the structure of
information returned in unsuccessful and successful responses. The labels are internal
implementation java class names.
Developer Guide
Page 22
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
1. As illustrated in the example in section 4.3.2, a TPA JSON response can contain either
a subscriberProfileList or a requestError. The diagram below shows the data structure of
the SubscriberProfileReponse:
Figure 1: Response structure - with list or error returned
2. As illustrated in the example in section 4.3.3, an exception may be thrown before
Aepona makes the call to the external service. The diagram below shows the exception
structures in this case:
Figure 2: Response structure - with no external call made
3. The diagram below shows structures nested in SubscriberProfile data type (described
in section 4.4.1). It shows that an entry in subscriberProfileList can contain error
information from the external service, or inventoryData (described in section 4.4.2).
Developer Guide
Page 23
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
Figure 3: subscriberprofile data structure
Developer Guide
Page 24
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
5
Response Codes and Exceptions
5.1
HTTP Response Codes
Response Code
Explanation
200 OK
Success!
400 Bad Request
The request was invalid. An accompanying error message will
explain why. For instance, the MSISDN specified in the request
may not be a valid U.S. Cellular subscriber.
401 Unauthorized
The request requires user authentication and the authentication
failed. Authentication credentials were missing or incorrect.
403 Forbidden
The request is understood, but it has been refused.
404 Not Found:
The URI requested is invalid or the resource requested does not
exist. There is a mistake in the host or path of the service URI.
405 Method Not
The method specified in the Request-Line is not allowed for the
Allowed
resource identified by the Request-URI. For example, one
mistakenly used a HTTP POST to query for the subscriber profile
instead of a HTTP GET, where only HTTP GET is supported.
500 Internal Server
The server encountered an unexpected condition, which
Error
prevented it from fulfilling the request.
503 Service
The server is currently unable to handle the request due to a
Unavailable
temporary overloading or maintenance of the server. Please retry
the request.
5.2
Exceptions
5.2.1 Service Exceptions
A service exception describes the reason why the service cannot accept the request.
The following service exceptions may be thrown:
Error
Explanation
Developer Guide
Page 25
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
SVC0001 - Service error
An internal service-related error has occurred as a
occurred
result of a client invocation on the service. This
category can be used for implementation-specific
errors. Contact the support team.
SVC0002 - Invalid input value
An input parameter value is not of the expected type.
Check the parameter types and re-submit your
request.
SVC0004 - Invalid Address
The requested terminal device address was supplied
Format
in the wrong format
SVC0005 - An external service
The Service received an error from an external
error occurred.
source. Contact the support team if this persists.
SVC0006 - Timeout error
The Service timed out waiting for a response from an
received.
external source. Contact the support team if this
persists.
5.2.2 Policy Exceptions
A policy exception means that the request syntax is valid, however an operator policy has
been broken.
POL0001 - Policy error occurred
The above exception may be thrown to indicate a fault relating to a policy associated with
the service. This category can be used for implementation-specific errors such as:
Error Text
Explanation
POL-006: TPA exceeded its
The maximum rate of transactions is exceeded.
maximum allowed rate of transactions
Ensure that the rate of your requests is within
the limits set up in your SLA, e.g. 10 TPS
(Transactions Per Second).
POL-014: White List is enforced, and
A white list is enforced and the number is not in
address is not in White List
the white list. Check your SLA details.
POL-015: Black List is enforced, and
A black list is enforced and the number is in the
address is in Black List
black list. Check you SLA details.
Developer Guide
Page 26
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
POL-016: Max Requests is enforced,
The maximum number of requests for this
and max requests has been exceeded
service is exceeded. Contact the support team.
POL-017: Operation is not allowed
The method/operation is not supported in your
current SLA. Check your SLA and use a method
that is supported.
POL-040: Max Destination Addresses
A maximum destination address limit is
is enforced and maximum destination
enforced and it has been exceeded. Check your
addresses has been exceeded
SLA for the limit and re-submit your request.
Developer Guide
Page 27
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
A Sandbox Service
The sandbox service replicates real U.S. Cellular Open API User Subscriber Profile web
service and returns various response objects, or 'canned responses', to pre-configured
subscriber CTN values. It does not connect to any external interfaces. Developers can use
this to test different scenarios of their application without connecting to the real
subscriber profile service.
A.1
Sandbox Service Design
The Sandbox service flow is described below in outline:
1 Normal Subscriber Profile service is invoked up to the point where the external call is
made to the USCC ESB Remote Endpoint.
2 At this point the Sandbox route will be invoked instead of the real USCC ESB
Endpoint.
This flow ensures that all the validation logic defined in the normal service is executed
inside the original service itself.
3 Once the sandbox route is being executed, it will generate the relevant response
object based on the configured values against the CTN provided in the request.
The values are configured by the administrator as sandbox service properties.
A.1.1 Sandbox URI
The URI of the resource for sandbox service is as follows:
{apiVersion}/sandbox?address={address}
Sandbox Request Example - Single Subscriber Profile
%2B15087300004 HTTP/1.1
Accept: application/json
Authorization: Basic QWVwb25hVfdghfdghdfghdfgWF6eHN3MjNl
Host: developerportal.uscellular.com
Developer Guide
Page 28
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
A.2
Sandbox Scenarios
Sandbox responses are driven by the CTN sent in the request. A response will be
returned based on the validity of the request and the configured response against the
CTN value.
·Â If the request is invalid then the normal service flow will reject the request and return
the relevant response according to normal service specification.
·Â If the request is valid then the sandbox service will return a response based on the
configured details against the CTN. The scenarios are listed in the section below.
A.2.1 Successful Scenarios
The pre-configured CTN and request URI syntax, and expected responses are
summarised in the table below. The responses include an inventory data object with hard
coded values and with the status relative to the configured CTN value.
An example success response is shown below. The structure is common across all
responses.
!
The sandbox returns only a subset of the structural elements available for this
service. As stated in section 4.4.2, the production endpoint USCC sends only
those elements noted in black characters in the table, thus only those may be
returned.
Sandbox Response Structure
{
"subscriberProfileList" : [ {
"address" : "tel:+15087300001",
"profileRetrievalStatus" : "RETRIEVED",
"inventoryData" : {
"subscriberHandsetSalesChannelCapableList" : {
"shscc" : [ "YES" ]
},
"subscriberHomeSwitchTimeZoneList" : {
"shstz" : [ "+1200" ]
},
Developer Guide
Page 29
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
"prepaidFlag":true,
"subscriberStatusList" : {
"ss" : [ "ACTIVE" ]
},
"subscriberFullNamList" : {
"sfn" : [ "Russel Crow" ]
},
"subscriberAccountTypeList" : {
"sat" : [ "I" ]
},
"subscriberAccountSubTypeList" : {
"sast" : [ "H" ]
},
"subscriberPrimaryMDNindList" : {
"spmi" : [ "Yes" ]
},
"subscriberMDNList" : {
"smdn" : [ "tel:+4433433312322" ]
},
"subscriberMEIDList" : {
"smeid" : [ "000000000000" ]
},
"subscriberAccountAgeList" : {
"saa" : [ "5" ]
},
"subscriberAccountList" : {
"sa" : [ "222" ]
}
}
} ]
}
Developer Guide
Page 30
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
Table 1: Success Scenarios and Canned Responses
Scenario
Steps
Result
Retrieve ACTIVE
Send a request with address tel:
You will get a JSON response as
Subscriber Profile
+15087300001.
shown in Sample 1 but with
following difference.
{port}/cxf/subscriberProfile/v1/sandb
"subscriberStatusList" : {
ox?address=tel%3A%2B15087300001
"ss" : [ "ACTIVE" ]
}
Retrieve
Send a request with address tel:
You will get a JSON response as
CANCELLED
+15087300002.
shown in Sample 1 but with
Subscriber Profile
following difference.
{port}/cxf/subscriberProfile/v1/sandb
"subscriberStatusList" : {
ox?address=tel%3A%2B15087300002
"ss" : [ "CANCELLED" ]
}
Retrieve RESERVED
Send a request with address tel:
You will get a JSON response as
Subscriber Profile
+15087300003.
shown in Sample 1 but with
following difference.
{port}/cxf/subscriberProfile/v1/sandb
"subscriberStatusList" : {
ox?address=tel%3A%2B15087300003
"ss" : [ "RESERVED" ]
}
Retrieve
Send a request with address tel:
You will get a JSON response as
SUSPENDED
+15087300004.
shown in Sample 1 but with
Subscriber Profile
following difference.
{port}/cxf/subscriberProfile/v1/sandb
"subscriberStatusList" : {
ox?address=tel%3A%2B15087300004
"ss" : [ "SUSPENDED" ]
}
Retrieve UNKNOWN
Send a request with a valid address
You will get a JSON response as
Subscriber Profile
not configured for a particular scenario
shown in Sample 1 but with
with the format tel:+1XXXXXXXXXX.
following difference.
"subscriberStatusList" : {
{port}/cxf/subscriberProfile/v1/sandb
"ss" : [ "UNKNOWN" ]
ox?address=tel%3A
}
%2B1XXXXXXXXXX
Developer Guide
Page 31
© Intel Corporation 2015. All rights reserved.
USCC AMP Subscriber Profile REST
Document Version 1.3
A.2.2 Unsuccessful Scenarios
Service and Policy failure scenarios are handled as in a normal service as described in
section 5, since the request comes through all components as normal before being
diverted from reaching the real ESB endpoint.
End of Document
Developer Guide
Page 32
© Intel Corporation 2015. All rights reserved.