Cisco IoTConnectivity Management Platform

Application
Programming Interface
User Guide
OPERATOR ADVANTAGE

An introduction to the Control Center platform APIs for operators with

Advantage accounts.

NOVEMBER 12, 2020 © 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved.
 TABLE OF CONTENTS
APPLICATION PROGRAMMING INTERFACE USER GUIDE 1
API Overview 6
API Policies and Best Practices 7
Backward Compatibility 10
API Sandbox 11
REST APIs 12
Getting Started 14
Roles with Access 14
Base URL 15
API Sandbox 16
API Key 16
Authentication 17
Resources 18
Requests and Responses 19
Pagination 27
Date/Time Formats 28
Error Handling 29
SIM Status Values 29
Language Values 30
Currency Values 30
User Role Values 31
Industry Vertical Values 32
SMS Validity Period 33
Try It Tool 34
Accounts 36
Get Account Details 36
Get All Accounts 53
Create Account 59
Edit Account Details 65
Get Account Application Settings 70
Edit Account Application Settings 77
Get Account Billing Settings 86
Edit Account Billing Settings 91
Get Available Rate Plans for an Account 98

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 2
 Edit Available Rate Plans for an Account 100
API Key 102
Create/Reset API Key for Given User 102
Get API Key 104
Reset API Key for Current User 106
Customers 108
Get Customer Details 108
Edit Customer Details 111
Create Customer 116
Devices 121
Search Devices 121
Get Device Details 125
Edit Device Details 129
Get Device Audit History 135
Get Device Location 140
Get Device Usage 145
Get Device Usage by Zone 149
Get Session Details 155
Echo 158
Echo 158
Multi-Party Billing 161
Get Partner Accounts for Device 161
Assign Device to Partner Account 163
Change Partner Rate Plan for Device 166
Remove Device from Partner Account 168
Rate Plans 170
Get Rate Plans 170
SMS Messages 183
Search SMS 183
Get SMS Details 187
Send SMS 191
Usages 195
Get Usage by Rate Plan 195
Users 201
Get User Details 201
Get All User Details 205
Create User 208
Edit User Details 212
Reset User Password 216
Delete User 218
REST Error Messages 220
REST API/Role Matrix 230
REST API Troubleshooting Checklist 231

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 3
 SOAP APIs 234
Getting Started 235
SOAP API Development Process 236
SOAP API Code Standards 238
WSDL Files 241
SOAP API Error Handling 242
SOAP API Functions 243
Devices 243
Global SIMs 245
Messages (SMS) 246
Rate Plans 248
Usage 249
Invoices 249
Users 250
Test 250
SOAP API Use Cases 251
Analyzing Device Usage 251
Synchronizing Databases 252
Working with Multiple Operators 253
Understanding Log-in Credentials 253
Storing Log-in Credentials 254
Tutorials 256
Java 256
C# 258
Perl 260
PHP 261
Ruby 262
XML Samples 263
SOAP Error Messages 264
SOAP API/Role Matrix 273
SOAP API Troubleshooting Checklist 273
Push APIs 280
Typical Event Sequence 281
Implementing a Push Receiver 282
Sample Push API Message 285
SSL Certificates 286
Push API Reference 290
AccountTransfer 292
AvailableStaticIpAddress 293
CtdUsage 294
CtdVoiceUsage 295
CtdVoiceZUsage 296
CtdZUsage 297

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 4
 ImeiWhitelist 298
LbsCellIdChange 299
MonthlyDataUsage 300
MonthlySmsUsage 301
MsisdnChange 302
NetworkRegistrationInZone 303
NoConnection 304
OrderCallback 305
Past24HDataUsage 307
Past24HVoiceUsage 308
PremiumServiceOrderType 309
RegistrationInZone 312
SecureSimAlert 313
Session 314
SimDataLimit 315
SimExpiration 316
SimFieldChange 317
SimImeiChange 318
SimPlanComplete 319
SimRatePlanChange 320
SimStateChange 321
SmsMoReceived 322
SmsUsage 323
TooFewDailyConnection 324
TooManyCtdConnection 325
TooManyDailyConnection 326

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 5
 API OVERVIEW
The Cisco Control Center platform provides an application programming
interface (API) that allows you to access and edit data in Control Center
from an external application. Using the API, you can perform many of the
same tasks you can handle through Control Center’s web interface,
including:
l Managing the device lifecycle
l Monitoring usage
l Sending messages to a device
l Assigning a rate plan to a device

Control Center offers multiple types of APIs:

SOAP APIs
The SOAP APIs have been available for many years and
provide a wide range of functions. Basic access to these
APIs is available to all accounts. Learn more

REST APIs
The REST APIs provide device attributes, usage
information, session details, and more. Over time this set
of APIs will grow. Learn more

Push APIs
Control Center uses push APIs to notify you when an
automation rule triggers. You must implement a push
receiver to interpret the messages. Learn more

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 6
 Real Time Data. REST and SOAP APIs are not intended to provide real-
time monitoring of service usage. For immediate feedback when certain
conditions occur, use automation rules.

Backward Compatibility. Follow these guidelines to ensure that your

application code functions properly with any API framework changes.

API Policies and Best Practices

Cisco has established an API fair use policy to ensure an optimal experience
for all Control Center users. Any client-side code that uses Control Center
APIs must adhere to the limitations described below.

Concurrent Connections
Cisco advises enterprises to avoid concurrent processing because it has the
potential to slow down response time considerably. We recommend using
APIs in single-threaded applications or routines only. Accounts using APIs
in multi-threaded scenarios may experience throttling or other restrictions,
depending on the circumstances.

Policy: Use single-threaded code—one API call at a time.

Calls Per Second

Cisco ensures effective API performance by limiting the number of API calls
an account can make per second. By default, the limit is 5 calls per second,
but this number may vary for individual accounts. There is no limit for
service providers. If the account exceeds the limit, subsequent API calls
within the one second measurement period will receive the response
shown in the table below, depending on the API type. After an appropriate
delay, the program should retry the API call.

API Type Return Code Message

REST 40000029 Rate Limit Exceeded

SOAP 400101 License has exceeded the rate limit for

API calls

As we continue to refine the platform for speed and reliability, Cisco may
update the calls per second limit from time to time. These updates may
occur without advance notice, however we will document them in the
Release Notes.
Be aware that this limit includes API calls made by both the account and
the account's customers. For example, if an account has two API users and

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 7
 they, along with five of their customers, made simultaneous API calls,
Control Center would attribute a total of 7 calls per second to the account.
The initial API calls would succeed, but after the limit is hit, the rest of the
API calls would return one of the messages shown above.
The limit also applies to the combination of REST and SOAP API calls. For
example, suppose an account made 1 REST API call and 1 SOAP API call
simultaneously and, at the same time, one of the account's customers made
a single REST API call. Control Center would attribute 3 calls per second to
the account.

Policy: Limit calls to 5 per second.

Best Practices
The following tips can help you avoid throttling or other usage restrictions
that may occur when your API use is excessive.

Add Rate Limiting Code

The best way to avoid exceeding the calls per second limit is to create
single-threaded code. However, you may have a scenario where that's not
possible. For example:
l Multiple API users are making calls.
l You need to use both REST and SOAP functions.
l You have a high volume of calls requiring multi-threaded processes.

In these cases, we recommend creating a rate limiting routine that

monitors and regulates your API calls. For instance, if your account receives
numerous error messages when processing calls, you might introduce a
wait time between API calls. You can increase the wait time until the errors
stop.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 8
 Pseudo Code Example. The following pseudo code illustrates how rate
limiting code might work.

// DISCLAIMER: THIS EXAMPLE IS PROVIDED FOR ILLUSTRATION PURPOSES ONLY,

// AND WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED

WHILE ( <<list is not empty>> )

{
// API_call attempts to perform an action to update the DEVICE status
// it returns the API response code
response = API_call( <<list element>> )

// API call returns the "limit exceeded" error, increase loop delay
IF ( response == ERROR_LIMIT_EXCEEDED )
{
delay += ADJUST_DELAY_INCR
}
ELSE
{ // ensure delay never goes below 0
IF ( delay > ADJUST_DELAY_DECR )
{
delay -= ADJUST_DELAY_DECR
}
ELSE
{
delay = 0
}
}

sleep( delay )
}

Adjust Call Frequency

When tracking device usage with APIs, it is important to align your API
calls with the frequency of your operator updates.
For example, if your operator updates their usage information once every 6
hours, there's no need to request the information via API more often than
once every 6 hours. Also, there is often a delay between the time when
usage data is available and when Control Center receives that usage data
from the operator. In some cases, the delay can be as long as 24 hours.

Use Caching
Cisco encourages local caching. For example, instead of calling an API on
every page load, create a simple routine to check the cache once a day.

Use Filters to Limit API Calls

Avoid unnecessary API calls by checking for certain conditions before you
execute a program. For example:
l If a device has been deactivated, do not check for usage.
l If an account has not requested usage on a device, do not check every
hour.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 9
 Lengthen Times Between Searches
If you receive API responses that are empty or unchanged, increase your
query time. For example, consider running your queries once a day rather
than every two hours.

FTP Reports. For enterprises that require access to large amounts of data
on a daily basis, FTP reports may be a better solution than APIs. See the
reports chapter in the Control Center User Guide for more information.

Backward Compatibility
Cisco regularly updates our APIs to provide new or enhanced functionality.
Our goal is to keep our API changes backward-compatible within the same
API version (see API Versions on the facing page) so that you don't have to
update your code whenever we make these changes.
Backward-compatible changes for our SOAP and REST APIs include:
l Adding new APIs
l Adding optional API request parameters
l Adding new fields to existing API responses
l Adding new values to existing API parameters that have enumerated
sets of values
l Adding HTTP response headers or adding values to existing response
headers

Backward-compatible changes for our push APIs include:

l Adding new Push API event types
l Adding HTTP POST form parameters
l Adding new fields to the “data” XML content
l Adding new values to existing API parameters that have enumerated
sets of values
l Adding HTTP request headers or adding values to existing request
headers

You should write your API clients (for SOAP and REST APIs) and push
receivers (for push APIs) with the expectation that these API changes will
happen, so that they can handle such changes gracefully. For example, do
not hard-code to a fixed set of API response fields, since new response
fields may be added in the future; instead, look for only the fields that you
are interested in, and ignore any other fields.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 10
 While Cisco strives to ensure that the majority of API changes are
backward-compatible, there are times when incompatible changes need to
be made. Backward-incompatible changes include:
l Removing or renaming an API, request parameter, response field, or
enum value
l Changing the visible behavior of existing APIs

Through the Release Notes, Cisco will provide at least six months' notice
before backward-incompatible changes go into effect. This notice will
include specific information about the change along with instructions for
upgrading your code without service disruption.

API Versions
Every API function includes a version number that identifies the API’s
structure and behavior. Cisco increments this version number under the
following circumstances:
l The API receives a backward-incompatible change AND
l The previous version of the API continues to be supported.

Refer to the detailed documentation to learn more about version numbers

for each type of API.

API Sandbox
For API development purposes, Control Center maintains a sandbox
environment, completely separate from the production environment. In this
protected environment, you can familiarize yourself with the APIs and try
your applications on test data.
If you decide to develop in the sandbox environment, you must submit a
change request in Control Center asking for sandbox access. You can use
this sandbox account to access Control Center through either the web
interface or the APIs. If your enterprise accounts want to use the sandbox
environment, Cisco will work with you to set up an account for them.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 11
 Chapter 1

REST APIS
The following table lists all the available REST API functions. For general
information about how to use these APIs, see Getting Started.

API Function Description

Accounts

Get Account Details Returns information about a given account.

Get All Accounts Returns information about all accounts.

Create Account Creates an enterprise account.

Edit Account Details Modifies attributes for a given account.

Get Account Application Returns information about application settings for

Settings a given account.

Edit Account Application Modifies attributes about application settings for

Settings a given account.

Get Account Billing Returns information about billing settings for a

Settings given account.

Edit Account Billing Modifies attributes about billing settings for a

Settings given account.

Get Available Rate Plans Returns information about available rate plan for
for an Account a given account.

Edit Available Rate Plans Modifies attributes about available rate plans for
for an Account a given account.

API Key

Create/Reset API Key for Creates or resets a given user's API key.
Given User

Get API Key Returns the API key for a given user.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 12
 API Function Description

Reset API Key for Current Resets the API key for the current user.
User

Customers

Get Customer Details Returns information about a given customer.

Create a Customer Creates a customer.

Edit Customer Details Modifies attributes for a given customer.

Devices

Search Devices Searches for devices based on various filters.

Get Device Details Retrieves detailed information for a given device.

Edit Device Details Modifies any device attributes such as SIM status,
rate plan, communication plan, custom fields and
other identifiers.

Get Device Location Returns location history information for a given

device during a specified time period.

Get Device Audit History Returns information about changes made to a

given device.

Get Device Usage Retrieves usage-related details for a given device.

Get Device Usage by Zone Returns usage details for a given device, based on
a specified zone and billing cycle.

Get Session Details Retrieves information related to the current or

most recent session for a given device.

Multi-Party Billing

Get Partner Accounts for a Get partner accounts for a device.

Device

Assign Partner Account to Assign partner account to device.

Device

Change Partner Rate Plan Change partner rate plan for device.
for Device

Remove Partner Account Remove partner account from device.

from Device

Rate Plans

Get Rate Plans Retrieves information about published rate plans.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 13
 API Function Description

SMS Messages

Search SMS Searches for messages that have been sent or

received during a specified timeframe.

Get SMS Details Retrieves detailed information about a message.

Send SMS Sends an SMS message to a device.

Usages

Get Usage by Rate Plan Returns usage information for all devices using a
given rate plan.

Users

Get User Details Returns information about a given user.

Get All User Details Returns information about all users.

Create User Creates a user.

Edit User Details Modifies attributes for a given user.

Reset User Password Resets the web interface password for a given
user.

Delete User Deletes a given user.

General

Echo Returns the value passed.

Getting Started
Roles with Access
Service provider, account, and customer users can use the APIs. However,
user access is limited by the following:
l Access Type. The user must have an Access Type of API Only or Both
API and UI in order to access the APIs. You can find that information
on the User Details page: Admin > Users > User Name link > Access
Type.
l Role. If a user with UI access can perform the function within the
Control Center web interface, then a user with the same role and
API access will be able to complete the task via an API call. There is
no single role that will guarantee access for all function calls. See the
API/Role matrix in the Knowledge Base for a complete list of roles
and the APIs they can use.

Typically, an enterprise will create user accounts with access to both the UI
and the APIs for their engineering team during development. For auditing

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 14
 purposes, Cisco recommends that production code use a dedicated Control
Center user whose sole purpose is to execute API functions. When you
create the user, you can specify that the user has API-only access to Control
Center.

Field Restrictions. While multiple roles may have access to the same API,
not every role will have access to all the fields listed in the documentation.
You can verify field access for a particular role by logging into the web
interface as a user with the same role who also has web interface access
and then looking for the field.

AccountAPIOnly Role. This legacy role has access to Control Center

through the API, but not through the web interface. The purpose of this
role was to provide restricted access to Control Center for operator
partners using a different platform. We recommend that current users take
advantage of the Access Type attribute to create users with API-only access
to Control Center rather than creating users with the AccountAPIOnly role.

IP Address Restrictions . If an enterprise implements IP Address

Restrictions, an API user might not have API access if their IP address falls
within a restricted range.

Base URL
The Control Center REST API is securely available over HTTPS. The
Knowledge Base displays your base URL on the REST API Getting Started
page. The base URL also appears as part of the resource URL on every
REST API reference page.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 15
 API Sandbox
For API development purposes, Control Center maintains a sandbox
environment, completely separate from the production environment, that
you can use to test your code. If you decide to develop in the sandbox
environment, you must submit a change request in Control Center asking
for sandbox access.
Base URL for Sandbox: https://rws-jpotest.jasper.com/rws/api/
If you use the sandbox account to test your code, you'll need to replace the
credentials and URL in your calls when you’re ready to put your code into
production. Be aware that you cannot migrate any data from the sandbox
environment to the production environment or vice versa.

API Key
Each user with API access has a unique API key that they must use in the
function calls. Be aware that you'll need different API keys for the
production and sandbox environments.
There are two ways to request a unique API Key for your user name:
From the Knowledge Base. Click the "Generate new key" link on any
REST API reference page.

After you generate your API key, it appears at the top of every function
page in the Knowledge Base.
A user with API-only access can also reset their API key using the
Create/Reset API Key for Given User API, if needed.
From the User Profile page. Click the Generate API Key button on the
User Profile or User Details page.

The new key appears as a series of asterisks. Click the Show API Key button
to view and copy the actual values. Click the Reset API Key button to reset

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 16
 an existing key that has been compromised.
A user must have web interface access to Control Center in order to create
or view their API key. Users with API Only access must rely on an
administrative user with appropriate privileges to generate an API key for
them in the User Details page. Although administrator users can generate
and view API keys for users with the API Only access type, they cannot
perform those functions for users with Both API and UI access types.

Authentication
All API calls must be authenticated through the HTTP Basic Authentication
scheme. To do this, you create an authorization header that you send as
part of the API request. This header contains encoded versions of a Control
Center user name and its associated API key.
Follow these instructions to create an authorization header:

1. Combine the user name and API key into a single string with a colon
separating the values. For example, if the user name is starterkit and
the API key is d703f52b-1200-4318-ae0d-0f6092b2e6ab, the
concatenated string would be:
starterkit:d703f52b-1200-4318-ae0d-0f6092b2e6ab

2. Encode the concatenated string using Base64 (i.e. RFC2045-MIME):

c3RhcnRlcmtpdDpkNzAzZjUyYi0xMjAwLTQzMTgtYWUwZC0wZjYw
OTJiMmU2YWI=

3. Set the Authorization header value to Basic followed by the encoded

string from step 2. Make sure there is a space between Basic and the
encoded string:
Basic c3RhcnRlcmtpdDpkNzAzZjUyYi0xMjAwLTQzMTgtYWUwZC0w
ZjYwOTJiMmU2YWI=

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 17
 Resources
Control Center supports the following resources and their associated
functions:

Resource Functions

Accounts l Get Account Details

l Get All Accounts
l Create Account
l Edit Account Details
l Get Account Application Settings
l Edit Account Application Settings
l Get Account Billing Settings
l Edit Account Billing Settings
l Get Available Rate Plans for an Account
l Edit Available Rate Plans for an Account

API Key l Create/Reset API Key for Given User

l Get API Key
l Reset API Key for Current User

Customers l Get Customer Details

l Create a Customer
l Edit Customer Details

Devices l Search Devices

l Get Device Details
l Get Device Location
l Get Device Usage
l Get Device Usage by Zone
l Get Device Audit History
l Get Session Details
l Edit Device Details

Echo l Echo

Multi-Party Billing l Get Partner Accounts for Device

l Assign Device to Partner Account
l Change Partner Rate Plan for Device
l Remove Device from Partner Account

Rate Plans l Get Rate Plans

SMS Messages l Search SMS Messages

l Get SMS Details
l Send an SMS

Usages l Get Usage by Rate Plan

Users l Get User Details

l Get All User Details
l Create User
l Edit User Details
l Reset User Password
l Delete User

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 18
 Requests and Responses
When you make a REST API request, Control Center returns a JSON-
formatted response. The documentation for each API function lists the
request parameters and contains a sample JSON response for that function.
For all GET functions, you can request a partial response to return just the
data of interest to you. For example, if you want to get the rate plan for a
particular device, you can instruct the Get Device Details function to return
the rate plan name only and no other fields. You can request one or more
fields, including subfields, subfields within an array, and subfields of any
depth in a hierarchy.

Partial Response Guidelines

When requesting partial responses, keep in mind these guidelines. For use
cases and sample code, see the following section.
l Syntax. Use "fields=" followed by a comma-separated list of field
names with no spaces between names. The GET function returns the
fields in the order you request them. For example,
"fields=smsMsgId,messageText,messageType,status" returns four
attributes for a particular SMS message: ID, content, type (MO or MT),
and status. You must specify the individual fields you want in the
response. Otherwise, the function returns nothing.
l Hierarchies. To indicate fields in a hierarchy, use a forward slash.
For example,
"field=contact/name,contact/email,billingAddress/country" returns
the name and email of the contact person and the country associated
with the billing address.
l Wildcards. You can use an asterisk (*) to request all the subfields of
a parent field. For example, "field=shippingAddress/* returns all the
attributes of the shipping address. If you omit the asterisk and do not
specify a subfield by name, the function does not return any subfields.
For example, "field=shippingAddress/" returns no data.
l Errors. If the function call incorrectly formats the request parameters
or uses an incorrect field name, Control Center returns as much data
as it can, but does not supply an error message. For example,
"field=iccid,ratePlan,commPlan" returns the ICCID and the rate plan
name only. The function does not return the communication plan
because the parameter should be "communicationPlan" not
"commPlan". Similarly, "field=contact/ name, contact/email" returns
the contact email, but not the contact name. Control Center trims
spaces before and after parameters, but not within them. Be aware
that Control Center ignores duplicate parameters.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 19
 l API Functions. You can request partial responses for all GET
functions. The "fields=" request parameter does not work with PUT,
POST, or DELETE functions.
l Try It Support. Currently, you cannot request partial responses in
the Knowledge Base Try It tool.

Partial Response Use Case #1: One field

Syntax: fields=field1
Example: Get Device Details
https://restapi1.jasper.com/rws/api/v1/devices/8988216716970004975?f
ields=status
Sample Response:

{
"status": "ACTIVATED"
}

Partial Response Use Case #2: Multiple fields

Syntax: fields=field1,field2,field3
Notes: Do not use spaces between field names.
Example: Get Device Details
https://restapi1.jasper.com/rws/api/v1/devices/8988216716970004975?f
ields=
iccid,status,ratePlan
Sample Response:

{
"iccid": "8988216716970004975",
"status": "ACTIVATED",
"ratePlan": "Monthly Flexible Pool 2GB"
}

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 20
 Partial Response Use Case #3: Subfields
Syntax: fields=field1/subfield1,field1/subfield2
Example: Get Customer Details
https://restapi1.jasper.com/rws/api/v1/customers/16716970?fields=
name,
billingAddress/addressLine1,
billingAddress/postalCode
Sample Response:

{
"name": "Northwest Region",
"billingAddress": {
"addressLine1": "123 Main Street",
"postalCode": "10155"
}
}

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 21
 Partial Response Use Case #4: Subfields in an array
Syntax: fields=field1/subfield1,field1/subfield2
Example: Get Device Usage in a Zone
https://restapi1.jasper.com/rws/api/v1/devices/89302720396916972826
/usageInZone?fields=
iccid, cycleStartDate, cycleEndDate,
deviceCycleUsageInZones/ratePlan,
deviceCycleUsageInZones/ratePlanVersion,
deviceCycleUsageInZones/zone,
deviceCycleUsageInZones/dataUsage,
deviceCycleUsageInZones/dataUsageUnit
Sample Response:

{
"iccid": "89302720396916972826",
"cycleStartDate": "2019-04-18T00:00:00.000Z",
"cycleEndDate": "2019-05-17T23:59:59.000Z",
"deviceCycleUsageInZones": {
"Acme Monthly Individual, 3": [
{
"ratePlan": "Acme Monthly Individual",
"ratePlanVersion": "3",
"zone": "Roaming",
"dataUsage": 20971924,
"dataUsageUnit": "bytes"
},
{
"ratePlan": "Acme Monthly Individual",
"ratePlanVersion": "3",
"zone": "Other Usage",
"dataUsage": 1375776,
"dataUsageUnit": "bytes"
}
]
}

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 22
 Partial Response Use Case #5: All subfields
Syntax: fields=field1/*
Notes: To include subfields in the response, you must specify the individual
field names or use an asterisk (*) to return all fields. If you use a forward
slash alone, the function returns no subfields.
Example: Get Customer Details
https://restapi1.jasper.com/rws/api/v1/customers/16716970?fields=
name,
contacts/name,
contacts/email,
billingAddress/*
Sample Response:

{
"name": "Northwest Region",
"contacts": [
{
"name": "John Doe",
"email": "jdoe@acme.com"
},
{
"name": "Annette Wong",
"email": "awong@acme.com"
}
]
"billingAddress": {
"addressLine1": "593 Palm Dr.",
"addressLine2": null,
"city": "Los Angeles",
"state": "CA",
"country": "USA",
"postalCode": "91201"
}
}

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 23
 Partial Response Use Case #6: Subfields of any depth
Syntax: fields=field1/subfield1/subsubfield1
Example: Get Account Details
https://restapi1.jasper.com/rws/api/v1/accounts/100020704?fields=
accountName,
security/passwordPolicySettings/ui/passwordExpirationInDays,
security/passwordPolicySettings/ui/content/minLength
Sample Response:

{
"accountName": "Acme Widgets",
"security": {
"passwordPolicySettings": {
"ui": {
"passwordExpirationInDays": "90",
"content": {
"minLength": "6"
}
}
}
}
}

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 24
 Partial Response Code Samples
Make sure to use your own URL and user credentials.
Python

import requests
import json
import base64
import pprint

# Replace the URL and credentials with your own

apiUrl= 'https://restapi1.jasper.com/rws/api/v1/accounts/100000000'

parameters= {'fields': "accountId,shippingAddr/addr1"}

myResponse = requests.get(url=apiUrl, auth=(raw_input("username: "),raw_input

("api_key: ")), params=parameters)
# For successful API call, response code will be 200 (OK)
if(myResponse.ok):
# Loading the response data into a dict variable
# json.loads takes in only binary or string variables so using content to
fetch binary content
# Loads (Load String) takes a Json file and converts into python data
structure (dict or list, depending on JSON)
pp = pprint.PrettyPrinter(indent=4)
jData = json.loads(myResponse.content)
pp.pprint(jData)
else:
# If response code is not ok (200), print the resulting http error code
with description
myResponse.raise_for_status()

Node.js

var request = require('request');

var body = [];

// Replace the URL and credentials with your own

request.get
('https://restapi1.jasper.com/rws/api/v1/accounts/100000000?fields=accountID
,shippingAddr/addr1').auth('user_name', 'password', false)
.on('error', function(error){
console.log('Error:', error);
})
.on('response', function(response) {
console.log(response.statusCode); // return statusCode
console.log(response.headers['content-type']); // return contentType
})
.on('data',function(chunk){
body.push(chunk);
})
.on('end',function(){
body = Buffer.concat(body).toString();
console.log(body);
});

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 25
 Ruby

#!/usr/bin/ruby -w
require 'rest-client'
require 'json'

# Replace the URL and credentials with your own

url =
'https://restapi1.jasper.com/rws/api/v1/accounts/100000000?fields=accountId,
shippingAddr/addr1'

response = RestClient::Request.execute(
method: :get,
url: url,
user: 'user_name',
password: 'password',
headers => {:accept => :json}
)
puts JSON.pretty_generate(JSON.parse(response))

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 26
 Pagination
For functions that typically return numerous records (such as Search
Devices and Search SMS), the API provides pagination controls that allow
you to process one set of results and then request more.
These request parameters manage the pagination process:

Request Parameter Description

pageSize Specifies the number of records returned in each

response page. The maximum value is 50. The
value defaults to 50.

pageNumber Specifies the number of the response page to

return. This value defaults to 1.

These response values allow your code to process the returns properly:

Response Value Description

pageNumber An integer specifying the number of the current

response page.

lastPage A true or false value indicating whether the

current response page is the last in the series.

For example, the first API request would define the number of records to
include in the response (pageSize=50) and ask for the first page of records
(pageNumber=1). The response would send an array containing the first 50
records and then let you know if there are any more pages to return
(lastPage=false).
The second request would define the page size again (pageSize=50) and
ask for the second page of results (pageNumber=2). The second response
would return the next 50 records and alert you if there were more records
to retrieve (lastPage=false). This process would continue until one of the
responses indicates that the current page is the last page of results
(lastPage=true).

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 27
 Date/Time Formats
The REST APIs use the following date and time formats for requests and
responses.

Use Case Format

Search Requests, for example: yyyy-MM-ddTHH:mm:ssZ

(ISO 8601 standard)
• Search Devices
(modifiedSince) Example: 2016-04-18T17:31:34+00:00
• Search SMS (fromDate)

Edit Device Request yyyy-MM-ddZ

(effectiveDate) (ISO 8601 standard; default time zone is UTC)
Get Device Usage in a Zone Example: 2016-04-18Z or 2016-04-18+05:00
Request
(cycleStartDate)

Responses, for example: yyyy-MM-dd HH:mm:ss.SSSZ

(ISO 8601 standard, based on UTC time)
• Get Device Details
(dateShipped) Example: 2016-04-18 17:31:34.121+0050
• Get Session Info
(lastSessionEndTime)

Get Device Usage by Zone yyyy-MM-ddTHH:mm:ss.SSSZ

Response (all dates) (ISO 8601 standard)
Example: 2016-12-06T15:58:06.466Z

Response timestamps (some) UNIX Epoch clock format. This format counts
the number of seconds since the start of the
UNIX Epoch on January 1, 1970 (UTC). There
are a number of converters available online.
Example: 1571416432
(equivalent to October 18, 2019 at 4:33pm
UTC)

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 28
 Error Handling
The REST APIs use standard HTTP status codes as well as business-specific
error messages. If an error occurs, Control Center will return a JSON
response containing an error code and an error message. For example:

{
"errorMessage": "The API credentials are invalid.",
"errorCode": "10000001"
}

The documentation for each API function contains a list of the errors that
may occur for that function.
The standard HTTP status codes are shown below.

HTTP Status Code Description

200 Success

202 Accepted. The request is scheduled for processing

and the task should be complete within several
seconds.

400 Bad request

401 Invalid credentials

404 Resource not found

500 Server error

SIM Status Values

Many API functions take the device SIM status as a parameter or return the
information in the response. Following is a list of the values you may see,
depending on your role.
l ACTIVATED
l ACTIVATION_READY
l DEACTIVATED
l INVENTORY
l ONHOLD (Start SIM state)
l PURGED
l REPLACED
l RETIRED
l TEST_READY

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 29
 Language Values
Several API functions take the language preference as a request parameter
or return the information in the response. Here are the valid values:
l "English"
l "English (UK)"
l "Portuguese (BR)"
l "Portuguese (PT)"
l "Spanish (MX)"
l "Spanish (ES)"
l "German"
l "French"
l "Japanese"
l "Russian"
l "Dutch"
l "Chinese (Simple)"
l "Chinese (Traditional)"
l "Indonesian"
l "Italian"
l "Thai"
l "Swedish"
l "Korean"

Currency Values
Several API functions take currency as a request parameter or return the
information in the response. Here are the valid values:

l AED l DKK l JPY l NZD

l ARS l EEK l KRW l PYG
l AUD l EUR l KZT l RUB
l BOB l GBP l LTL l SAR
l BRL l GTQ l LVL l SEK
l CAD l HKD l MOP l SGD
l CHF l HNL l MXN l SVC
l CLP l IDR l NGN l THB
l CNY l INR l NOK l USD
l COP l ITL l NTD l ZAR
l CZK

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 30
 User Role Values
For API functions that take user role as a request parameter or return the
information in a response, here is a list of valid values:
l SERVICEPROVIDERACCOUNTREP
l SERVICEPROVIDERADMIN
l SERVICEPROVIDERCSRUSER
l SERVICEPROVIDERDATAHELPDESK
l SERVICEPROVIDERDEVICESORDERS
l SERVICEPROVIDERFINANCE
l SERVICEPROVIDERFINANCEAPPROVAL
l SERVICEPROVIDERFINANCEOPERATIONS
l SERVICEPROVIDERGLOBALADMIN
l SERVICEPROVIDERREADONLY
l SERVICEPROVIDERSERVICEADMIN
l SERVICEPROVIDERSUPPORTONLY
l SERVICEPROVIDERTECHSUPPORT
l SERVICEPROVIDERUSER
l SPSECURITYADMIN
l SPSECURITYADMINAPPROVER
l ACCOUNTADMIN
l ACCOUNTAPIONLY
l ACCOUNTDEMO
l ACCOUNTFINANCE
l ACCOUNTFINANCEAPPROVAL
l ACCOUNTFINANCEREADONLY
l ACCOUNTGLOBALADMIN
l ACCOUNTLBSUSER
l ACCOUNTORGADMIN
l ACCOUNTREADONLY
l ACCOUNTSECURITYADMIN
l ACCOUNTUSER
l TRIALUSER
l CUSTOMERADMIN
l CUSTOMERDEMO
l CUSTOMERREADONLY
l CUSTOMERSUPERVISOR
l CUSTOMERTERMINALEDIT
l CUSTOMERTRIALUSER
l CUSTOMERUSER

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 31
 Industry Vertical Values
For API functions that take vertical industry as a request parameter or
return the information in a response, here is a list of the valid values:
l ASSET_MANAGEMENT
l AVIATION
l CONNECTED_CAR
l CONSUMER_ELECTRONICS
l DIGITAL_SIGNAGE
l FLEET_MANAGEMENT
l INDUSTRIAL
l INSURANCE
l MEDICAL_DEVICES
l MOBILITY
l OIL_AND_GAS
l OTHER
l PAYMENT_SOLUTIONS
l RETAIL
l ROBOTICS
l SECURITY_AND_AUTOMATION
l SMART_BIKES
l SMART_METERS
l TELEMATICS

For information on the available industry verticals, see the Control Center
User Guide or the Knowledge Base (Reference > Admin > Account Wizard
Page 1 > Industry Vertical Descriptions).

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 32
 SMS Validity Period
The Send SMS function uses a tpvp request parameter for time-sensitive
messages. This value defines the length of time the message is available
before expiring. The SMSC will attempt to deliver the SMS message to the
mobile device within this validity period. If the message cannot be
delivered to the device by the end of this period (because the device is off
or out of coverage, for example), the message will be dropped.
For example, suppose you have an application that sends a Door
Lock/Unlock command to a vehicle via SMS. If the car is out of coverage
when the message is sent, you wouldn't necessarily want to deliver the
message hours later when the car is back in coverage. In this scenario, you
might choose to expire the message after a 5 minute validity period.
The tpvp parameter supports validity periods between 5 minutes and 63
weeks in length using the TP-VP relative format defined by the GSM 03.40
standards:

TPVP Value Validity Period Possible Validity Periods

0-143 (TP-VP + 1) x 5 minutes 5, 10, 15 minutes ... 11:55,

12:00 hours

144-167 (12 + (TP-VP - 143) / 2 ) 12:30, 13:00, ... 23:30, 24:00

hours hours

168-196 (TP-VP - 166) days 2, 3, 4, ... 30 days

197-255 (TP-VP - 192) weeks 5, 6, 7, ... 63 weeks

In the Door Lock/Unlock example, if you pass a value of 0 for tpvp, the
message would expire in 5 minutes: (0 + 1) x 5 = 5 minutes.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 33
 Try It Tool
From within the Knowledge Base, you can execute individual REST APIs
without writing any code.

Location: Help > Find everything you need in the Knowledge Base > APIs >
REST APIs > Devices > Search Devices

1. Scroll down to the bottom of any REST API reference page until you see
the Try It section. Click the function name to open the Try It tool.
2. Click the Try it out button to activate the parameter fields.
3. Enter the desired request parameter values. For functions that require a
date, copy and paste the sample date (which uses the correct date
format) and then edit the date to suit your use case.
4. Click Execute to send the request.

Control Center displays both the request code and the JSON response. You
can copy and paste the request code into a separate code file for future use.

No Partial Responses. Currently, you cannot request partial responses in

the Knowledge Base Try It tool.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 34
 Caution. The Try It tool acts on the environment you are currently logged
into — production or test (sandbox). Be aware that any PUT or POST calls
will update the current database. If you are interested in setting up a
sandbox environment, submit a project request in Cisco IoT Connect Portal.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 35
Accounts
Get Account Details
Description
Returns the account details for a given account. See the Response
Parameters section for a list of the specific account details returned.
You must have the ServiceProviderAdmin role to perform this function.

Resource URL
GET BaseURL/v{apiVersion}/accounts/{accountId}

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

accountId The ID of the account whose details you want to

retrieve.

Response Parameters

Return Value Description

accountName The account name appears throughout Control Center

as an identifier for the account.

accountId A Control Center-generated identifier for the account.

defaultSIMState This field defines the default SIM state that devices
receive when the operator transfers them from the
inventory account into the enterprise account. For
valid values, see SIM Status Values on page 29.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 36
 Return Value Description

type The type of account. Here are some values you may
see:
l STANDARD. For enterprise accounts.
l OPERATOR. For operator accounts. Each operator
has only one of these accounts. This account should
contain all service provider users, but no devices.
l MASTER. For operator inventory accounts. Every
operator has a least one inventory account. An
inventory account contains devices that have not
been assigned to an enterprise account. The devices
in this account have a special status called Start. In
the web interface, this account type is called
Inventory.

currency The currency value is the unit of measure used for the
rate plan and billing information.

language The default account language. The preference of the

logged in user will always take precedence over the
account language.

operatorAccountId The account ID used by the operator's internal IT

systems. Control Center uses this ID in the invoice
report feed that you receive for IT integration.

status Indicates whether the account is active or inactive.

When an account is inactive, account users cannot log
into Control Center through the web interface or the
APIs. However, account devices remain active in
Control Center and on the network. Automation rules
for the account also remain active and may trigger
based on the defined conditions. Typically, operators
use this flag as a way to "delete" an account.
Valid values are Active and Inactive.

taxId The tax or VAT ID is an account identifier that may be

used for tax purposes.

industryVertical This flag indicates the industry vertical for the

account. For valid values, see Industry Vertical Values
on page 32.

commPlanDetails See the Communication Plan Parameters table below.

defaultRatePlan See the Rate Plan Parameters table below.

billingAddr See the Address Parameters table below.

shippingAddr See the Address Parameters table below.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 37
 Return Value Description

ppuAddress See the Address Parameters table below.

primaryContact See the Contact Parameters table below.

billingContact See the Contact Parameters table below.

accountSegment Account segments are operator-created categories

that reflect the operator’s business requirements.

applicationSettings The application settings are grouped in categories that

mirror the organization of the Account Details >
Application Settings subtab in the web interface. See
the tables below.

applicationFeature See the Application Settings > Application Feature

Parameters table below.

simFeature See the Application Settings > SIM Feature Parameters

table below.

billingSettings The GET function currently returns only the general

billing settings. In the web interface, this information
appears on the Account Details page in the Billing
Settings > General subtab.

general See the Billing Settings > General Parameters table

below.

security All the security settings appear in this section. See the
Security Parameters table below.

Communication Plan Parameters

Control Center uses the default communication plan for any account device
that does not have a communication plan assigned to it.

Parameter Description

defaultCommPlan The name of the default communication plan.

defaultOnCommProfile The name of the communication profile devices

in the ON state will use.

defaultOffCommProfile The name of the communication profile devices

in the OFF state will use.

onCommProfileHlrTemplateId A unique identifier for the HLR template

containing the ON communication profile
information.

offCommProfileHlrTemplateId A unique identifier for the HLR template

containing the OFF communication profile
information.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 38
 Rate Plan Parameters

Control Center applies the default rate plan to any SIMs you transfer into
the account unless you specify a different rate plan.

Parameter Description

defaultRatePlanId The Plan ID for the default rate plan.

defaultRatePlanName The Plan Name for the default rate plan.

Address Parameters
These parameters are the same for all three types of addresses: billing,
shipping, and primary place of use.

Parameter Description

addr1 Street address, line 1. String, 1-100 characters

addr2 (Optional) Street address, line 2. String, 1-100

characters

city The city name. String, 1-100 characters

region The region name — a state or province, for example.

String, 1-100 characters

countryCode A two character country code. See ISO 3166 for two-
letter codes (alpha-2).

postalCode A postal code. String, 1-50 characters

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 39
 Contact Parameters
These parameters are the same for both the primary contact and the billing
contact, with one exception. The primary contact can have a job title, but
the billing contact does not.

Parameter Description

firstName A first name for the contact person. String, 1-49

characters

lastName A last name for the contact person. String, 1-49

characters

email An email for the contact person. This string must

conform to standard email format. No more than 320
characters.

phone A phone number for the contact person. String, 1-25

characters

fax A fax number for the contact person. String, 1-25

characters

name This string is the combination of the first and last name
values. Control Center uses the string for the Primary
Contact field on the Accounts list and the Account Details
pages. String, up to 100 characters.

jobTitle The primary contact can have a job title, but the billing
contact does not. String, up to 100 characters.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 40
 Application Settings > Application Feature Parameters

Parameter Description

accessCommPlan All account users can see the communication plan

name in the device Edit form. This toggle determines
whether the field is editable.
If this toggle is set to true, then account users have
the ability to change a device's communication plan.
In addition, Control Center displays the
communication plan name in the Device List and on
the device Details page.
If the toggle is set to false, account users cannot
change a device's communication plan and will not
see the communication plan name in the Device List
and on the device Details page.

businessRulesEnabled If this toggle is set to true, then the rules feature is

enabled for this account. The rules functionality is
visible in the Automation category to users
associated with this account.
If this toggle is set to false, then rules are disabled,
and the rules functionality is not visible to users
associated with this account.

simOrderingEnabled If this toggle is set to true, then the SIM ordering

feature is enabled for this account. This feature
allows account users to place an order as soon as the
need arises, and to assign a default rate plan and
communication plan for the new SIMs at the time of
the order.
If this toggle is set to false, SIM ordering is disabled
for this account.

smsAccess If this toggle is set to true, then the SMS fields in the
user interface are visible to account users. If this
toggle is set to false, then the SMS fields are not
visible.

voiceAccess If this toggle is set to true, then the voice fields in the
user interface are visible to account users. If this
toggle is set to false, then the voice fields are not
visible.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 41
 Application Settings > SIM Feature Parameters

Parameter Description

blockBackwardSimState If this toggle is set to true, users cannot change a

device status from Activated to the pre-activated
status (Activation Ready, Test Ready, or Inventory). If
the toggle is set to false, there are no restrictions on
changing a device status to Activation Ready, Test
Ready, or Inventory. This setting prevents an account
from moving under-used devices to Activation Ready
where they can avoid being charged a subscription
fee until they attempt to make a connection.

displayDiagnosticWizard The Diagnostics Wizard provides a very simple

interface that users with little wireless knowledge
can use to quickly see what is happening with a
device on the network.
If this toggle is set to true, then Control Center
displays the Diagnostics Wizard to account users.
If this toggle is set to false, then Control Center
hides the Diagnostics Wizard from account users.

displaySpotlight Spotlight is a troubleshooting tool that provides a

detailed snapshot of device connectivity history over
the past 30 days so you can observe long-term
trends. This tool is designed for advanced support
representatives, who have technical expertise in
wireless connectivity.
If this toggle is set to true, then Control Center
displays Spotlight to account users.
If this toggle is set to false, then Control Center
hides Spotlight from account users.

fixedIpEnabled If this toggle is set to true, Control Center displays

the fixed IP address (if any) for devices in the
Device List page.
If this toggle is set to false, Control Center does not
display the fixed IP addresses.

testReadyDataLimit This field specifies the amount of data (in bytes) a

device in the Test Ready state will receive free of
charge. Once the configured limit is reached for any
service (voice, SMS, data, or other), the device will
transition to the target state, and no more free test
traffic will be available for any service.
A blank value indicates there is no limit. For a zero
value, the device will reach the limit the first time it
initiates traffic.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 42
 Parameter Description

testReadySmsLimit This field specifies the number of messages a device

in the Test Ready state will receive free of charge.
Once the configured limit is reached for any service
(voice, SMS, data, or other), the device will
transition to the target state, and no more free test
traffic will be available for any service.
A blank value indicates there is no limit. For a zero
value, the device will reach the limit the first time it
sends or receives a message.

testReadyVoiceLimit This field specifies the number of voice minutes a

device in the Test Ready state will receive free of
charge. Once the configured limit is reached for any
service (voice, SMS, data, or other), the device will
transition to the target state, and no more free test
traffic will be available for any service.
A blank value indicates there is no limit. For a zero
value, the device will reach the limit the first time it
places or receives a phone call.

testReadyDataState Once the device reaches the configured limit in the

Test Ready state, Control Center automatically
moves the device to another SIM state. This field
specifies the next SIM state. Most operators use
either Activation Ready or Inventory. For valid
values, see SIM Status Values on page 29.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 43
 Billing Settings > General Parameters

Parameter Description

billable This toggle indicates whether the account is

billable. Valid values are Yes and No.

prorationRule Indicates whether or not the billing engine

will prorate subscription fees and included
usage in the first billing cycle for devices
using monthly rate plans.
l None. The billing engine charges for the
full month regardless of when the device
was first activated. The device receives
all the included usage.
l Daily. The billing engine charges the
account based on the number of days
since the device was activated for the
first time. The device receives a portion
of the included usage, based on the
number of days since the first activation.
l Semi-Monthly. The billing engine charges
for either a full or half month depending
on whether the device was activated for
the first time in the first half or second
half of the month. The device receives all
or half of the included usage, based on the
first activation date.
l Unknown. You may also see this value.

renewalProrationRule Similar to prorationRule, this parameter

covers the special case where a device ends
a prepaid rate plan and moves onto a
monthly plan. Depending on the value of
prorationRule, Control Center will prorate
the new subscription fee on a semi-monthly
or daily basis – or not at all. Valid values
include: None, Semi-Monthly, Daily, Unknown.

simFee This fee indicates how much the account is

charged for any SIMs they purchase from
you.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 44
 Parameter Description

activationPlan The default activation plan defines how

Control Center will apply the activation fee
to each device owned by the account.
l First Time Only. The account pays the
activation fee when the device is
activated for the first time (typical).
l Each Time. The account pays every time
the device SIM status changes to
Activated.
l Not First Time. The account does not pay
for the first device activation, but it does
pay for every subsequent activation.
l None. No charge.

You can override the default activation fee

and plan settings by defining this
information at the rate plan level. In that
case Control Center will charge an activation
fee based on the settings associated with the
current device rate plan.

activationFee Control Center charges this fee based the

activationPlan setting. You can override the
default activation fee and plan settings by
defining this information at the rate plan
level. In that case Control Center charges an
activation fee based on the settings
associated with the current device rate plan.

vpnPlan Control Center supports two types of VPN:

GPRS and SMPP. The account can choose to
purchase one, both, or neither. You must
select one of these options before you can
define a setup fee or monthly fees for the
VPN. Valid values include: GPRS Only, SMPP
Only, GPRS + SMPP, and None.

retailBilling The retail billing feature is enabled if the

value is Retail Customer.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 45
 Parameter Description

immediateRatePlanChange If this toggle is on, you can change the rate

plan for a device mid-cycle (as long as the
device has an Activated SIM state) and
Control Center will bill for the device as if it
had been on the new rate plan during the
entire billing cycle. This behavior only
applies to monthly rate plans. You cannot
change the rate plan for a device on a
prepaid rate plan until the plan expires.

defaultTimeZone The default time zone for the account.

Unless otherwise specified, Control Center
uses the time zone associated with the
logged in user to display all dates. The
information is stored as text. Sample values
include: UTC, Pacific/Midway, America/Costa_
Rica, America/Nome, Pacific/Marquesas,
America/Anchorage.

eventPlanEnabled If this toggle is set to true, then event plans

are enabled for this account. An event plan
is a prepaid rate plan that’s designed for
special circumstances or "events" that occur
outside of a normal rate plan.
If this toggle is set to false, then this account
cannot use event plans.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 46
 Parameter Description

prepaidRenewalPolicy When a prepaid rate plan expires, Control

Center either deactivates the device or
gives it a different rate plan. You can specify
the default renewal behavior for all the
account’s prepaid rate plans. Valid options
are:
l Deactivate. Deactivate the device.
l AutoRenew. Renew the current prepaid
rate plan.
l NamedPlan. Use the first rate plan in the
device queue. If there is no device queue,
Control Center uses the named rate plan
(prepaidRenewalRatePlanId).
l None.
l Unknown.

prepaidRenewalRatePlanId If prepaidRenewalPolicy is NamedPlan, then

Control Center requires a rate plan. When a
prepaid device rate plan expires, Control
Center attaches the named rate plan to the
device. If the device has a queue, Control
Center uses the rate plan at the top of the
queue instead of the plan named here.

Security Parameters

Parameter Description

ipLoginRestrictionEnabled Indicates whether the account can use IP address

restrictions .

secureSimEnabled Indicates whether the account can use the Secure

SIM feature .

twoStepVerification Indicates whether the account can use the 2-Step

Verification feature.

passwordPolicySettings See Password Parameters table below.

ui These parameters define password policies for

users who access the product through the web
interface.

soap These parameters define password policies for

users who access the product through the SOAP
API.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 47
 Password Parameters

Parameter Description

passwordExpirationInDays The number of days before the user’s password

expires automatically. If the user does not reset
their password before the current password
expires, the user must ask an administrator for
assistance. This parameter applies to all new
users. For existing users, this parameter applies
only if an administrator forces the user to
change their password, or if the user initiates
the password reset.
If passwords do not expire, this field contains
the string "Passwords do not expire." This
policy is useful for SOAP API users who do not
typically change passwords.

numAttemptsBefore The number of times a user can attempt to

TempLockout properly input the correct password before
Control Center locks them out of the system.
If Control Center never locks users out of the
system, this field contains the string "User
accounts never lock out."

tempLockoutPeriodInMinutes If the numAttemptsBeforeTempLockout

parameter is used, then the operator can
enforce a specified time (in minutes) for the
lockout period.

numHistoryChecks Control Center examines previous passwords

assigned to a user ID and ensures that the
newly created password is not identical to the
specified past number of versions.

content A group of fields that specify rules for the

password string.

minLength The minimum number of characters that a

password must contain.

maxLength The maximum number of characters a password

can contain.

minUppercaseChars The minimum number of uppercase characters

that a password must contain.

minNumerics The minimum number of numeric characters

that a password must contain.

minSpecialChars The minimum number of special characters that

a password must contain.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 48
 Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic
RW5nbGlzaFNQQWRtaW5RQTozOGFkNDI0Zi0yMjEzLTQ3ZDAtYjlmNS05OWEzZDdmNzEwNjg="
"https://restapi1.jasper.com/rws/api/v1/accounts/100020704"

Response Example

{
"accountName": "Widgets Inc.",
"accountId": "100020704",
"defaultSIMState": "TEST_READY",
"type": "STANDARD",
"currency": "USD",
"language": "English",
"operatorAccountId":"123",
"status": "Active",
"taxId": "123",
"industryVertical": "AVIATION",
"commPlanDetails": {
"defaultCommPlan": "QACP4",
"defaultOnCommProfile": "QACPR3",
"defaultOffCommProfile": "QACPR4",
"onCommProfileHlrTemplateId": "999999102236001",
"offCommProfileHlrTemplateId": "999999101669802"
},
"defaultRatePlan": {
"defaultRatePlanId": 78138,
"defaultRatePlanName": "29658_RPID_MonInd"
},
"billingAddr": {
"addr1": "123 Main St",
"addr2": null,
"city": "Danville",
"region": "CA",
"countryCode": "US",
"postalCode": "94526"
},
"shippingAddr": {
"addr1": "123 Main St",
"addr2": null,
"city": "Danville",
"region": "CA",
"countryCode": "US",
"postalCode": "94526"
},
"ppuAddress": {
"addr1": "123 Main St",
"addr2": null,
"city": "Danville",
"region": "CA",
"countryCode": "US",
"postalCode": "94526"
},
"primaryContact": {
"firstName": "Katie",

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 49
 "lastName": "Duncan",
"email": "katiedu@widgets.com",
"phone": "123-345-2345",
"fax": null,
"name": null,
"jobTitle": null
},
"billingContact": {
"firstName": "Katie",
"lastName": "Duncan",
"email": "katiedu@widgets.com",
"phone": "123-345-2345",
"fax": null,
"name": null,
"jobTitle": null
},
"acctSegment": null,
"applicationSettings": {
"applicationFeature": {
"accessCommPlan": true,
"businessRulesEnabled": true,
"simOrderingEnabled": true,
"smsAccess": true,
"voiceAccess": true
},
"simFeature": {
"blockBackwardSimState": true,
"displayDiagnosticWizard": true,
"displaySpotlight": true,
"fixedIpEnabled": true,
"testReadyDataLimit": 20480,
"testReadySmsLimit": 2,
"testReadyVoiceLimit": 120,
"testReadyDataState": "ACTIVATION_READY"
}
},
"billingSettings": {
"general": {
"billable": "No",
"prorationRule": "None",
"renewalProrationRule": "None",
"simFee": null,
"activationPlan": "First Time Only",
"activationFee": null,
"vpnPlan": "None",
"retailBilling": "None",
"immediateRatePlanChange": true,
"defaultTimeZone": null,
"eventPlanEnabled": false,
"prepaidRenewalPolicy": "Deactivate",
"prepaidRenewalRatePlanId": null
}
},
"security": {
"ipLoginRestrictionEnabled": true,
"secureSimEnabled": false,
"twoStepVerification": true,
"passwordPolicySettings": {
"ui": {

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 50
 "passwordExpirationInDays": "Passwords do not expire.",
"numAttemptsBeforeTempLockout": "User accounts never lock out.",
"tempLockoutPeriodInMinutes": null,
"numHistoryChecks": null,
"content": {
"minLength": "6",
"maxLength": "25",
"minUppercaseChars": null,
"minNumerics": null,
"minSpecialChars": null
}
},
"soap": {
"passwordExpirationInDays": "Passwords do not expire.",
"numAttemptsBeforeTempLockout": "User accounts never lock out.",
"tempLockoutPeriodInMinutes": null,
"numHistoryChecks": null,
"content": {
"minLength": "6",
"maxLength": "25",
"minUppercaseChars": null,
"minNumerics": null,
"minSpecialChars": null
}
}
}
}
}

Code Samples
Make sure to use your own URL and user credentials.
Python

import requests
import json
import base64
import pprint

cobrandURL=input("Cobrand URL: ")

url = 'https://'+cobrandURL+'/rws/api/v1/accounts/'+input("Account ID: ")
myResponse = requests.get(url,auth=(input("username: "),input("api_key: ")))
# For successful API call, response code will be 200 (OK)
if(myResponse.ok):
# Loading the response data into a dict variable
# json.loads takes in only binary or string variables so using content
to fetch binary content
# Loads (Load String) takes a Json file and converts into python data
structure (dict or list, depending on JSON)
jData = json.loads(myResponse.content)
pp=pprint.PrettyPrinter(indent=4)
pp.pprint(jData)
else:
# If response code is not ok (200), print the resulting http error
code with description
print("Failure")
myResponse.raise_for_status()

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 51
 Node.js

var request = require('request');

var body = [];
request.get('https://restapi1.jasper.com/rws/api/v1/accounts/147060908').auth
('username', 'password', false)
.on('error', function(error){
console.log('Error:', error);
})
.on('response', function(response) {
console.log(response.statusCode); // return statusCode
console.log(response.headers['content-type']); // return contentType
})
.on('data',function(chunk){
body.push(chunk);
})
.on('end',function(){
body = Buffer.concat(body).toString();
console.log(body);
});

Ruby

#!/usr/bin/ruby -w
require 'rest-client'
require 'json'

url = 'https://restapi1.jasper.com/rws/api/v1/accounts/147060908'
response = RestClient::Request.execute(
method: :get,
url: url,
user: 'username',
password: 'password',
:headers => {:accept => :json}
)
puts JSON.pretty_generate(JSON.parse(response))

Errors

HTTP
Error Code Description
Code

10000024 400 Invalid apiVersion.

10000030 400 Your role does not have access to this API function.

20000003 404 Resource not found - Invalid accountId.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 52
 Get All Accounts
Description
Returns all accounts associated with the operator. The response body
contains a subset of the details for each account. Use the Get Accounts
Details API to get additional information for a particular account.
You must have the ServiceProviderAdmin role to perform this function.

Resource URL
GET BaseURL/v{apiVersion}/accounts

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

pageSize (Optional) Specifies the number of records returned in

each response page. The maximum value is 50. The
value defaults to 50. See Pagination on page 27.

pageNumber (Optional) Specifies the number of response pages to

return. This value defaults to 1. See Pagination on
page 27.

Response Parameters

Return Value Description

pageNumber An integer specifying the number of the current

response page.
See Pagination on page 27.

accounts An array of accounts associated with the operator.

accountName The account name appears throughout Control Center

as an identifier for the account.

accountId A Control Center-generated identifier for the account.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 53
 Return Value Description

type The type of account. Here are some values you may
see:
l STANDARD. For enterprise accounts.
l OPERATOR. For operator accounts. Each operator
has only one of these accounts. This account should
contain all service provider users, but no devices.
l MASTER. For operator inventory accounts. Every
operator has a least one inventory account. An
inventory account contains devices that have not
been assigned to an enterprise account. The devices
in this account have a special status called Start. In
the web interface, this account type is called
Inventory.

status Indicates whether the account is active or inactive.

When an account is inactive, account users cannot log
into Control Center through the web interface or the
APIs. However, account devices remain active in
Control Center and on the network. Automation rules
for the account also remain active and may trigger
based on the defined conditions. Typically, operators
use this flag as a way to "delete" an account.
Valid values are Active and Inactive.

currency The currency value is the unit of measure used for the
rate plan and billing information.

operatorAccountId The account ID used by the operator's internal IT

systems. Control Center uses this ID in the invoice
report feed that you receive for IT integration.

taxId The tax or VAT ID is an account identifier that may be

used for tax purposes.

industryVertical This flag indicates the industry vertical for the

account. For valid values, see Industry Vertical Values
on page 32.

commPlanDetails See the Communication Plan Parameters table below.

defaultRatePlan See the Rate Plan Parameters table below.

lastPage A true or false value indicating whether the current

response page is the last in the series. See Pagination
on page 27.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 54
 Communication Plan Parameters
Control Center uses the default communication plan for any account device
that does not have a communication plan assigned to it.

Parameter Description

defaultCommPlan The name of the default communication plan.

defaultOnCommProfile The name of the communication profile devices

in the ON state will use.

defaultOffCommProfile The name of the communication profile devices

in the OFF state will use.

onCommProfileHlrTemplateId A unique identifier for the HLR template

containing the ON communication profile
information.

offCommProfileHlrTemplateId A unique identifier for the HLR template

containing the OFF communication profile
information.

Rate Plan Parameters

Control Center applies the default rate plan to any SIMs you transfer into
the account unless you specify a different rate plan.

Parameter Description

defaultRatePlanId The Plan ID for the default rate plan.

defaultRatePlanName The Plan Name for the default rate plan.

Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic
RW5nbGlzaFNQQWRtaW5RQTozOGFkNDI0Zi0yMjEzLTQ3ZDAtYjlmNS05OWEzZDdmNzEwNjg="
"https://restapi1.jasper.com/rws/api/v1/accounts"

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 55
 Response Example

{
"pageNumber": 1,
"accounts": [{
"accountName": "Acme Corp",
"accountId": "100595340",
"type": "STANDARD",
"status": "Active",
"currency": "USD",
"operatorAccountId": null,
"taxId": "78593",
"industryVertical": "AVIATION",
"commPlanDetails": {
"defaultCommPlan": "Acme Default",
"defaultOnCommProfile": "Acme ON",
"defaultOffCommProfile": "Acme OFF"
"onCommProfileHlrTemplateId": "999999108256301",
"offCommProfileHlrTemplateId": "999999109629702"
},
"defaultRatePlan": {
"defaultRatePlanId": 1126395,
"defaultRatePlanName": "Acme Flex Pool"
}
}, {
"accountName": "Widgets Inc",
"accountId": "100613714",
"type": "STANDARD",
"status": "Active",
"currency": "USD",
"operatorAccountId": "39599",
"taxId": "23090",
"industryVertical": "SMART_METERS",
"commPlanDetails": {
"defaultCommPlan": "Widgets Default",
"defaultOnCommProfile": "Widgets ON",
"defaultOffCommProfile": "Widgets OFF"
"onCommProfileHlrTemplateId": "999999105236806",
"offCommProfileHlrTemplateId": "999999129729305"
},
"defaultRatePlan": {
"defaultRatePlanId": 1993832,
"defaultRatePlanName": "Widgets Fixed Pool"
}
}],
"lastPage": true
}

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 56
 Code Samples
Make sure to use your own URL and user credentials.
Python

import requests
import json
import base64
import pprint

cobrandURL=input("Cobrand URL: ")

url = 'https://'+cobrandURL+'/rws/api/v1/accounts'
myResponse = requests.get(url,auth=(input("username: "),input("api_key: ")))
# For successful API call, response code will be 200 (OK)
if(myResponse.ok):
# Loading the response data into a dict variable
# json.loads takes in only binary or string variables so using content
to fetch binary content
# Loads (Load String) takes a Json file and converts into python data
structure (dict or list, depending on JSON)
jData = json.loads(myResponse.content)
pp=pprint.PrettyPrinter(indent=4)
pp.pprint(jData)
else:
# If response code is not ok (200), print the resulting http error
code with description
print("Failure")
myResponse.raise_for_status()

Node.js

var request = require('request');

var body = [];
request.get('https://restapi1.jasper.com/rws/api/v1/accounts').auth
('username', 'password', false)
.on('error', function(error){
console.log('Error:', error);
})
.on('response', function(response) {
console.log(response.statusCode); // return statusCode
console.log(response.headers['content-type']); // return contentType
})
.on('data',function(chunk){
body.push(chunk);
})
.on('end',function(){
body = Buffer.concat(body).toString();
console.log(body);
});

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 57
 Ruby

#!/usr/bin/ruby -w
require 'rest-client'
require 'json'

url = 'https://restapi1.jasper.com/rws/api/v1/accounts'
response = RestClient::Request.execute(
method: :get,
url: url,
user: 'username',
password: 'password',
:headers => {:accept => :json}
)
puts JSON.pretty_generate(JSON.parse(response))

Errors

HTTP
Error Code Description
Code

10000006 400 Invalid pageSize.

10000007 400 Invalid pageNumber.

10000024 400 Invalid apiVersion.

10000030 400 Your role does not have access to this API function.

10000062 400 Access Denied.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 58
 Create Account
Description
Creates a standard enterprise account with the minimum information
required for a new account. Using this REST API is equivalent to creating an
account in the web interface with just the information on the first page of
the account creation form.
You must have the ServiceProviderAdmin role to use this function.

Resource URL
POST BaseURL/v{apiVersion}/accounts

Request Parameters
All parameters are required unless the description says otherwise.

Parameter Description

apiVersion The version number for this API. The current

version for all functions is 1.

accountName The account name appears throughout Control

Center as an identifier for the account. We
recommend using the company name. This
name must be unique.

type All enterprise accounts use the following type:

STANDARD.

operator (Optional) The name of the service provider.

This field is optional for operator users.

currency The currency value is the unit of measure used

for the rate plan and billing information. Note
that you can use only one currency type to bill
an account. For valid values, see Currency
Values on page 30.

language The default account language. The preference

of the logged in user will always take
precedence over the account language. For
valid values, see Language Values on page 30.

taxId The tax or VAT ID for the account appears in

the invoice report feeds that Control Center
sends to the operator. You can use this account
identifier for tax purposes.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 59
 Parameter Description

industryVertical (Optional) This flag indicates the industry

vertical for the account. If the value is left
blank, the system defaults to OTHER. For valid
values, see Industry Vertical Values on page 32.

defaultSIMState This field defines the default SIM state that

devices receive when the operator transfers
them from the inventory account into the
enterprise account. For valid values, see SIM
Status Values on page 29.

defaultCommPlanName Control Center uses the default communication

plan for any account device that does not have
a communication plan assigned to it. You must
supply the name of an existing shared
communication plan.

defaultRatePlanName Control Center applies the default rate plan to

any devices you transfer into the account. You
must supply the name of an existing shared
base rate plan. Control Center automatically
assigns that rate plan to the account.

primaryContact Every account must have a primary contact

with detailed information. See Contact
Parameters table below for details.

billingContactSameAsPrimary This flag indicates whether the billing contact

is the same as the primary contact. If you
choose true, you can omit the billing contact
information. If you choose false, the billing
contact fields are required.

billingContact (Optional) Every account must have a billing

contact. If the billingContactSameAsPrimary
flag is true, you can omit the fields. Otherwise,
you must provide values for these fields (see
Contact Parameters table below).

billingAddr The billing address is required. See the Address

Parameters table below for details.

shippingAddrSameAs This flag indicates whether the shipping

Billing address is the same as the billing address. If
you choose true, you can omit the shipping
address information. If you choose false, the
shipping address fields are required.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 60
 Parameter Description

shippingAddr (Optional) Every account must have a shipping

address. If the shippingAddrSameAsBilling flag
is true, you can omit the fields. Otherwise, you
must provide values for this list of fields (see
Address Parameters table below).

ppuaddrSameAs This flag indicates whether the Primary Place

Shipping of Use (PPU) address is the same as the
shipping address. If you choose true, you can
omit the PPU address information. If you
choose false, the PPU address fields are
required.

ppuAddr (Optional) Every account must have a Primary

Place of Use (PPU) address. If the
ppuaddrSameAsShippingflag is true, you can
omit the fields. Otherwise, you must provide
values for this list of fields (see Address
Parameters table below).

accountSegment (Optional) Account segments are operator-

created categories that reflect the operator’s
business requirements.

notes (Optional) Provides additional information

about the account. Maximum length is 2000
characters.

operatorAccountId (Optional) The account ID used by the

operator's internal IT systems. Control Center
uses this ID in the invoice report feed that you
receive for IT integration.

customFields (Optional) If you have already created custom

account fields to record business-specific
information, you can supply values for these
fields when you create a new account. To view,
edit, or create custom account fields and their
values, go to Admin > Service Provider Profile
> Account Custom Fields. See fieldValue1...10.

fieldValue1...10 (Optional) You can provide account-specific

values for existing custom account fields. You
must use the parameter names "fieldValue1",
"fieldValue2", and so on, regardless of the field
names that appear in the web interface.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 61
 Contact Parameters
These parameters are the same for both the primary contact and the billing
contact, with one exception. The primary contact can have a job title, but
the billing contact does not.

Parameter Description

firstName A first name for the contact person. String, 1-49

characters

lastName A last name for the contact person. String, 1-49

characters

email An email for the contact person. This string must

conform to standard email format. No more than 320
characters.

phone A phone number for the contact person. String, 1-25

characters

fax A fax number for the contact person. String, 1-25

characters

name This string is the combination of the first and last name
values. Control Center uses the string for the Primary
Contact field on the Accounts list and the Account Details
pages. String, up to 100 characters.

jobTitle The primary contact can have a job title, but the billing
contact does not. String, up to 100 characters.

Address Parameters
These parameters are the same for all three types of addresses: billing,
shipping, and primary place of use.

Parameter Description

addr1 Street address, line 1. String, 1-100 characters

addr2 (Optional) Street address, line 2. String, 1-100

characters

city The city name. String, 1-100 characters

region The region name — a state or province, for example.

String, 1-100 characters

countryCode A two character country code. See ISO 3166 for two-
letter codes (alpha-2).

postalCode A postal code. String, 1-50 characters

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 62
 Response Parameters
Control Center returns the account ID for the new account.

Return Value Description

accountId An unique identifier for the new account.

timestamp The date and time when the account was created. The
timestamp displays in UNIX Epoch clock format. See
Date/Time Formats on page 28 for more information.

Request Example
Make sure to use your own URL and user credentials.

{ curl -X POST --header "Content-Type: application/json" --header "Accept:

application/json" --header "Authorization: Basic
RW5nbGlzaFNQQWRtaW5RQTozOGFkNDI0Zi0yMjEzLTQ3ZDAtYjlmNS05OWEzZDdmNzEwNjg=" -d
"{
\"accountName\": \"ProDevice Inc.\",
\"type\": \"STANDARD\",
\"currency\": \"USD\",
\"language\": \"English\",
\"taxId\": \"34006\",
\"industryVertical": \"AVIATION\",
\"defaultSIMState\": \"TEST_READY\",
\"defaultCommPlanName\": \"QACP4\",
\"defaultRatePlanName\": \"29658_RPID_MonInd\",
\"primaryContact\": {
\"name\": \"John Doe\",
\"firstName\": \"John\",
\"lastName\": \"Doe\",
\"email\": \"john@prodevice.com\",
\"phone\": \"432-556-4545\" },
\"billingContactSameAsPrimary\": true,
\"billingAddr\": {
\"addr1\": \"335 Elm St\",
\"city\": \"Sacramento\",
\"region\": \"CA\",
\"countryCode\": \"US\",
\"postalCode\": \"94632\" },
\"shippingAddrSameAsBilling\": true,
\"ppuaddrSameAsShipping\": true
}" "https://restapi1.jasper.com/rws/api/v1/accounts"

Response Example

{
"accountId": 105520704,
"timestamp": 1527590173
}

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 63
 Errors

Error HTTP
Description
Code Code

1000621 400 Invalid Industry Vertical.

10000013 404 Invalid ratePlan.

10000014 400 Invalid communicationPlan.

10000023 400 The JSON in the request is not well formed. Please
ensure that commas, colons, braces etc. are formatted
properly.

10000024 400 Invalid apiVersion.

10000062 400 Access Denied.

10000500 400 Service provider not found.

10000501 400 Could not create account.

10000504 400 Account already exists.

10000505 400 Invalid region Id.

10000515 400 Invalid BillingCycleStart.

10000516 400 Not allow to set BillingCycleStart.

10000521 400 Invalid Country Code.

10000528 400 Partner Account creation not allowed.

10000548 400 Primary contact firstName and lastName are

required.

30000001 500 Unknown server error.

50001225 400 Shipping Address cannot be null as it is not same as

the billing address.

50001226 400 PPU Address cannot be null is it as not same as the

shipping address.

50001224 400 Billing Contact cannot be null is it is not same as

primary contact.

50001227 400 Operator name is invalid.

50001228 400 Account type is invalid.

50001229 400 Currency code is invalid.

50001230 400 Language is invalid.

50001231 400 Sim state name is invalid.

50001233 400 JSON validation error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 64
 Edit Account Details
Description
Changes one or more account settings for a single active account. You
cannot make changes to an inactive account.
You must have the ServiceProviderAdmin role to perform this function.

Resource URL
PUT BaseURL/v{apiVersion}/accounts/{accountId}

Request Parameters
The following tables list all the parameters you can update using this
API function. Typically, users will update one or two parameters at a time.

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

accountId The ID of the account you want to change. You cannot

change this value.

accountName The account name appears throughout Control Center

as an identifier for the account. We recommend using
the company name. This name must be unique.

status Indicates whether the account is active (A) or inactive

(I).

currency The currency value is the unit of measure used for the
rate plan and billing information. Note that you can
use only one currency type to bill an account. For valid
values, see Currency Values on page 30.

language The default account language. The preference of the

logged in user will always take precedence over the
account language. For valid values, see Language
Values on page 30.

taxId The tax or VAT ID for the account appears in the

invoice report feeds that Control Center sends to the
operator. You can use this account identifier for tax
purposes.

industryVertical (Optional) This flag indicates the industry vertical for

the account. If the value is left blank, the system
defaults to OTHER. For valid values, see Industry
Vertical Values on page 32.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 65
 Parameter Description

primaryContact Every account must have a primary contact with

detailed information. See Contact Parameters table
below for details.

billingContact Every account must have a billing contact with

detailed information. See Contact Parameters table
below for details.

billingAddr A billing address. See the Address Parameters table

below for details.

shippingAddr A shipping address. See the Address Parameters table

below for details.

ppuAddr A primary place of use (PPU) address. See the Address

Parameters table below for details.

accountSegment Account segments are operator-created categories

that reflect the operator’s business requirements. You
can view, add, edit, or delete these values in the web
interface: Admin > Service Provider Profile > Account
Segments subtab.

notes Provides additional information about the account.

Maximum length is 2000 characters.

operatorAccountId The account ID used by the operator's internal IT

systems. Control Center uses this ID in the invoice
report feed that you receive for IT integration.

customFields If you have already created custom account fields to

record business-specific information, you can specify
values for these fields. To view, edit, or create custom
account fields and their values, go to Admin >
Service Provider Profile > Account Custom Fields.

fieldValue1-10 You can provide account-specific values for existing

custom account fields. You must use the parameter
names "fieldValue1", "fieldValue2", and so on,
regardless of the field names that appear in the web
interface.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 66
 Contact Parameters
These parameters are the same for both the primary contact and the billing
contact, with one exception. The primary contact can have a job title, but
the billing contact does not.

Parameter Description

firstName A first name for the contact person. String, 1-49

characters

lastName A last name for the contact person. String, 1-49

characters

email An email for the contact person. This string must

conform to standard email format. No more than 320
characters.

phone A phone number for the contact person. String, 1-25

characters

fax A fax number for the contact person. String, 1-25

characters

name This string is the combination of the first and last name
values. Control Center uses the string for the Primary
Contact field on the Accounts list and the Account Details
pages. String, up to 100 characters.

jobTitle The primary contact can have a job title, but the billing
contact does not. String, up to 100 characters.

Address Parameters
These parameters are the same for all three types of addresses: billing,
shipping, and primary place of use.

Parameter Description

addr1 Street address, line 1. String, 1-100 characters

addr2 (Optional) Street address, line 2. String, 1-100

characters

city The city name. String, 1-100 characters

region The region name — a state or province, for example.

String, 1-100 characters

countryCode A two character country code. See ISO 3166 for two-
letter codes (alpha-2).

postalCode A postal code. String, 1-50 characters

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 67
 Response Parameters
Control Center returns the account ID for the updated account.

Return Value Description

accountId An unique identifier for the updated account.

timestamp The date and time when the account was updated. The
timestamp displays in UNIX Epoch clock format. See
Date/Time Formats on page 28 for more information.

Request Example
Account updates are typically brief, targeting one or two parameters at a
time. Make sure to use your own URL and user credentials.

curl -X PUT --header "Content-Type: application/json" --header "Accept:

application/json" --header "Authorization: Basic
RW5nbGlzaFNQQWRtaW5RQTozOGFkNDI0Zi0yMjEzLTQ3ZDAtYjlmNS05OWEzZDdmNzEwNjg=" -d
"{
\"currency\": \"USD\" }
}" "https://restapi1.jasper.com/rws/api/v1/accounts/100020704"

Response Example

{
"accountId": 100020704,
"timestamp": 1527590173
}

Errors

HTTP
Error Code Description
Code

1000621 400 Invalid Industry Vertical.

1400109 404 User not found.

10000002 400 AccoundId is required.

10000004 400 Invalid accountId.

10000005 400 Invalid status.

10000013 404 Invalid ratePlan.

10000014 400 Invalid communicationPlan.

10000024 400 Invalid apiVersion.

10000033 400 Invalid contactName.

10000521 400 Invalid Country Code.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 68
 HTTP
Error Code Description
Code

20000003 404 Resource not found - Invalid accountId.

30000001 500 Unknown server error.

50001229 400 Currency code is invalid.

50001230 400 Language is invalid.

50001233 400 JSON validation error.

50001234 400 CommPlan not allowed for Partner Account.

50001235 400 Invalid AccountSegment.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 69
 Get Account Application Settings
Description
Returns account application settings for a specified account. See the
API/Role matrix in the Knowledge Base for a complete list of roles that can
use this API.

Resource URL
GET BaseURL/v{apiVersion}/accounts/{accountId}/applicationSettings

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

accountId The ID of the account whose application settings you

want to retrieve.

Response Parameters
This function returns data organized into four different groups
corresponding to the groups you'll see in the web interface (Admin >
Account Details > Application Settings):
l Application Feature
l SIM Feature
l Site Configuration
l Support

Return Value Description

applicationFeature See the Application Feature table below.

simFeature See the SIM Feature table below.

siteConfiguration See the Site Configuration table below.

support See the Support table below.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 70
 Application Feature

Return Value Description

accessCommPlan All account users can see the communication plan

name in the device Edit form. This toggle determines
whether the field is editable.
If this toggle is set to true, then account users have
the ability to change a device's communication plan.
In addition, Control Center displays the
communication plan name in the Device List and on
the device Details page.
If the toggle is set to false, account users cannot
change a device's communication plan and will not
see the communication plan name in the Device List
and on the device Details page.

csdAccess A true or false indicates whether or not the

application displays access to Circuit Switched Data
(CSD) fields in the user interface are visible to
account users.

businessRulesEnabled A true or false indicates whether or not business rules

are available for the account. The rules functionality
is visible in the Automation category to users
associated with the account. Be aware that any
existing business rules associated with the account
continue to function even it you disable rules for the
account.

globalAccountEnabled If set to true, the Global SIM feature is enabled for

this account. This feature enables operators to create
partnerships with other operators to serve
multinational enterprise customers.
Unlike a typical roaming agreement between
operators, a global alliance allows the roaming SIM
to actually swap credentials (IMSIs, ICCIDs, and
MSISDNs) from the original operator to the partner
operator using over-the-air (OTA) swap technology.
If set to false, the Global SIM feature is disabled for
this account.

policiesEnabled This legacy field is no longer used.

simOrderingEnabled A true or false indicates whether or not the SIM

ordering feature is enabled for the account. If set to
true, account users can place an order that includes
the default rate plan and communication plan for the
new SIMs.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 71
 Return Value Description

smsAccess If this toggle is set to true, then the SMS fields in the
user interface are visible to account users. If this
toggle is set to false, then the SMS fields are not
visible.

subscriptionChannel A true or false indicates whether or not the

application has enabled a subscription channel. This
capability allows a deactivated account to go to a
specific URL and reactivate itself.

voiceAccess If this toggle is set to true, then the voice fields in the
user interface are visible to account users. If this
toggle is set to false, then the voice fields are not
visible.

SIM Feature

Return Value Description

blockBackwardSimState If set to true, account users cannot change a device

status from Activated to the pre-activated status
(such as Activation Ready, Inventory, or Test Ready).
If set to false, there are no restrictions on changing
a device status to Activation Ready, Inventory, or Test
Ready. This setting prevents an account from moving
under-used devices to Activation Ready where they
can avoid being charged a subscription fee until they
attempt to make a connection.

defaultSimState This field defines the default SIM state that devices
receive when the operator transfers them from the
inventory account into the enterprise account. For a
list of valid values, see SIM Status Values on page 29.

displayDiagnosticWizard The Diagnostics tool provides a very simple

interface that users with little wireless knowledge
can use to quickly see what is happening with a
device on the network. If set to Yes, then Control
Center displays the Diagnostics tool to account
users. If set to No, then Control Center hides the
Diagnostics tool from account users.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 72
 Return Value Description

displaySpotlight Spotlight is a troubleshooting tool that provides a

detailed snapshot of device connectivity history over
the past 30 days so you can observe long-term
trends. This tool is designed for advanced support
representatives, who have technical expertise in
wireless connectivity. If set to Yes, then Control
Center displays Spotlight to account users. If set to
No, then Control Center hides Spotlight from account
users.

fixedIpEnabled If set to true, Control Center displays the fixed IP

address (if any) for devices in the Device List page.
If set to false, Control Center does not display the
fixed IP addresses.

testReadyDataLimit This field specifies the amount of data (in bytes) a

device in the Test Ready state receives free of
charge. Once the configured limit is reached for any
service (voice, SMS, data, or other), the device will
transition to the target state, and no more free test
traffic will be available for any service. A blank
value indicates there is no limit. For a zero value,
the device will reach the limit the first time it
initiates traffic. The upper values is 10.

testReadySmsLimit This field specifies the number of messages a device

in the Test Ready state will receive free of charge.
Once the configured limit is reached for any service
(voice, SMS, data, or other), the device will
transition to the target state, and no more free test
traffic will be available for any service. A blank
value indicates there is no limit. For a zero value,
the device will reach the limit the first time it sends
or receives a message. The upper values is 10.

testReadyVoiceLimit This field specifies the number of voice minutes a

device in the Test Ready state will receive free of
charge. Once the configured limit is reached for any
service (voice, SMS, data, or other), the device will
transition to the target state, and no more free test
traffic will be available for any service. A blank
value indicates there is no limit. For a zero value,
the device will reach the limit the first time it
places or receives a phone call. The upper values is
10.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 73
 Return Value Description

testReadyCsdLimit This field specifies the number of Circuit Switched

Data in seconds (CSD) a device in the Test Ready
state will receive free of charge. Once the
configured limit is reached for any service (voice,
SMS, data, or other), the device will transition to the
target state, and no more free test traffic will be
available for any service. A blank value indicates
there is no limit. For a zero value, the device will
reach the limit the first time it places or receives a
phone call. The upper values is 10.

testReadyDataState Once the device reaches the configured limit in the

Test Ready state, Control Center automatically
moves the device to another SIM state. This field
specifies the next SIM state. Most operators use
either Activation Ready or Inventory. For a list of
valid values, see SIM Status Values on page 29.

Site Configuration

Return Value Description

cobrandSite The URL for the branded instance of Control Center

that account users will use to launch Control Center.

fileExportMethod This field determines the format of an export files the

user creates. The options are EXCEL and CSV.

eulaEnabled If set to true, Control Center prompts a new user to

view and accept the End User License Agreement
(EULA) the first time the user logs into this account. If
set to false, Control Center does not prompt account
users to view and accept the EULA when they log in for
the first time.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 74
 Support

Return Value Description

supportEmail The support email address. If showAccountSupport is

set to yes, then this support email displays in the
Account Support section of the Help page.

supportPhone The support phone number. If showAcctSupport is set to

yes, then this support phone number displays in the
Account Support section on the Help page.

showAcctSupport If set to yes, then the support phone number and support
email displays in the Account Support section on the
Help page.

showSpSupport If set to yes, Control Center displays Service Provider

Support information on the Help page. On this page, the
account will see a support site URL, an email, and a
phone number. All this information is associated with
the operator profile located in Admin > Service
Provider Profile > Support Access. If you select false,
then users will not see the Service Provider Support
information on the Help page.

Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic
RW5nbGlzaFNQQWRtaW5RQTozOGFkNDI0Zi0yMjEzLTQ3ZDAtYjlmNS05OWEzZDdmNzEwNjg="
"https://restapi1.jasper.com/rws/api/v1/accounts/130265703/applicationSetti
ngs"

Response Example

{
"applicationFeature": {
"accessCommPlan": false,
"csdAccess": false,
"businessRulesEnabled": true,
"globalAccountEnabled": false,
"policiesEnabled": false,
"simOrderingEnabled": false,
"smsAccess": true,
"subscriptionChannel": false,
"voiceAccess": false
},
"simFeature": {
"blockBackwardSimState": false,
"defaultSimState": "TEST_READY",
"displayDiagnosticWizard": true,
"displaySpotlight": true,
"fixedIpEnabled": false,

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 75
 "testReadyDataLimit": 20480,
"testReadySmsLimit": 2,
"testReadyVoiceLimit": 120,
"testReadyCsdLimit": 120,
"testReadyDataState": "ACTIVATION_READY"
},
"siteConfiguration": {
"cobrandSite": null,
"fileExportMethod": "EXCEL",
"eulaEnabled": true
},
"support": {
"supportEmail": null,
"supportPhone": null,
"showAcctSupport": false,
"showSpSupport": true
}
}

Errors

Error Code HTTP Code Description

10000024 400 Invalid apiVersion.

20000003 404 Resource not found - Invalid accountId.

50001236 400 Unsupported Account Type.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 76
 Edit Account Application Settings
Description
Edits the application settings for a specific account. See the API/Role matrix
in the Knowledge Base for a complete list of roles that can use this API.

Resource URL
PUT BaseURL/v{apiVersion}/{accountId}/applicationSettings

Request Parameters
This function organizes the application settings data into four different
groups corresponding to the groups you'll see in the web interface (Admin
> Account Details > Application Settings):
l Application Feature
l SIM Feature
l Site Configuration
l Support

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

accountId The ID of the account whose application settings you

want to edit.

applicationFeature See the Application Feature table below.

simFeature See the SIM Feature table below.

siteConfiguration See the Site Configuration table below.

support See the Support table below.

Application Feature
All parameters are required.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 77
 Parameter Description

accessCommPlan All account users can see the communication plan

name in the device Edit form. This toggle determines
whether the field is editable.
If this toggle is set to true, then account users have
the ability to change a device's communication plan.
In addition, Control Center displays the
communication plan name in the Device List and on
the device Details page.
If the toggle is set to false, account users cannot
change a device's communication plan and will not
see the communication plan name in the Device List
and on the device Details page.

csdAccess A true or false indicates whether or not the

application displays access to Circuit Switched Data
(CSD) fields in the user interface are visible to
account users.

businessRulesEnabled A true or false indicates whether or not the

application has enabled business rules for the
account. The rules functionality is visible in the
Automation category to users associated with the
account. Be aware that any existing business rules
associated with the account continue to function even
it you disable rules for the account.

globalAccountEnabled If set to true, the Global SIM feature is enabled for

this account. This feature enables operators to create
partnerships with other operators to serve
multinational enterprise customers.
Unlike a typical roaming agreement between
operators, a global alliance allows the roaming SIM to
actually swap credentials (IMSIs, ICCIDs, and
MSISDNs) from the original operator to the partner
operator using over-the-air (OTA) swap technology.
If set to false, the Global SIM feature is disabled for
this account.

policiesEnabled This legacy field is no longer used.

simOrderingEnabled A true or false indicates whether or not the SIM

ordering feature is enabled for the account. If set to
true, account users can place an order that includes
the default rate plan and communication plan for the
new SIMs.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 78
 Parameter Description

smsAccess If this toggle is set to true, then the SMS fields in the
user interface are visible to account users. If this
toggle is set to false, then the SMS fields are not
visible.

subscriptionChannel A true or false indicates whether or not the

application has enabled a subscription channel. This
capability allows a deactivated account to go to a
specific URL and reactivate itself.

voiceAccess If this toggle is set to true, then the voice fields in the
user interface are visible to account users. If this
toggle is set to false, then the voice fields are not
visible.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 79
 SIM Feature
All parameters are required.

Parameter Description

blockBackwardSimState If set to true, account users cannot change a device

status from Activated to the pre-activated status
(such as Activation Ready, Inventory, or Test Ready).
If set to false, there are no restrictions on changing
a device status to Activation Ready, Inventory, or Test
Ready. This setting prevents an account from moving
under-used devices to Activation Ready where they
can avoid being charged a subscription fee until they
attempt to make a connection.

defaultSimState This field defines the default SIM state that devices
receive when the operator transfers them from the
inventory account into the enterprise account. For a
list of valid values, see SIM Status Values on page 29.

displayDiagnosticWizard The Diagnostics tool provides a very simple

interface that users with little wireless knowledge
can use to quickly see what is happening with a
device on the network. If set to Yes, then Control
Center displays the Diagnostics tool to account
users. If set to No, then Control Center hides the
Diagnostics tool from account users.

displaySpotlight Spotlight is a troubleshooting tool that provides a

detailed snapshot of device connectivity history over
the past 30 days so you can observe long-term
trends. This tool is designed for advanced support
representatives, who have technical expertise in
wireless connectivity. If set to Yes, then Control
Center displays Spotlight to account users. If s set to
No, then Control Center hides Spotlight from account
users.

fixedIpEnabled If set to true, Control Center displays the fixed IP

address (if any) for devices in the Device List page.
If set to false, Control Center does not display the
fixed IP addresses.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 80
 Parameter Description

testReadyDataLimit This field specifies the amount of data (in bytes) a

device in the Test Ready state receives free of
charge. Once the configured limit is reached for any
service (voice, SMS, data, or other), the device will
transition to the target state, and no more free test
traffic will be available for any service. A blank
value indicates there is no limit. For a zero value,
the device will reach the limit the first time it
initiates traffic. The upper values is 10.

testReadySmsLimit This field specifies the number of messages a device

in the Test Ready state will receive free of charge.
Once the configured limit is reached for any service
(voice, SMS, data, or other), the device will
transition to the target state, and no more free test
traffic will be available for any service. A blank
value indicates there is no limit. For a zero value,
the device will reach the limit the first time it sends
or receives a message. The upper values is 10.

testReadyVoiceLimit This field specifies the number of voice minutes a

device in the Test Ready state will receive free of
charge. Once the configured limit is reached for any
service (voice, SMS, data, or other), the device will
transition to the target state, and no more free test
traffic will be available for any service. A blank
value indicates there is no limit. For a zero value,
the device will reach the limit the first time it
places or receives a phone call. The upper values is
10.

testReadyCsdLimit This field specifies the number of Circuit Switched

Data in seconds (CSD) a device in the Test Ready
state will receive free of charge. Once the
configured limit is reached for any service (voice,
SMS, data, or other), the device will transition to the
target state, and no more free test traffic will be
available for any service. A blank value indicates
there is no limit. For a zero value, the device will
reach the limit the first time it places or receives a
phone call. The upper values is 10.

testReadyDataState Once the device reaches the configured limit in the

Test Ready state, Control Center automatically
moves the device to another SIM state. This field
specifies the next SIM state. Most operators use
either Activation Ready or Inventory. For a list of
valid values, see SIM Status Values on page 29.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 81
 Site Configuration
All parameters are required, but those marked as optional can take null
values.

Parameter Description

cobrandSite (Optional). The URL for the branded instance of Control

Center that account users will use to launch Control
Center.

fileExportMethod This field determines the format of an export files the

user creates. The options are Excel or CSV.

eulaEnabled If set to true, Control Center prompts a new user to

view and accept the End User License Agreement
(EULA) the first time the user logs into this account. If
set to false, Control Center does not prompt account
users to view and accept the EULA when they log in for
the first time.

Support
All parameters are required, but those marked as optional can take null
values.

Return Value Description

supportEmail (Optional) The support email address. If

showAccountSupport is set to yes, then this support
email displays in the Account Support section of the
Help page.

supportPhone (Optional) The support phone number. If

showAcctSupport is set to yes, then this support phone
number displays in the Account Support section on the
Help page.

showAcctSupport If set to yes, then the support phone number and support
email displays in the Account Support section on the
Help page.

showSpSupport If set to yes, Control Center displays Service Provider

Support information on the Help page. On this page, the
account will see a support site URL, an email, and a
phone number. All this information is associated with
the operator profile located in Admin > Service
Provider Profile > Support Access. If you select false,
then users will not see the Service Provider Support
information on the Help page.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 82
 Response Parameters
Control Center returns the account ID for the updated account.

Return Value Description

accountId An unique identifier for the updated account.

timestamp The date and time when the account was updated. The
timestamp displays in UNIX Epoch clock format. See
Date/Time Formats on page 28 for more information.

Request Example
Make sure to use your own URL and user credentials.

curl -X PUT --header "Content-Type: application/json" --header "Accept:

application/json" --header "Authorization: Basic
cWFhd3RzcGFkbWluOkF3dHRlc3QxMjM=" -d "{ {
\"applicationFeature\": {
\"accessCommPlan\": false, "
\"csdAccess\": false, "
\"businessRulesEnabled\": false,
\"globalAccountEnabled\": false,
\"policiesEnabled\": false,
\"simOrderingEnabled\": false,
\"smsAccess\": true,
\"subscriptionChannel\": false,
\"voiceAccess\": false
\"smsEnabled\": false,
\"voiceEnabled\": false
},
\"simFeature\": {
"blockBackwardSimState\": false,
"defaultSimState\": "TEST_READY",
"displayDiagnosticWizard\": true,
"displaySpotlight\": true,
"fixedIpEnabled\": false,
"testReadyDataLimit\": 20480,
"testReadySmsLimit\": 2,
"testReadyVoiceLimit\": 120,
"testReadyCsdLimit\": 120,
"testReadyDataState\": "ACTIVATION_READY"
},
\"siteConfiguration\": {
\"cobrandSite\": null,
\"fileExportMethod\": "EXCEL",
\"eulaEnabled\": true
},
\"support\": {
\"supportEmail\": null,
\ "supportPhone\": null,
\"showAcctSupport\": false,
\"showSpSupport\": true
}
}"
"https://restapi1.jasper.com/rws/api/v1/accounts/100020704/applicationSetti
ngs"

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 83
 Response Example

{
"accountId": 100020704,
"timestamp": 1527590173
}

Errors

Error HTTP
Description
Code Code

10000024 400 Invalid apiVersion.

10000301 400 Test Ready Data Limit length must be between 0 and
10.

10000302 400 Test Ready Sms Limit length must be between 0 and
10.

10000303 400 Test Ready Voice Limit length must be between 0 and
10.

10000304 400 Test Ready Csd Limit length must be between 0 and
10.

10000305 400 Test Ready Data Limit must be a positive number.

10000306 400 Test Ready Sms Limit must be a positive number.

10000307 400 Test Ready Voice Limit must be a positive number.

10000308 400 Test Ready Csd Limit must be a positive number.

10000309 400 Invalid Default Sim State.

10000310 400 Invalid Test ready data state.

10000311 400 Invalid File export method

10000312 400 No support information to show. Either Account

Support Email and/or Account Support Phone must be
specified.

10000313 400 Account Support Email must be a correctly formatted

email address and cannot contain commas.

10000314 400 Account Support Phone cannot be more than 25

characters and cannot contain commas (,) or asterisks
(*).

10000315 400 Invalid SMS Enabled value Only true/false allowed.

10000316 400 Invalid Voice Enabled value Only true/false allowed.

10000321 400 Application feature cannot be null.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 84
 Error HTTP
Description
Code Code

10000322 400 Sim feature cannot be null.

10000323 400 Site configuration cannot be null.

10000324 400 Support cannot be null.

10000325 400 AccessCommPlan cannot be null.

10000326 400 CsdAccess cannot be null.

10000327 400 BusinessRulesEnabled cannot be null.

10000328 400 GlobalAccountEnabled cannot be null.

10000329 400 PoliciesEnabled cannot be null.

10000330 400 SimOrderingEnabled cannot be null.

10000331 400 SmsAccess cannot be null.

10000332 400 SubscriptionChannel cannot be null.

10000333 400 VoiceAccess cannot be null.

10000334 400 SmsEnabled cannot be null.

10000335 400 VoiceEnabled cannot be null.

10000336 400 BlockBackwardSimState cannot be null.

10000337 400 DefaultSimState cannot be null.

10000338 400 DisplayDiagnosticWizard cannot be null.

10000339 400 DisplaySpotlight cannot be null.

10000340 400 FixedIpEnabled cannot be null.

10000341 400 TestReadyDataLimit cannot be null.

10000342 400 TestReadySmsLimit cannot be null.

10000343 400 TestReadyVoiceLimit cannot be null.

10000344 400 TestReadyCsdLimit cannot be null.

10000345 400 TestReadyDataState cannot be null.

10000346 400 FileExportMethod cannot be null.

10000347 400 EulaEnabled cannot be null.

10000348 400 ShowAcctSupport cannot be null.

10000349 400 ShowSpSupport cannot be null.

20000003 404 Resource not found - Invalid accountId.

50001236 400 Unsupported Account Type.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 85
 Get Account Billing Settings
Description
Retrieves the billing settings for a given account. See the API/Role matrix in
the Knowledge Base for a complete list of roles that can use this API.

Resource URL
GET BaseURL/v{apiVersion}/{accountId}/billingSettings

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

accountId The ID of the account.

Response Parameters

Parameter Description

general Contains the general billing setting information. See the

General table for parameter definitions.

commitments Contains information about device and account

commitments. See the Commitments table for
parameter definitions.

General Parameters

Return Value Description

billable If set to Yes, the account is billable. The default

value is No.

currentBillingCycleStart Indicates the first day of the account's current

billing cycle.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 86
 Return Value Description

prorationRule Indicates whether or not the billing engine will

prorate subscription fees in the first billing cycle
for devices using monthly rate plans.
l None. The first month’s subscription is charged
for the full month regardless of when the
device was first activated.
l Daily. The first month’s subscription is charged
based on the number of days since the device
was activated for the first time.
l Semi-Monthly. The first month’s subscription is
charged either a full or half month depending
on whether the device was activated for the
first time in the first half or second half of the
month.

renewalProrationRule Similar to activation proration, this parameter

covers the special case where a device ends a
prepaid rate plan and moves onto a monthly plan.
Control Center prorates the new subscription fee
on a semi-monthly or daily basis – or not at all,
depending on the value of this parameter. Valid
values are: Daily, Semi-Monthly, and None.

simFee This fee indicates how much the account is

charged for any SIMs purchased.

activationPlan The default activation plan defines how Control

Center applies the activation fee to each device
owned by the account.
l First Time Only. The account pays the activation
fee when the device is activated for the first
time (typical).
l Each Time. The account pays every time the
device SIM status changes to Activated.
l Not First Time. The account does not pay for
the first device activation, but it does pay for
every subsequent activation.
l None. No charge.

activationFee Control Center charges this fee based the

Activation Plan setting. This setting might be
replaced if it is set at the rate plan level. In that
case Control Center charges an activation fee
based on the settings associated with the current
device rate plan. (Admin > Accounts > Account
Name link > Rate Plans subtab > Edit Settings
button).

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 87
 Return Value Description

retailBilling Indicates whether the account can use the retail

billing feature:
l None. The account does not support retail
billing.
l Retail Customer. The account supports retail
billing.

immediateRatePlanChange If this parameter is set to true, you can change the

rate plan for a device mid-cycle (as long as the
device has an Activated SIM state) and Control
Center bills the device as if it had been on the new
rate plan during the entire billing cycle. This
behavior only applies to monthly rate plans. You
cannot change the rate plan for a device on a
prepaid rate plan until the plan expires.

defaultTimeZone The default time zone to use for this account.

eventPlanEnabled If set to true, then event plans are enabled for this
account. An event plan is a prepaid rate plan
that’s designed for special circumstances or
"events" that occur outside of a normal rate plan.
If set to false, then this account cannot use event
plans. The default is false.

prepaidRenewalPolicy When a prepaid rate plan expires, Control Center

either deactivates the device or gives it a
different rate plan. You can specify the default
renewal behavior for all the account’s prepaid
rate plans. The options are as follows:
l Deactivate. (Default) Deactivate the device.
l AutoRenew. Renew the current prepaid rate
plan.
l NamedPlan. Assign a specific rate plan or
assign the next rate plan in the device queue.

prepaidRenewalRatePlanId When a prepaid device rate plan expires, Control

Center attaches the named rate plan to the device.
If the device has a queue, Control Center uses the
rate plan at the top of the queue instead of the
named plan here.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 88
 Commitments Parameters

Return Value Description

activationGracePeriod This length of time (specified in days) is the grace

period between the time a device is transferred
to an account and Control Center starts billing for
the device. If the device is not active (and
billable) by the time this grace period ends,
Control Center starts billing the subscription fee
in the next billing cycle. To enable this feature,
you must also set the Bill Activation Grace Period
value to true.
The grace period for devices using prepaid rate
plans is indefinite. Control Center does not charge
for these devices until they become active.

billActivationGracePeriod When this parameter is set to true, Control Center

enables the activation grace period feature and
bill the account for a device, regardless of its
status, after the activation period ends. You also
need to define the length of the grace period with
the Activation Grace Period parameter. The
default is false.

monthlyDevicesMinimum This parameter specifies the length of time the

Term monthly device minimum will be in effect for each
device in the account. The term begins on the
device's activation date. The maximum term is
999 months.

monthlyDeviceMinimum This parameter specifies the minimum revenue a

device is expected to provide in each billing cycle.
The maximum amount is 9999.99 (in the account's
default currency).

billMonthlyDeviceMinimum If set to true, Control Center enables the monthly

device minimum commitment using the values in
the mdmCommitmentTerm and mdmCommitment
parameters.

minimumActivationTerm The number of months each device must be

active. To enable this feature, you must also set
the Bill Minimum Activation Term parameter to
true.

billMinimumActivation If set to true, Control Center enables the minimum

Term activation term feature and bills the subscription
fee for any devices that have not been active long
enough to meet the minimum requirement. The
default is false.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 89
 Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic cWFhd3RzcGFkbWluOkF3dHRlc3QxMjM="
"https://restapi1.jasper.com/rws/api/v1/accounts/100015068/billingSettings"

Response Example
{
"general": {
"billable": "No",
"currentBillingCycleStart": "12th of month(Europe/Moscow)",
"prorationRule": "None",
"renewalProrationRule": "None",
"simFee": null,
"activationPlan": "None",
"activationFee": null,
"retailBilling": "None",
"immediateRatePlanChange": true,
"defaultTimeZone": null,
"eventPlanEnabled": false,
"prepaidRenewalPolicy": "Deactivate",
"prepaidRenewalRatePlanId": null
}
"commitments": {
"activationGracePeriod": 365,
"billActivationGracePeriod": false,
"monthlyDevicesMinimumTerm": null,
"monthlyDeviceMinimum": null,
"billMonthlyDeviceMinimum": false,
"minimumActivationTerm": null,
"billMinimumActivationTerm": false
}
}

Errors

HTTP
Error Code Description
Code

10000004 400 Invalid accountId.

10000024 400 Invalid apiVersion.

20000003 404 Resource not found - Invalid accountId.

20000031 400 Invalid request to view account billing settings.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 90
 Edit Account Billing Settings
Description
Changes the billing settings for a given account. See the API/Role matrix in
the Knowledge Base for a complete list of roles that can use this API.

Resource URL
PUT BaseURL/v{apiVersion}/{accountId}/billingSettings

Request Parameters
All parameters are required.

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

accountId The identification number of an existing account.

general Contains the general billing setting information. See the

General table for parameter definitions.

commitments Contains information about device and account

commitments. See the Commitments table for
parameter definitions.

General Parameters

Parameter Description

taxable If set to true, the account is taxable. The default

value is false.

billable If set to true, the account is billable. The default

value is false.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 91
 Parameter Description

prorationRule Indicates whether or not the billing engine will

prorate subscription fees in the first billing cycle
for devices using monthly rate plans.
l None. The first month’s subscription is charged
for the full month regardless of when the
device was first activated.
l Daily. The first month’s subscription is charged
based on the number of days since the device
was activated for the first time.
l Semi-Monthly. The first month’s subscription is
charged either a full or half month depending
on whether the device was activated for the
first time in the first half or second half of the
month.

renewalProrationRule Similar to activation proration, this parameter

covers the special case where a device ends a
prepaid rate plan and moves onto a monthly plan.
Control Center prorates the new subscription fee
on a semi-monthly or daily basis – or not at all,
depending on the value of this parameter. Valid
values are: Daily, Semi-Monthly, and None.

simFee This fee indicates how much the account is

charged for any SIMs purchased.

activationPlan The default activation plan defines how Control

Center applies the activation fee to each device
owned by the account.
l First Time Only. The account pays the activation
fee when the device is activated for the first
time (typical).
l Each Time. The account pays every time the
device SIM status changes to Activated.
l Not First Time. The account does not pay for
the first device activation, but it does pay for
every subsequent activation.
l None. No charge.

activationFee Control Center charges this fee based the

Activation Plan setting. This setting might be
replaced if it is set at the rate plan level. In that
case Control Center charges an activation fee
based on the settings associated with the current
device rate plan. (Admin > Accounts > Account
Name link > Rate Plans subtab > Edit Settings
button).

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 92
 Parameter Description

retailBilling Not supported for operator users. Control Center

ignores any values you supply for this parameter.

immediateRatePlanChange If this parameter is set to true, you can change the

rate plan for a device mid-cycle (as long as the
device has an Activated SIM state) and Control
Center bills the device as if it had been on the new
rate plan during the entire billing cycle. This
behavior only applies to monthly rate plans. You
cannot change the rate plan for a device on a
prepaid rate plan until the plan expires.

defaultTimeZone The default time zone to use for this account

eventPlanEnabled If set to true, then event plans are enabled for this
account. An event plan is a prepaid rate plan
that’s designed for special circumstances or
"events" that occur outside of a normal rate plan.
If set to false, then this account cannot use event
plans. The default is false.

prepaidRenewalPolicy When a prepaid rate plan expires, Control Center

either deactivates the device or gives it a
different rate plan. You can specify the default
renewal behavior for all the account’s prepaid
rate plans. The options are as follows:
l Deactivate. (Default) Deactivate the device.
l AutoRenew. Renew the current prepaid rate
plan.
l NamedPlan. Assign a specific rate plan or
assign the next rate plan in the device queue.

prepaidRenewalRatePlanId When a prepaid device rate plan expires, Control

Center attaches the named rate plan to the device.
If the device has a queue, Control Center uses the
rate plan at the top of the queue instead of the
named plan here.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 93
 Commitments Parameters

Parameter Description

activationGracePeriod This length of time (specified in days) is the grace

period between the time a device is transferred
to an account and Control Center starts billing for
the device. If the device is not active (and
billable) by the time this grace period ends,
Control Center starts billing the subscription fee
in the next billing cycle. To enable this feature,
you must also set the Bill Activation Grace Period
value to true.
The grace period for devices using prepaid rate
plans is indefinite. Control Center does not charge
for these devices until they become active.

billActivationGracePeriod When this parameter is set to true, Control Center

enables the activation grace period feature and
bill the account for a device, regardless of its
status, after the activation period ends. You also
need to define the length of the grace period with
the Activation Grace Period parameter. The
default is false.

monthlyDevicesMinimum This parameter specifies the length of time the

Term monthly device minimum will be in effect for each
device in the account. The term begins on the
device's activation date. The maximum term is
999 months.

monthlyDeviceMinimum This parameter specifies the minimum revenue a

device is expected to provide in each billing cycle.
The maximum amount is 9999.99 (in the account's
default currency).

billMonthlyDeviceMinimum If set to true, Control Center enables the monthly

device minimum commitment using the values in
the mdmCommitmentTerm and mdmCommitment
parameters.

minimumActivationTerm The number of months each device must be

active. To enable this feature, you must also set
the Bill Minimum Activation Term parameter to
true.

billMinimumActivation If set to true, Control Center enables the minimum

Term activation term feature and bills the subscription
fee for any devices that have not been active long
enough to meet the minimum requirement. The
default is false.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 94
 Response Parameters

Return Value Description

accountID The ID of the account.

timestamp The date and time when the account was updated. The
timestamp displays in UNIX Epoch clock format. See
Date/Time Formats on page 28 for more information.

Request Example
Make sure to use your own URL and user credentials.

curl -X PUT --header "Content-Type: application/json" --header "Accept:

application/json" --header "Authorization: Basic
RW5nbGlzaFNQRmluQXBwTWl4ZWQ6NWFhNGRlOTMtMTZiZS00MzZiLTliNDEtOWE3Y2Y4ZTZhMGZ
k" -d "{
{
\"general\":
{
\"taxable\": false,
\"billable\": false,
\"prorationRule\": \"None\",
\"renewalProrationRule\": \"None\",
\"simFee\": 0,
\"activationPlan\": \"None\",
\"activationFee\": 0,
\"retailBilling\": \"None\",
\"immediateRatePlanChange\": true,
\"defaultTimeZone\": null,
\"eventPlanEnabled\": false,
\"prepaidRenewalPolicy\": \"Deactivate\",
\"prepaidRenewalRatePlanId\": null
},
\"commitments\":
{
\"activationGracePeriod\": 180,
\"billActivationGracePeriod\": true,
\"monthlyDevicesMinimumTerm\": 0,
\"monthlyDeviceMinimum\": 0,
\"billMonthlyDeviceMinimum\": false,
\"minimumActivationTerm\": 0,
\"billMinimumActivationTerm\": false
}
}"
"https://restapi1.jasper.com/rws/api/v1/accounts/100015068/billingSettings"

Response Example
{
"accountId": 100015068,
"timestamp": 1527590173
}

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 95
 Errors

HTTP
Error Code Description
Code

10000004 400 Invalid accountId.

10000024 400 Invalid apiVersion.

20000003 404 Resource not found - Invalid accountId.

20000013 400 Account billing settings cannot be edited for operator

account.

20000014 400 Empty monthly devices minimum term (months).

20000015 400 Empty monthly device minimum.

20000016 400 Invalid activation proration.

20000017 400 Invalid renewal proration.

20000018 400 Invalid sim fee scale.

20000021 400 Invalid default activation fee scale.

20000019 400 Sim fee should be between [0-9999999].

20000020 400 Invalid default activation plan.

20000022 400 Default activation fee should be between [0-9999999].

20000023 400 Invalid enable retail billing.

20000024 400 Invalid default timezone.

20000025 400 Invalid prepaid renewal policy.

20000026 400 Invalid prepaid renewal rate plan.

20000028 400 Monthly devices minimum term should be between

[0-999].

20000027 400 Invalid activation grace period.

20000029 400 Monthly device minimum should be between [0-

999.99].

20000030 400 Invalid minimum activation term.

20000031 400 Invalid request to view account billing settings.

20000032 400 Billing commitment settings cannot be edited for

Essential/Partner accounts.

20000033 400 Invalid request to perform edit operation.

20000034 400 Account billing settings cannot be edited for NBIOT

account.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 96
 HTTP
Error Code Description
Code

20000041 400 Taxable cannot be null.

20000042 400 Billable cannot be null.

20000043 400 ProrationRule cannot be null.

20000044 400 RenewalProration cannot be null.

20000045 400 ActivationPlan cannot be null.

20000046 400 RetailBilling cannot be null.

20000049 400 PrepaidRenewalPolicy cannot be null.

20000047 400 ImmediateRatePlanChange cannot be null.

20000048 400 EventPlanEnabled cannot be null.

20000050 400 PrepaidRenewalRatePlanId cannot be null.

20000051 400 BillActivationGracePeriod cannot be null.

20000052 400 MonthlyDevicesMinimumTerm cannot be null.

20000053 400 MonthlyDeviceMinimum cannot be null.

20000054 400 BillMonthlyDeviceMinimum cannot be null.

20000056 400 Commitments settings cannot be null.

20000055 400 BillMinimumActivationTerm cannot be null.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 97
 Get Available Rate Plans for an Account
Description
The operator can get available rate plans for an account. These rate plans
include custom rate plans associated with the account as well as shared
rate plans that the operator assigned to the account. See the API/Role
matrix in the Knowledge Base for a complete list of roles that can use this
API.

Resource URL
GET BaseURL/v{apiVersion}/accounts/{accountId}/ratePlans

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

accountId The ID of the account whose rate plan you want to

retrieve.

pageSize (Optional) Specifies the number of records returned in

each response page. The maximum value is 50. The
value defaults to 50.

pageNumber (Optional) Specifies the number of response pages to

return. This value defaults to 1.

Response Parameters

Return Value Description

pageNumber An integer specifying the number of the current

response page. This value defaults to 1. See Pagination
on page 27.

ratePlans An array of rate plans.

ratePlanId A rate plan identifier, that is not necessarily unique. A

rate plan can have multiple versions that share the
same ratePlan ID. See versionId.

ratePlanName The name of the rate plan.

versionId Uniquely identifies a particular version of a rate plan in

relation to every other rate plan version in the system.
Because a rate plan may have multiple active versions,
the versionId, and not the ratePlanId is the only truly
unique rate plan identifier.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 98
 Return Value Description

shared If set to true, it indicates that this rate plan is available

to multiple accounts. If set to false, the rate plan is
assigned to a specific account.

lastPage A true or false value indicating whether the current

response page is the last in the series. See Pagination
on page 27.

Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic cWFhd3RzcGFkbWluOkF3dHRlc3QxMjM=
"
"https://restapi1.jasper.com/rws/api/v1/accounts/100015068/ratePlans?pageSi
ze=50&pageNumber=1"

Response Example
{
"pageNumber": 1,
"ratePlans": [
{
"ratePlanId": 39374,
"ratePlanName": "QASPAWTRP",
"versionId": 28060,
"shared": true
}
],
"lastPage": true
}

Errors

HTTP
Error Code Description
Code

10000004 400 Invalid accountId.

10000006 400 Invalid pageSize.

10000007 400 Invalid pageNumber.

10000024 400 Invalid apiVersion.

20000003 404 Resource not found - Invalid accountId.

20000035 400 Shared rate plans can only be viewed by

Advantage/Essential accounts.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 99
 Edit Available Rate Plans for an Account
Description
Changes the shared rate plans associated with a specified account. The
function allows an operator to add or remove a shared rate plan from an
account. You must have a ServiceProvideFinance or
ServiceProviderCSRUser role to perform this function.

Resource URL
PUT BaseURL/v{apiVersion}/accounts/{accountId}/ratePlans

Request Parameters
This function specifies all the shared rate plans associated with the
specified account. If you remove an existing shared rate plan from your
request parameters, you will delete the shared rate plan from the account.
All request parameters are required.

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

accountId The ID of the account whose rate plans you want to

change.

sharedRatePlans A comma-separated list of shared rate plans that you

want to assign to the account. The named rate plans
will overwrite any shared rate plans already
associated with the account. You must include a
minimum of one shared rate plan.

Response Parameters

Return Value Description

accountId The ID of the account you want to change.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 100
 Request Example
Make sure to use your own URL and user credentials.

curl -X PUT --header "Content-Type: application/json" --header "Accept:

application/json" --header "Authorization: Basic
RW5nbGlzaFNQRmluTWl4ZWQ6ODY3YzBiYWYtOWFhYS00NTRlLTg0YTAtNmViODE3MTM0NGVh" -d
"{
\"sharedRatePlans\": [
\"100MB Pool\",
\"200MB Pool\",
\"300MB Pool\"
]
}" "https://restapi1.jasper.com/rws/api/v1/accounts/100015068/ratePlans"

Response Example

{
"accountId": 100015068
}

Errors

HTTP
Error Code Description
Code

10000004 400 Invalid accountId.

10000024 400 Invalid apiVersion.

20000003 404 Resource not found - Invalid accountId.

20000036 400 Invalid request to assign shared rate plans to the

account.

20000037 400 Operation cannot be performed as there are no rate

plans available for this account.

20000038 400 Cannot perform operation as one or more shared

rate plans not available for this account.

20000039 500 Error adding shared rate plan id mappings to the

account.

20000040 400 Shared rate plans can only be added by

Advantage/Essential accounts.

20000057 400 Failed to update shared plans. Cannot remove the

account default rate plan.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 101
API Key
Create/Reset API Key for Given User
Description
Resets the API key for a given user and returns the new value. If the user
does not have an API key, the function creates a new key for the user. You
must have access to this user's information in order to change or create an
API key. In addition, you cannot reset or create an API key for a user if they
have web interface access and can perform these tasks for themselves.
To reset your own API key, you must use a different API (see Reset API Key
for Current User on page 106). You cannot create an API key for yourself.
This function is available to service provider and account administrators,
but not customer users. See the API/Role matrix in the Knowledge Base for
a complete list of roles that can use this API.

Warning. Resetting the API key immediately invalidates any API key in use.
To avoid a lockout, we recommend you save the response containing the
new key and then use it to update any programs using the previous key.

Resource URL
PUT BaseURL/v{apiVersion}/apikey/{userId}

Request Parameters

Return Value Description

apiVersion The version number for this API. The current version for
all functions is 1.

userId The ID of the user whose API key you want to reset or
create. If there is no user ID, the function resets the
API key for the user making the function call. See Reset
API Key for Current User on page 106.

Response Parameters

Return Value Description

userId The ID of the requested user. If you reset your own

API key, the function returns your own user ID.

apiKey The new API key value for the requested user.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 102
 Return Value Description

timestamp The date and time when the API key was created or
updated. The timestamp displays in UNIX Epoch clock
format. See Date/Time Formats on page 28 for more
information.

Request Example
Make sure to use your own URL and user credentials.

curl -X PUT --header "Accept: application/json" --header "Authorization:

Basic
RW5nbGlzaFNQQWRtaW5RQTozOGFkNDI0Zi0yMjEzLTQ3ZDAtYjlmNS05OWEzZDdmNzEwNjg="
"https://restapi1.jasper.com/rws/api/v1/apikey/401038105"

Response Example

{
"userId": 401038105,
"apiKey": "84b5c96e-9bfb-4565-b4b5-e73fd41b998f",
"timestamp": 1549369025
}

Errors

Error HTTP
Description
Code Code

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000024 400 Invalid apiVersion.

10000030 400 Your role does not have access to this API function.

10000438 404 Resource not found - Invalid username.

10000439 400 Unauthorized access to the user.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 103
 Get API Key
Description
Returns the API key for a given user. If the user doesn't have an API key or
if the key has expired, the function returns an empty value. You must have
access to this user's information in order to get the API key. Be aware that
you cannot get a user's API key if the user has web interface access.
This function is available to service provider and account users, but not
customer users. See the API/Role matrix in the Knowledge Base for a
complete list of roles that can use this API.

Resource URL
GET BaseURL/v{apiVersion}/apikey/{userId}

Request Parameters

Return Value Description

apiVersion The version number for this API. The current version
for all functions is 1.

userId The ID of the user whose API key you want to get.

Response Parameters

Return Value Description

userId The ID of the requested user.

apiKey The API key value for the requested user. If the user
doesn't have an API key or if the key has expired, the
function returns an empty value.

timestamp The date and time when the API key was returned. The
timestamp displays in UNIX Epoch clock format. See
Date/Time Formats on page 28 for more information.

Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic
RW5nbGlzaFNQQWRtaW5RQTozOGFkNDI0Zi0yMjEzLTQ3ZDAtYjlmNS05OWEzZDdmNzEwNjg="
"https://restapi1.jasper.com/rws/api/v1/apikey/401056705"

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 104
 Response Example

{
"userId": 401056705,
"apiKey": "84b5c96e-9bfb-4565-b4b5-e73fd41b998f",
"timestamp": 1549365650
}

Errors

Error HTTP
Description
Code Code

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000024 400 Invalid apiVersion.

10000030 400 Your role does not have access to this API function.

10000438 404 Resource not found - Invalid username.

10000439 400 Unauthorized access to the user.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 105
 Reset API Key for Current User
Description
Resets the API key for the user making the function call. For security
reasons, you may want to reset the key on a regular basis—or whenever
you have reason to believe the key has been compromised.
All service provider and account users have access to this function.
Customer users do not have access to this API and must request a key reset
from an account administrator. See the API/Role matrix in the Knowledge
Base for a complete list of roles that can use this API.

Warning. Resetting the API key immediately invalidates the API key in use.
To avoid a lockout, we recommend you save the response containing the
new key and then use it to update any programs using the previous key.

Resource URL
PUT BaseURL/v{apiVersion}/apikey

Request Parameters

Return Value Description

apiVersion The version number for this API. The current version
for all functions is 1.

Response Parameters

Return Value Description

apiKey New API key value.

Request Example
Make sure to use your own URL and user credentials.

curl -X PUT --header "Accept: application/json" --header "Authorization:

Basic
RW5nbGlzaFNQQWRtaW5RQTozOGFkNDI0Zi0yMjEzLTQ3ZDAtYjlmNS05OWEzZDdmNzEwNjg="
"https://restapi1.jasper.com/rws/api/v1/apikey"

Response Example

{
"apiKey": "7a8af469-fc46-40da-903a-00acaea9940d"
}

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 106
 Code Samples
Make sure to use your own URL and user credentials.
Ruby

#!/usr/bin/ruby -w
require 'rest-client'
require 'json'
require 'base64'
$auth = 'Basic' + Base64.encode64( 'apiuser:469bfd67-62a2-4ab6-9df6-
d5cf5527e7a8' ).chomp
$url = 'https://restapi1.jasper.com/rws/api/v1/apikey'
@resource = RestClient::Resource.new( $url )
@response = @resource.put( :Authorization => $auth )
puts JSON.parse(response)

Errors

Error HTTP
Description
Code Code

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000024 400 Invalid apiVersion.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 107
Customers
Get Customer Details
Description
Returns the customer details for a given customer. Users can view detailed
information for any customers to which they have access. In general, service
provider users can view all customers, account users can view all customers
within their account, and customer users can view their own customer
information. If a user is part of an account group or a customer group,
however, the group may restrict or expand the user’s access to information.
See the API/Role matrix in the Knowledge Base for a complete list of roles
that can use this API.

Resource URL
GET BaseURL/v{apiVersion}/customers/{customerId}

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

customerId The identification number of the customer.

Response Parameters

Return Value Description

name The name of the customer.

accountName The name of the account to which the customer

belongs.

securityQuestion The security question.

securityAnswer The answer to the security question.

shipToBillAddress If true, the customer's billing address is the same as

the shipping address.

contacts An array of contacts. See the Contacts table below.

billingAddress See the Address table below.

shippingAddress See the Address table below.

customerId The identification number of the customer.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 108
 Contacts Parameters
The function returns an array of up to four contacts.

Return Value Description

name The name of the customer contact.

title The title of the customer contact.

phone The phone number of the customer contact.

mobile The mobile phone number of the customer contact.

email The email address of the customer contact.

Address Parameters
The shipping and billing address use the same response parameters.

Return Value Description

addressLine1 The first line of the address.

addressLine2 The second line of the address.

city The city.

state The region, for example, state or province.

country The country.

postalCode Postal code.

Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic cWFhd3RzcGFkbWluOkF3dHRlc3QxMjM="
"https://restapi1.jasper.com/rws/api/v1/customers/10008314"

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 109
 Response Example

{
"name": "Acme Corporation",
"accountName": "QASPAWT_Act003",
"securityQuestion": null,
"securityAnswer": null,
"shipToBillAddress": true,
"contacts": [
{
"name": "Jules Bron",
"title": "Director",
"phone": "323-948-2312",
"mobile": "408-796-9432",
"email": "julesbron@acme.com"
}
],
"billingAddress": {
"addressLine1": "123 Main Street",
"addressLine2": null,
"city": "Buckley",
"state": "Tennessee",
"country": "United States",
"postalCode": "42308"
},
"shippingAddress": {
"addressLine1": "123 Main Street",
"addressLine2": null,
"city": "Buckley",
"state": "Tennessee",
"country": "United States",
"postalCode": "42308"
},
"customerId": 100021774
}

Errors

HTTP
Error Code Description
Code

10000024 400 Invalid apiVersion.

10000603 400 Invalid account. Account erasure request is in

progress for the account.

10000604 400 Invalid Customer Id.

10000605 404 Customer not found with given Id.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 110
 Edit Customer Details
Description
Updates the detailed information for any customers to which users have
access. In general, service provider users can view all customers, account
users can view all customers within their account, and customer users can
view their own customer information. If a user is part of an account group
or a customer group, however, the group may restrict or expand the user’s
access to information. See the API/Role matrix in the Knowledge Base for a
complete list of roles that can use this API.

Resource URL
PUT BaseURL/v{apiVersion}/customers/{customerId}

Request Parameters
Caution. This function overwrites existing customer information using
parameter values you supply. Control Center uses default values for any
parameters that are missing from the call. To avoid losing data, make sure
to provide existing values for any unchanged parameters.

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

name The name of the customer that you want to update.

accountName The account name for the customer.

securityAnswer The answer to the security question. If a

securityAnswer is used, the securityQuestion is
required. The string allows a maximum of 100
characters. A null value is acceptable

securityQuestion A security question. If a securityAnswer is used, the

securityQuestion is required. The string allows a
maximum of 100 characters. A null value is acceptable.

shipToBillAddress Set this value to true if you want to to use the

customer's billing address as the shipping address.

contacts See the Contact Parameters table below. A null value

is acceptable.

billingAddress See the Address Parameters table below.

shippingAddress See the Address Parameters table below.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 111
 Contact Parameters
Each customer can have a maximum of four contacts.

Parameter Description

name The name of the contact. The string allows 0 to 40

characters.

title The title of the contact. The string allows 0 to 40

characters.

phone The phone number of the contact. The string allows 0

to 25 characters.

mobile The mobile number of the contact. The string allows 0

to 25 characters.

email The email address of the contact. The string allows 0 to

320 characters.

Address Parameters
The following parameters are used for both billingAddress and
shippingAddress.

Parameter Description

addressLine1 The first line of the contact's billing/shipping address.

This is typically a street number and a street name. The
string allows 0 to 40 characters.

addressLine2 The second line of the contact's billing/shipping

address. The string allows 0 to 40 characters.

city The city of the contact. The string allows 0 to 40

characters.

state The state or province of the contact. The string allows 0

to 40 characters.

country The country of the contact. The string allows 0 to 150

characters.

postalCode The postal code of the contact. The string allows 0 to 15

characters.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 112
 Response Parameters

Return Value Description

customerId The customer identification number associated with the

customer name.

timestamp The date and time when the customer was updated. The
timestamp displays in UNIX Epoch clock format. See
Date/Time Formats on page 28 for more information.

Request Example
Make sure to use your own URL and user credentials.

curl -X PUT --header "Content-Type: application/json" --header "Accept:

application/json" --header "Authorization: Basic
cWFhd3RzcGFkbWluOkF3dHRlc3QxMjM=" -d "{
\"name\": \"Acme Customer\",
\"accountName\": \"Acme\",
\"securityQuestion\": null,
\"securityAnswer\": null,
\"shipToBillAddress\": true,
\"contacts\": [
{
\"name\": \"Jules Bron\",
\"title\": \"Director\",
\"phone\": \"323-948-2312\",
\"mobile\": \"408-796-9432\",
\"email\": \"julesbron@acme.com\"
},
{
\"name\": \"Guillaume Avicci\",
\"title\": \"VP\",
\"phone\": \"323-948-5722\",
\"email\": \"guillaumea@acme.com\"
}
],
\"billingAddress\":
{
\"addressLine1\": \"123 Main Street\",
\"addressLine2\": \"string\",
\"city\": \"Buckley\",
\"state\": \"Tennessee\",
\"country\": \"United States\",
\"postalCode\": \"42308\"
}
\"shippingAddress\":
{
\"addressLine1\": \"123 Main Street\",
\"addressLine2\": \"string\",
\"city\": \"Buckley\",
\"state\": \"Tennessee\",
\"country\": \"United States\",
\"postalCode\": \"42308\"
}
}" "https://restapi1.jasper.com/rws/api/v1/customers/10008314/"

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 113
 Response Example

{
"customerId": 10008314,
"timestamp": 1527590173
}

Errors

HTTP
Error Code Description
Code

10000004 400 Invalid accountId.

10000024 400 Invalid apiVersion.

10000580 400 Customer details required.

10000581 400 Customer name is required.

10000582 400 Invalid customer name. Number of characters

allowed 1 - 60.

10000583 400 Account Id is required.

10000584 400 Security answer missing.

10000585 400 Security question missing.

10000586 400 Invalid security question. Number of characters

allowed 0 - 100.

10000587 400 Invalid security answer. Number of characters

allowed 0 - 100.

10000588 400 Maximum 4 contacts can be associated with a

customer.

10000589 400 Invalid contact name. Number of characters allowed

0 - 40.

10000590 400 Invalid contact title. Number of characters allowed

0 - 40.

10000591 400 Invalid contact phone. Number of characters allowed

0 - 25.

10000592 400 Invalid contact mobile. Number of characters

allowed 0 - 40.

10000593 400 Invalid contact email. Number of characters allowed

0 - 320.

10000594 400 Invalid address line1. Number of characters allowed

0 - 40.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 114
 HTTP
Error Code Description
Code

10000595 400 Invalid address line2. Number of characters allowed

0 - 40.

10000596 400 Invalid city. Number of characters allowed 0 - 40.

10000597 400 Invalid state/region. Number of characters allowed

0 - 40.

10000598 400 Invalid country. Number of characters allowed 0 -

100.

10000599 400 Invalid postal code. Number of characters allowed 0

- 15.

10000602 400 Duplicate customer name.

10000603 400 Invalid account. Account erasure request is in

progress for the account.

20000003 404 Resource not found - Invalid accountId.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 115
 Create Customer
Description
Creates a new customer. Both service provider and account users can create
customers. In general, service provider users can create customers for any
account and account users can create customers within their own account.
If a user is part of an account group or a customer group, however, the
group may restrict or expand the user’s ability to create customers within
the given account. See the API/Role matrix in the Knowledge Base for a
complete list of roles that can use this API.

Resource URL
POST BaseURL/v{apiVersion}/customers

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

name The name of the customer. The string must contain at

least one character with a maximum of 60 characters.
You can include spaces and special characters in the
customer name.

accountName The name of the parent account containing the

customer.

securityAnswer (Optional) The answer to the security question. This

field is required if there is a securityQuestion. The
string allows a maximum of 100 characters.

securityQuestion (Optional) A security question. If a securityAnswer is

used, the securityQuestion is required. The string
allows a maximum of 100 characters.

shipToBillAddress (Optional) Set this value to true if you want to use the
customer's billing address as the shipping address. The
default is false.

contacts (Optional) See the Contact Parameters table below.

billingAddress (Optional) See the Address Parameters table below.

shippingAddress (Optional) See the Address Parameters table below.

This address is required if shipToBillAddress is false.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 116
 Contact Parameters
Each customer can have a maximum of four contacts. A customer contact is
optional.

Parameter Description

name The name of the contact. The string allows 0 to 40

characters.

title The title of the contact. The string allows 0 to 40

characters.

phone The phone number of the contact. The string allows 0

to 25 characters.

mobile The mobile number of the contact. The string allows 0

to 25 characters.

email The email address of the contact. The string allows 0 to

320 characters.

Address Parameters
The following parameters are used for both billingAddress and
shippingAddress. Billing addresses are optional.

Parameter Description

addressLine1 The first line of the contact's billing/shipping address.

This is typically a street number and a street name. The
string allows 0 to 40 characters.

addressLine2 The second line of the contact's billing/shipping

address. The string allows 0 to 40 characters.

city The city of the contact. The string allows 0 to 40

characters.

state The state or province of the contact. The string allows 0

to 40 characters.

country The country of the contact. The string allows 0 to 150

characters.

postalCode The postal code of the contact. The string allows 0 to 15

characters.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 117
 Response Parameters

Return Value Description

customerId The identification number of the customer that was

created.

timestamp The date and time when the customer was created. The
timestamp displays in UNIX Epoch clock format. See
Date/Time Formats on page 28 for more information.

Request Example
Make sure to use your own URL and user credentials.

curl -X POST --header "Content-Type: application/json" --header "Accept:

application/json" --header "Authorization: Basic
cWFhd3RzcGFkbWluOkF3dHRlc3QxMjM=" -d "{
\"name\": \"Acme Customer\",
\"accountName\": \"Acme\",
\"securityQuestion\": \"FirstConcert\",
\"securityAnswer\": \"Journey\",
\"shipToBillAddress\": true,
\"billingAddress\":
{
\"addressLine1\": \"123 Main\",
\"addressLine2\": \"string\",
\"city\": \"Anytown\",
\"state\": \"FLA\",
\"country\": \"USA\",
\"postalCode\": \"36301\"
}
}" "https://restapi1.jasper.com/rws/api/v1/customers"

Response Example

{
"customerId": 1234,
"timestamp": 1527590173
}

Errors

HTTP
Error Code Description
Code

10000004 400 Invalid accountId.

10000024 400 Invalid apiVersion.

10000580 400 Customer details required.

10000581 400 Customer name is required.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 118
 HTTP
Error Code Description
Code

10000582 400 Invalid customer name. Number of characters

allowed 1 - 60.

10000583 400 Account Id is required.

10000584 400 Security answer missing.

10000585 400 Security question missing.

10000586 400 Invalid security question. Number of characters

allowed 0 - 100.

10000587 400 Invalid security answer. Number of characters

allowed 0 - 100.

10000588 400 Maximum 4 contacts can be associated with a

customer.

10000589 400 Invalid contact name. Number of characters allowed

0 - 40.

10000590 400 Invalid contact title. Number of characters allowed

0 - 40.

10000591 400 Invalid contact phone. Number of characters allowed

0 - 25.

10000592 400 Invalid contact mobile. Number of characters

allowed 0 - 40.

10000593 400 Invalid contact email. Number of characters allowed

0 - 320.

10000594 400 Invalid address line1. Number of characters allowed

0 - 40.

10000595 400 Invalid address line2. Number of characters allowed

0 - 40.

10000596 400 Invalid city. Number of characters allowed 0 - 40.

10000597 400 Invalid state/region. Number of characters allowed

0 - 40.

10000598 400 Invalid country. Number of characters allowed 0 -

100.

10000599 400 Invalid postal code. Number of characters allowed 0

- 15.

10000602 400 Duplicate customer name.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 119
 HTTP
Error Code Description
Code

10000603 400 Invalid account. Account erasure request is in

progress for the account.

20000003 404 Resource not found - Invalid accountId.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 120
Devices
Search Devices
Description
For a given enterprise account, returns a list of devices that have changed
since a specified date. You can filter the list by SIM status.

Resource URL
GET BaseURL/v{apiVersion}/devices

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

accountId (Optional) Unique identifier for the account that owns

the devices you're searching for. If you omit this
parameter, Control Center uses the account associated
with the user name.

modifiedSince A date and time using the ISO 8601 format. The function
returns any devices that have been modified since this
time.

status (Optional) A SIM status value. The function returns only

devices with this status. For a list of valid values, see
SIM Status Values on page 29.

pageSize (Optional) Specifies the number of records returned in

each response page. The maximum value is 50. The
value defaults to 50. See Pagination on page 27.

pageNumber (Optional) Specifies the number of response pages to

return. This value defaults to 1. See Pagination on
page 27.

Response Parameters
The function returns an array of devices with the information below.
Records are sorted by modification date in ascending order with the oldest
device change listed first.

Return Value Description

devices The array containing the device list.

iccid The ICCID of the device.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 121
 Return Value Description

status The device's SIM status. For a list of valid values,

see SIM Status Values on page 29.

ratePlan The name of the rate plan associated with the

device.

communicationPlan The name of the communication plan associated with

the device.

pageNumber An integer specifying the number of the current

response page.

lastPage A true or false value indicating whether the current

response page is the last in the series.

Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic ZHB0cmlhbFVzZXIxOmQ3MDNmNTJiLTEyMDAtNDMxOC1hZTBkLTBmNjA5MmIyZTZhYg=="
"https://restapi1.jasper.com/rws/api/v1/devices?accountId=100020620&modified
Since=2016-04-18T17%3A31%3A34%2B00%3A00&pageSize=50&pageNumber=1"

Response Example

{
"pageNumber": 1,
"devices": [
{
"iccid": "8988216716970004971",
"status": "ACTIVATION_READY",
"ratePlan": "hphlr rp1",
"communicationPlan": "CP_Basic_ON",
},
{
"iccid": "8988216716970004975",
"status": "ACTIVATED",
"ratePlan": "hphlr rp1",
"communicationPlan": "CP_Basic_ON",
}
],
"lastPage": true
}

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 122
 Code Samples
Make sure to use your own URL and user credentials.
Python

import requests
import json
import base64
import pprint

cobrandURL=input("Cobrand URL: ")

url = 'https://'+cobrandURL+'/rws/api/v1/devices/?modifiedSince=2016-04-
18T17%3A31%3A34%2B00%3A00'
myResponse = requests.get(url,auth=(input("username: "),input("api_key: ")))
if(myResponse.ok):
# Loading the response data into a dict variable
# json.loads takes in only binary or string variables so using content
to fetch binary content
# Loads (Load String) takes a Json file and converts into python data
structure (dict or list, depending on JSON)
jData = json.loads(myResponse.content)
pp=pprint.PrettyPrinter(indent=4)
pp.pprint(jData)
else:
# If response code is not ok (200), print the resulting http error
code with description
print("Failure")
myResponse.raise_for_status()

Node.js

var request = require('request');

var body = [];
request.get
('https://restapi1.jasper.com/rws/api/v1/devices/?modifiedSince=2016-04-
18T17%3A31%3A34%2B00%3A00').auth('username', 'password', false)
.on('error', function(error){
console.log('Error:', error);
})
.on('response', function(response) {
console.log(response.statusCode); // return statusCode
console.log(response.headers['content-type']); // return contentType
})
.on('data',function(chunk){
body.push(chunk);
})
.on('end',function(){
body = Buffer.concat(body).toString();
console.log(body);
});

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 123
 Ruby

#!/usr/bin/ruby -w
require 'rest-client'
require 'json'

url = 'https://restapi1.jasper.com/rws/api/v1/devices/?modifiedSince=2016-04-
18T17%3A31%3A34%2B00%3A00'
response = RestClient::Request.execute(
method: :get,
url: url,
user: 'username',
password: 'password',
:headers => {:accept => :json}
)
puts JSON.pretty_generate(JSON.parse(response))

Errors

Error HTTP
Description
Code Code

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000002 400 AccoundId is required.

10000003 400 ModifiedSince is required.

10000004 400 Invalid accountId.

10000005 400 Invalid status.

10000006 400 Invalid pageSize.

10000007 400 Invalid pageNumber.

10000012 400 Invalid date format.

10000024 400 Invalid apiVersion.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 124
 Get Device Details
Description
Returns detailed information about a specified device.

Resource URL
GET BaseURL/v{apiVersion}/devices/{iccid}

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

iccid The ICCID of the device you want information about.

Response Parameters

Return Value Description

iccid The ICCID of the device.

imsi The device IMSI.

msisdn The device MSISDN or phone number.

imei The device IMEI.

status The device SIM status. For a list of valid values, see
SIM Status Values on page 29.

ratePlan The name of the rate plan associated with the device.

communicationPlan The name of the communication plan associated with

the device.

customer The name of the customer (generally an enterprise or

business unit), if any, associated with this device.

endConsumerId The ID of the person, if any, associated with this

device.

dateActivated The date when the device was first activated. See
Date Formats for more details.

dateUpdated The date when the last device information update

occurred. See Date Formats for more details.

dateShipped The date when the device SIM was transferred from
the operator inventory into the enterprise account.
See Date Formats for more details.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 125
 Return Value Description

accountId The ID of the enterprise account associated with the

device.

fixedIPAddress The IPv4 address assigned to the device. This field

may be null if the device communication plan uses
dynamic IP addresses or if the device uses an IPv6
address instead.

fixedIpv6Address The IPv6 address assigned to the device. This field

may be null if the device communication plan uses
dynamic IP addresses or if the device uses an IPv4
address instead.

operatorCustom1-5 Values for any custom device fields the operator has
created in Control Center. This information is
applicable to users with operator roles only.

accountCustom1-10 Values for any custom device fields the enterprise has
created in Control Center. This information is
applicable to users with account roles only.

customerCustom1-5 Values for any custom device fields the customer has
created in Control Center. This information is
applicable to users with customer roles only.

simNotes Information the operator has added about the device.

deviceID Optional identifier that an account or customer can

give to a device.

modemID Identifies the modem used by the device to transmit

data.

globalSIMType For enterprises taking advantage of Control Center's

Global SIM feature, this value indicates whether the
device is using a primary SIM from the lead operator
or a virtual subscription from a partner operator.

Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic ZHB0cmlhbFVzZXIxOmQ3MDNmNTJiLTEyMDAtNDMxOC1hZTBkLTBmNjA5MmIyZTZhYg=="
"https://restapi1.jasper.com/rws/api/v1/devices/8988216716970004975"

Response Example

{
"iccid": "8988216716970004975",
"imsi": "901161697004975",
"msisdn": "882351697004975",

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 126
 "imei": "",
"status": "ACTIVATED",
"ratePlan": "hphlr rp1",
"communicationPlan": "CP_Basic_ON",
"customer": null,
"endConsumerId": null,
"dateActivated": "2016-06-29 00:21:33.339+0000",
"dateAdded": "2014-07-22 23:31:46.571+0000",
"dateUpdated": "2016-07-06 22:04:04.380+0000",
"dateShipped": "2016-06-27 07:00:00.000+0000",
"accountId": "100020620",
"fixedIPAddress": null,
"fixedIpv6Address": null,
"accountCustom1": "78",
"accountCustom2": "",
"accountCustom3": "",
"accountCustom4": "",
"accountCustom5": "",
"accountCustom6": "",
"accountCustom7": "",
"accountCustom8": "",
"accountCustom9": "",
"accountCustom10": "",
"simNotes": null,
"deviceID": null,
"modemID": "2221",
"globalSimType": ""
}

Code Samples
Make sure to use your own URL and user credentials.
Node.js

var request = require('request');

var body = [];
request.get
('https://restapi1.jasper.com/rws/api/v1/devices/8988216716970004975').auth
('username', 'password', false)
.on('error', function(error){
console.log('Error:', error);
})
.on('response', function(response) {
console.log(response.statusCode); // return statusCode
console.log(response.headers['content-type']); // return contentType
})
.on('data',function(chunk){
body.push(chunk);
})
.on('end',function(){
body = Buffer.concat(body).toString();
console.log(body);
});

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 127
 Python

import requests
import json
import base64
import pprint

cobrandURL=input("Cobrand URL: ")

url = 'https://'+cobrandURL+'/rws/api/v1/devices/'+input("iccid: ")
myResponse = requests.get(url,auth=(input("username: "),input("api_key: ")))
# For successful API call, response code will be 200 (OK)
if(myResponse.ok):
# Loading the response data into a dict variable
# json.loads takes in only binary or string variables so using content
to fetch binary content
# Loads (Load String) takes a Json file and converts into python data
structure (dict or list, depending on JSON)
jData = json.loads(myResponse.content)
pp=pprint.PrettyPrinter(indent=4)
pp.pprint(jData)
else:
# If response code is not ok (200), print the resulting http error
code with description
print("Failure")
myResponse.raise_for_status()

Ruby

#!/usr/bin/ruby -w
require 'rest-client'
require 'json'

url = 'https://restapi1.jasper.com/rws/api/v1/devices/89011704252318147060'
response = RestClient::Request.execute(
method: :get,
url: url,
user: 'username',
password: 'password',
:headers => {:accept => :json}
)
puts JSON.pretty_generate(JSON.parse(response))

Errors

Error HTTP
Description
Code Code

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000024 400 Invalid apiVersion.

20000001 404 Resource not found - Invalid ICCID.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 128
 Edit Device Details
Description
Modifies device attributes such as SIM status, rate plan, communication
plan, and custom fields for a specified device.
See the API/Role matrix in the Knowledge Base for a complete list of roles
that can use this API. Be aware that not all roles can edit all fields. To verify
field access for a particular role, log into the web interface as a user with
the same role (who also has web interface access) and open the Edit Device
pop-up (Devices > Device List > ICCID link > Edit button). The user can edit
only the fields that appear in the pop-up.

Resource URL
PUT BaseURL/v{apiVersion}/devices/{iccid}

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

iccid The ICCID of the device you want edit.

effectiveDate (Optional) The date when the change will take effect
(see Date Formats). If you omit this parameter, the
change occurs immediately.

At least one of the following parameters is required

status The device SIM status. For a list of valid values, see
SIM Status Values on page 29.

ratePlan The name of a rate plan.

communicationPlan The name of a communication plan.

customer The name of a customer. Customer users may not

change this value.

deviceID Optional identifier that an account or customer can

give to a device.

modemID A modem ID number.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 129
 Parameter Description

overageLimitOverride Determines the device behavior when it reaches the

data limit defined in the rate plan. Valid values are:
• DEFAULT. The device cannot exceed the data limit.
• TEMPORARY_OVERRIDE. The device can use any
amount of data until the end of the current billing
cycle, at which point Control Center will begin
enforcing the data limit set in the rate plan.
• PERMANENT_OVERRIDE. The device can use any
amount of data, regardless of the data limit
defined in the rate plan.

ipv4Address The IPv4 address assigned to the device. Do not

assign an IP address unless the device
communication plan supports fixed IP addresses. A
device can have both an IPv4 and an IPv6 address
depending on the APNs in the communication plan.
If you assign an IPv4 address value, you must also
provide values for the apn and pdpId parameters.

ipv6Address The IPv6 address assigned to the device. Do not

assign an IP address unless the device
communication plan supports fixed IP addresses. A
device can have both an IPv4 and an IPv6 address
depending on the APNs in the communication plan.
If you assign an IPv6 address value, you must also
provide values for the apn and pdpId parameters.

apn If you change the IPv4 or IPv6 address fields, you

must supply an APN value to identify the IP address.
This value does not change the APN used by the
device.

pdpId If you change the IPv4 or IPv6 address fields, you

must supply a PDP ID value to identify the IP
address. This value does not change the PDP ID used
by the device.

operatorCustom1-5 Custom device fields the operator has created in

Control Center. These fields use the VARCHAR data
type and can be up to 2000 characters in length. Only
operator users can modify these attributes.
If the custom field is a combo box, then the value in
the custom field must be either a blank value or one
of the pre-defined values.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 130
 Parameter Description

accountCustom1-10 Custom device fields the enterprise has created in

Control Center. These fields use the VARCHAR data
type and can be up to 2000 characters in length. Both
operator and account users can modify these
attributes. Be aware that operator users do not have
edit privileges in the web interface.
If the custom field is a combo box, then the value in
the custom field must be either a blank value or one
of the pre-defined values.

customerCustom1-5 Custom device fields the customer has created in

Control Center. These fields use the VARCHAR data
type and can be up to 2000 characters in length. Both
operator and customer users can modify these
attributes. Be aware that operator users do not have
edit privileges in the web interface.
If the custom field is a combo box, then the value in
the custom field must be either a blank value or one
of the pre-defined values.

Response Parameters

Return Value Description

iccid A unique identifier for the device Control Center

updated.

Request Example
Make sure to use your own URL and user credentials.

{curl -X PUT --header "Content-Type: application/json" --header "Accept:

application/json" --header "Authorization: Basic
ZHB0cmlhbFVzZXIxOmQ3MDNmNTJiLTEyMDAtNDMxOC1hZTBkLTBmNjA5MmIyZTZhYg==" -d "{
\"status\": \"DEACTIVATED\"
}" "https://restapi1.jasper.com/rws/api/v1/devices/9088217871987000001"

{curl -X PUT --header "Content-Type: application/json" --header "Accept:

application/json" --header "Authorization: Basic
ZHB0cmlhbFVzZXIxOmQ3MDNmNTJiLTEyMDAtNDMxOC1hZTBkLTBmNjA5MmIyZTZhYg==" -d "{
\"ipv6Address\": \"2003:2002:1001:114a::\",
\"apn\": \"awt-v6-s1\",
\"pdpId\": \"2098\"
}" "https://restapi1.jasper.com/rws/api/v1/devices/9088217871987000001"

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 131
 Response Example
For changes that are effective immediately, this function returns an HTTP
status of 200. For changes that are scheduled in the future, the HTTP status
code is 202.

{
"iccid": "9088217871987000001"
}

Code Samples
Make sure to use your own URL and user credentials.
Ruby

#!/usr/bin/ruby -w
require 'rest-client'
require 'json'

url = 'https://restapi1.jasper.com/rws/api/v1/devices/89011704252318147060'
response = RestClient::Request.execute(
method: :put,
url: url,
user: 'dpSKit20',
password: 'b09c4266-83c6-411a-a475-ca4925b3bb4a',
:payload => '{"accountCustom1":"test acctCustom1: sent by ruby"}',
:headers => {:accept => :json,
:content_type => :json}
)
puts JSON.pretty_generate(JSON.parse(response))

Node.js

var request = require('request');

var body = [];
var auth = "Basic " + new Buffer("username:password").toString("base64");
request({
method: 'PUT',
url: 'https://restapi1.jasper.com/rws/api/v1/devices/8988216716970004975',
headers : {"Authorization" : auth},
body: {"customerCustom1":"CustCustom11111"},
json: true
},
function (error, response, body) {
if(error) {
console.log('Error:', error);
return;
} else {
// return statusCode
console.log(response.statusCode);
// return contentType
console.log(response.headers['content-type']);
console.log(body);
}
}
)

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 132
 Python

#!/usr/local/bin/python3
import requests
import json
import base64
import pprint

cobrandURL=input("Cobrand URL: ")

url = 'https://'+cobrandURL+'/rws/api/v1/devices/'+input("iccid: ")
data = {'customerCustom1':'CustCustom11111'}
myResponse = requests.put(url,auth=(input("username: "),input("api_key:
")),json=data)
# For successful API call, response code will be 200 (OK)
if(myResponse.ok):
# Loading the response data into a dict variable
# json.loads takes in only binary or string variables so using content to
fetch binary content
# Loads (Load String) takes a Json file and converts into Python data
structure (dict or list, depending on JSON)
jData = json.loads(myResponse.content)
pp=pprint.PrettyPrinter(indent=4)
pp.pprint(jData)
else:
# If response code is not ok (200), print the resulting http error code
with description
print("Failure")
myResponse.raise_for_status()

Errors

Error HTTP
Description
Code Code

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000005 400 Invalid status.

10000008 400 Your role does not have access to operator and
customer custom fields.

10000009 400 Your role does not have access to account custom
fields.

10000010 400 Your role does not have access to customer custom
field.

10000011 400 One or more required fields are missing.

10000012 400 Invalid date format.

10000013 404 Invalid ratePlan.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 133
 Error HTTP
Description
Code Code

10000014 400 Invalid communicationPlan.

10000015 400 Invalid customer.

10000016 400 Invalid overageLimitOverride.

10000023 400 The JSON in the request is not well formed. Please
ensure that commas, colons, braces etc. are formatted
properly.

10000024 400 Invalid apiVersion.

10000025 400 Invalid deviceID.

10000026 400 Invalid modemID.

10000028 400 Invalid request.

The request contained one or more unrecognized
parameters.

10000029 400 This SIM may not be moved back to a Pre Activation
status.

10000030 400 Your role does not have access to this API function.

10000031 400 Invalid Zone.

20000001 404 Resource not found - Invalid ICCID.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 134
 Get Device Audit History
Description
For a specified device, returns information about changes that occurred
within a given time period as measured from today's date. You can request
up to a year's worth of data (365 days).

Resource URL
GET BaseURL/v{apiVersion}/devices/{iccid}/auditTrails

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

iccid The ICCID of the device you want information about.

daysOfHistory (Optional) Specifies the audit history time period as

measured from today. You can request up to a year's
worth of data (no more than 365 days). If you do not
specify the number of days, Control Center returns data
from the past 30 days by default.

pageSize (Optional) Specifies the number of records returned in

each response page. The maximum value is 50. The
value defaults to 50. See Pagination on page 27 for
details.

pageNumber (Optional) Specifies the number of response pages to

return. This value defaults to 1. See Pagination on
page 27 for details.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 135
 Response Parameters
The function returns an array of audit history records, with the most recent
listed first.

Return Value Description

iccid The ICCID of the device.

timestamp The time when the audit information was returned.

The date format is yyyy-MM-ddTHH:mm:ss.SSSZ. See
Date Formats for more details.

pageNumber An integer specifying the number of the current page.

See Pagination on page 27 for details.

lastPage A true or false value indicating whether the current

page is the last in the series. See Pagination on
page 27 for details.

deviceAuditTrails An array of change records for the specified device.

Fields within each change record

field The name of the field whose value was changed.

priorValue The previous value of the field. No value indicates that

this is the first time the field was set.

value The current value of the field.

effectiveDate The date and time the change occurred. The date
format is yyyy-MM-ddT HH:mm:ss.SSSZ. See Date
Formats for more details.

status The status of the change. Valid values include: Pending,

Running, Executed, Error, Deleted, Cancelled, and
WaitingRetry.

userName The name of the user who performed the change.

delegatedUser The name of the user, if any, who acted on behalf of

the person who performed the change. This
information will alert you if one user was mirroring
another when the change occurred.

ipAddress The IP address of the machine used by the person who

made the change.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 136
 Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic ZHB0cmlhbFVzZXIxOmQ3MDNmNTJiLTEyMDAtNDMxOC1hZTBkLTBmNjA5MmIyZTZhYg=="
"https://restapi1.jasper.com/rws/api/v1/devices/9901310650450118011/auditTra
ils?daysOfHistory=30&pageSize=50&pageNumber=1"

Response Example

{
"iccid":"9901310650450118011",
"timeStamp":"2016-12-06T15:58:06.466Z",
"pageNumber": 1,
"lastPage": true,
"deviceAuditTrails":[
{
"field":"Usage Limit Reached",
"priorValue":"false",
"value":"false",
"effectiveDate":"2016-12-06T01:34:16.613Z",
"status":"Executed",
"userName":"simUsageManagementUser",
"delegatedUser":"",
"ipAddress":"10.106.232.184"
},
{
"field":"Rate Plan",
"priorValue":"Integration Test -- SP1 Default RP",
"value":"Integration Test -- SP1 PrepaidTerm",
"effectiveDate":"2016-11-11T03:39:06.570Z",
"status":"Executed",
"userName":"businessRuleUser",
"delegatedUser":"",
"ipAddress":"127.0.0.1"
}
]
}

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 137
 Code Samples
Make sure to use your own URL and user credentials.
Python

import requests
import json
import base64
import pprint

cobrandURL=input("Cobrand URL: ")

url = 'https://'+cobrandURL+'/rws/api/v1/devices/'+input("iccid:
")+'/auditTrails'
myResponse = requests.get(url,auth=(input("username: "),input("api_key: ")))
# For successful API call, response code will be 200 (OK)
if(myResponse.ok):
# Loading the response data into a dict variable
# json.loads takes in only binary or string variables so using content
to fetch binary content
# Loads (Load String) takes a Json file and converts into python data
structure (dict or list, depending on JSON)
jData = json.loads(myResponse.content)
pp=pprint.PrettyPrinter(indent=4)
pp.pprint(jData)
else:
# If response code is not ok (200), print the resulting http error
code with description
print("Failure")
myResponse.raise_for_status()

Node.js

var request = require('request');

var body = [];
request.get
('https://restapi1.jasper.com/rws/api/v1/devices/8988216716970004975/auditTr
ails').auth('username', 'password', false)
.on('error', function(error){
console.log('Error:', error);
})
.on('response', function(response) {
console.log(response.statusCode); // return statusCode
console.log(response.headers['content-type']); // return contentType
})
.on('data',function(chunk){
body.push(chunk);
})
.on('end',function(){
body = Buffer.concat(body).toString();
console.log(body);
});

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 138
 Ruby

#!/usr/bin/ruby -w
require 'rest-client'
require 'json'

url =
'https://restapi1.jasper.com/rws/api/v1/devices/89011704252318147060/auditTr
ails'
response = RestClient::Request.execute(
method: :get,
url: url,
user: 'username',
password: 'password',
:headers => {:accept => :json}
)
puts JSON.pretty_generate(JSON.parse(response))

Errors

Error HTTP
Description
Code Code

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000006 400 Invalid pageSize.

10000007 400 Invalid pageNumber.

10000024 400 Invalid apiVersion.

10000049 400 The daysOfHistory must be less than or equal to 365.

20000001 404 Resource not found - Invalid ICCID.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 139
 Get Device Location
Description
Returns location information for a given device during a specified time
period. Control Center collects location details from data session
information via RADIUS accounting records. Control Center does not track
device location information for SMS or voice usage.
The Location Based Services feature must be enabled for the account and
cell ID tracking must be turned on for the device. Only users with the
AccountLBSUser role can perform this function.

Resource URL
GET BaseURL/v{apiVersion}/devices/{iccid}/locationHistory

Request Parameters
Use the fromDate and toDate parameters to define a reporting time period.
The standard pagination parameters (pageSize and pageNumber) allow you
to control the amount of data that is returned.

Parameter Description

apiVersion The version number for this API. The current version for
all functions is 1.

iccid The ICCID for the device whose location history you want
to retrieve.

fromDate (Optional) A date and time indicating the beginning of

the time period you want to report on. If there is no
fromDate, the function returns an array with two
records: the most recent device location and the location
immediately prior to that.
The date format is yyyy-MM-ddTHH:mm:ssZ. For
example, 2018-07-18T17:31:34+00:00.

toDate (Optional) A date and time indicating the end of the time
period you want to report on. If there is no toDate, the
function returns the location history from the date
specified in fromDate to the current date and time. If
there is no fromDate, the function returns an array with
two records: the most recent device location and the
location immediately prior to that.
The date format is yyyy-MM-ddTHH:mm:ssZ. For
example, 2018-07-30T17:31:34+00:00.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 140
 Parameter Description

pageSize (Optional) Specifies the number of records returned in

each response page. The maximum value is 50. The value
defaults to 50. See Pagination on page 27 for more
information.

pageNumber (Optional) Specifies the number of response pages to

return. This value defaults to 1. See Pagination on
page 27 for more information.

Response Parameters
The function returns an array of locations from the specified time period.
All return values are strings unless otherwise specified.

Return Value Description

pageNumber An integer specifying the number of the current page.

simlocations An array of location records. See below for details. If

cell ID tracking is enabled for the device, but no
information is available, this array will be empty. If cell
ID tracking is disabled for the device, Control Center
returns one record with "-1" values for several of the
fields. See the Response Examples below.

lastPage A true or false value indicating whether the current

page is the last in the series.

Parameters in the simLocations array

iccid The ICCID of the device.

dateReceived The date associated with the cell ID. The date format is
yyyy-MM-ddTHH:mm:ssZ. For example, 2018-07-
12T17:31:34+00:00.

cellId The cell ID associated with a data session (from the

Radius accounting record). If cell ID tracking is disabled
for the device, Control Center returns "-1" in this field.
Data type: number.

cellLac The location area code (LAC) associated with the cell ID.
If cell ID tracking is disabled for the device, Control
Center returns "-1" in this field. Data type: number.

servingMcc The mobile country code (MCC) associated with the cell
ID. If cell ID tracking is disabled for the device, Control
Center returns "-1" in this field. Data type: number.

servingMnc The mobile network code (MNC) associated with the cell
ID. If cell ID tracking is disabled for the device, Control
Center returns "-1" in this field. Data type: number.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 141
 Return Value Description

latitude The latitude associated with the cell ID. This field is null
if the operator doesn't upload a cell ID mapping file.
Data type: number (floating point)

longitude The longitude associated with the cell ID. This field is
null if the operator doesn't upload a cell ID mapping file.
Data type: number (floating point)

accuracy Indicates the accuracy of the latitude/longitude values.

This number comes from the cell ID mapping file which
determines the unit of measure. Data type: number.

city The city associated with the cell ID.

state The state associated with the cell ID.

country The country associated with the cell ID.

Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic ZHB0cmlhbFVzZXIxOmQ3MDNmNTJiLTEyMDAtNDMxOC1hZTBkLTBmNjA5MmIyZTZhYg=="
"https://restapi1.jasper.com/rws/api/v1/devices/8988216716970004975/locatio
nHistory?fromDate=2018-07-12T17:31:34+00:00&toDate=2018-07-
18T17:31:34+00:00?pageSize=10&pageNumber=2"

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 142
 Response Example
For a device with cell ID tracking enabled and some available location
information.

{
"pageNumber": 1,
"simLocations": [{
"iccid": "89014103255100000055",
"dateReceived": "2018-07-25T01:13:34+0000",
"cellId": 43761,
"cellLac": 10000,
"servingMcc": 302,
"servingMnc": 720,
"latitude": 37.7749,
"longitude": -122.4194,
"accuracy": 20,
"city": "Boston",
"state": "MA",
"country": "USA"
}, {
"iccid": "89014103255100000055",
"dateReceived": "2018-07-25T01:13:34+0000",
"cellId": 28312832,
"cellLac": 65534,
"servingMcc": 302,
"servingMnc": 220,
"latitude": 42.3601,
"longitude": -71.0589,
"accuracy": 50,
"city": "SF",
"state": "CA",
"country": "USA"
}],
"lastPage": true
}

For a device with cell ID tracking enabled, but no available location

information.

{
"pageNumber": 1,
"simLocations": [],
"lastPage": true
}

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 143
 For a device with cell ID tracking disabled.

{
"simLocations": [{
"iccid": "89014103255100000055",
"dateReceived": "2018-07-25T01:13:34+0000",
"cellId": -1,
"cellLac": -1,
"servingMcc": -1,
"servingMnc": -1,
}],
"pageNumber": 1,
"lastPage": true
}

Errors

Error HTTP
Description
Code Code

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000006 400 Invalid pageSize.

10000007 400 Invalid pageNumber.

10000021 400 Invalid iccid.

10000022 400 FromDate is required.

10000024 400 Invalid apiVersion.

10000027 400 ToDate must be after fromDate.

10000030 400 Your role does not have access to this API function.

10000062 400 Access Denied.

10000079 400 Account does not have access to this API.

20000001 404 Resource not found - Invalid ICCID.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 144
 Get Device Usage
Description
Returns cycle-to-date usage information for a specified device.

Resource URL
GET BaseURL/v{apiVersion}/devices/{iccid}/ctdUsages

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

iccid The ICCID of the device you want information about.

Response Parameters

Return Value Description

iccid The ICCID of the device.

imsi The device IMSI.

msisdn The device MSISDN or phone number.

imei The device IMEI.

status The device SIM status. For a list of valid values, see
SIM Status Values on page 29.

ratePlan The name of the rate plan associated with the

device.

communicationPlan The name of the communication plan associated with

the device.

ctdDataUsage The amount of data used (in bytes) since the

beginning of the billing cycle.

ctdSMSUsage A count of the mobile-originated and mobile-

terminated messages since the beginning of the
billing cycle.

ctdVoiceUsage The number of voice seconds used since the

beginning of the billing cycle.

ctdSessionCount The number of data sessions since the beginning of

the billing cycle.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 145
 Return Value Description

overageLimitReached A true/false value indicating whether the device has

reached the data limit set in the rate plan.

overageLimitOverride Indicates whether the device can exceed the data

limit specified in the rate plan. The possible values
are:
• DEFAULT. The device cannot exceed the data limit.
• TEMPORARY_OVERRIDE. The device can use any
amount of data until the end of the current billing
cycle, at which point Control Center will begin
enforcing the data limit set in the rate plan.
• PERMANENT_OVERRIDE. The device can use any
amount of data, regardless of the data limit
defined in the rate plan.

Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic ZHB0cmlhbFVzZXIxOmQ3MDNmNTJiLTEyMDAtNDMxOC1hZTBkLTBmNjA5MmIyZTZhYg=="
"https://restapi1.jasper.com/rws/api/v1/devices/8988216716970004975/ctdUsage
s"

Response Example

{
"iccid": "8988216716970004975",
"imsi": "901161697004975",
"msisdn": "882351697004975",
"imei": "",
"status": "ACTIVATED",
"ratePlan": "hphlr rp1",
"communicationPlan": "CP_Basic_ON",
"ctdDataUsage": 0,
"ctdSMSUsage": 0,
"ctdVoiceUsage": 0,
"ctdSessionCount": null,
"overageLimitReached": false,
"overageLimitOverride": "DEFAULT"
}

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 146
 Code Samples
Make sure to use your own URL and user credentials.
Python

import requests
import json
import base64
import pprint

cobrandURL=input("Cobrand URL: ")

url = 'https://'+cobrandURL+'/rws/api/v1/devices/'+input("iccid:
")+'/ctdUsages'
myResponse = requests.get(url,auth=(input("username: "),input("api_key: ")))
# For successful API call, response code will be 200 (OK)
if(myResponse.ok):
# Loading the response data into a dict variable
# json.loads takes in only binary or string variables so using content
to fetch binary content
# Loads (Load String) takes a Json file and converts into python data
structure (dict or list, depending on JSON)
jData = json.loads(myResponse.content)
pp=pprint.PrettyPrinter(indent=4)
pp.pprint(jData)
else:
# If response code is not ok (200), print the resulting http error
code with description
print("Failure")
myResponse.raise_for_status()

Node.js

var request = require('request');

var body = [];
request.get
('https://restapi1.jasper.com/rws/api/v1/devices/8988216716970004975/ctdUsag
es').auth('username', 'password', false)
.on('error', function(error){
console.log('Error:', error);
})
.on('response', function(response) {
console.log(response.statusCode); // return statusCode
console.log(response.headers['content-type']); // return contentType
})
.on('data',function(chunk){
body.push(chunk);
})
.on('end',function(){
body = Buffer.concat(body).toString();
console.log(body);
});

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 147
 Ruby

#!/usr/bin/ruby -w
require 'rest-client'
require 'json'

url =
'https://restapi1.jasper.com/rws/api/v1/devices/89011704252318147060/ctdUsag
es'
response = RestClient::Request.execute(
method: :get,
url: url,
user: 'username',
password: 'password',
:headers => {:accept => :json}
)
puts JSON.pretty_generate(JSON.parse(response))

Errors

Error HTTP
Description
Code Code

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000024 400 Invalid apiVersion.

10000031 400 Invalid Zone.

20000001 404 Resource not found - Invalid ICCID.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 148
 Get Device Usage by Zone
Description
For a specified device, returns usage information for a single billing cycle,
broken down by rate plan and zone. You can filter the usage information by
zone and/or rate plan, and specify a particular cycle start date. If no billing
cycle is specified, the API returns usage for the current billing cycle by
default. All usage is pre-invoiced and applies to wholesale rate plans. To
retrieve retail rate plan usage, you must examine the corresponding
wholesale rate plan usage.

Resource URL
GET BaseURL/v{apiVersion}/devices/{iccid}/usageInZone

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

iccid The ICCID of the device you want information about.

cycleStartDate (Optional) The first day of a billing cycle. This date

must correspond to one of the last three billing cycles
(the current billing cycle plus the two preceding cycles).
If there is no date, the function returns usage
information for the current billing cycle only.
The date format is yyyy-MM-ddZ. See Date Formats for
details.

ratePlan (Optional) The name of a rate plan. Use this parameter

to retrieve usage information that's linked to a specific
rate plan. If there's no rate plan listed, the function
returns usage information for any rate plans used by
the device during the specified time period. You can
specify only one rate plan per function call.

zone (Optional) The name of a billing zone. Use this

parameter to track usage for a specific zone. To get
usage information for all zones specified in the rate
plans used by the device, omit this parameter. You can
specify only one zone per function call.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 149
 Response Parameters
The function returns an array of usage records sorted by rate plan and
zone.

Return Value Description

iccid The ICCID of the device.

timestamp The point in time when the usage information was

returned. The date format is yyyy-MM-
ddTHH:mm:ss.SSSZ. See Date Formats for more
details.

cycleStartDate The beginning of the billing cycle associated with

the usage. The date format is yyyy-MM-
ddTHH:mm:ss.SSSZ. See Date Formats for more
details.

cycleEndDate The end of the billing cycle associated with the

usage. The date format is yyyy-MM-
ddTHH:mm:ss.SSSZ. See Date Formats for more
details.

deviceCycleUsageInZones An object containing a list of rate plans used by

the device during the billing cycle.

deviceCycleUsageInZones

Rate Plan Name, Version Each rate plan contains an array of zones where
Number usage occurred. If the device did not use service in
a particular zone, that zone does not appear in the
array. The function returns the rate plan version
number, because in the case of prepaid rate plans
it's possible for a device to use two versions of the
same rate plan during the billing cycle.

ratePlan The name of the rate plan associated with the

device usage.

ratePlanVersion The version number of the rate plan.

zone The name of the zone associated with the device

usage.

dataUsage The amount of data used during the specified time

period.

dataUsageUnit The unit of measure for the data usage. Valid

values include: bytes.

voiceMTUsage The number of mobile-terminated voice seconds

used since the specified start date.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 150
 Return Value Description

voiceMTUsageUnit The unit of measure for the voice MT usage. Valid

values include: seconds.

voiceMOUsage The number of mobile-originated voice seconds

used since the specified start date.

voiceMOUsageUnit The unit of measure for the voice MO usage. Valid

values include: seconds.

SMSmtusage The number of mobile-terminated messages sent

since the specified start date.

SMSmousage The number of mobile-originated messages sent

during the specified time period.

Request Example
Make sure to use your own URL and user credentials.
The first example requests all usage records for a device during the current
billing cycle. See the Response Example for the response.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic ZHB0cmlhbFVzZXIxOmQ3MDNmNTJiLTEyMDAtNDMxOC1hZTBkLTBmNjA5MmIyZTZhYg=="
"https://restapi1.jasper.com/rws/api/v1/devices/8988217755520000031/usageInZ
one"

To get usage for a specific cycle start date:

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic ZHB0cmlhbFVzZXIxOmQ3MDNmNTJiLTEyMDAtNDMxOC1hZTBkLTBmNjA5MmIyZTZhYg=="
"https://restapi1.jasper.com/rws/api/v1/devices/8988217755520000031/usageInZ
one?cycleStartDate=2016-11-10Z"

To get usage for a specific cycle start date, rate plan, and zone:

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic ZHB0cmlhbFVzZXIxOmQ3MDNmNTJiLTEyMDAtNDMxOC1hZTBkLTBmNjA5MmIyZTZhYg=="
"https://restapi1.jasper.com/rws/api/v1/devices/8988217755520000031/usageInZ
one?cycleStartDate=2016-11-10Z&ratePlan=Rate%20Plan%20A&zone=Zone%20B

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 151
 Response Example
The response contains an array of rate plans. Each rate plan contains an
array of usage records. This response matches the first request example.

{
"iccid":"8988217755520000031",
"timeStamp":"2016-11-10T05:31:17.557Z",
"cycleStartDate":"2016-10-31T10:30:00.000Z",
"cycleEndDate":"2016-11-30T10:29:59.000Z",
"deviceCycleUsageInZones":{
"Rate Plan A, 1":[
{
"ratePlan":"Rate Plan A",
"ratePlanVersion":"1",
"zone":"default zone",
"dataUsage":null,
"dataUsageUnit":null,
"voiceMTUsage":null,
"voiceMTUsageUnit":null,
"voiceMOUsage":600,
"voiceMOUsageUnit":"seconds",
"smsmtusage":null,
"smsmousage":null
}
],
"Rate Plan B, 2":[
{
"ratePlan":"Rate Plan B",
"ratePlanVersion":"2",
"zone":"default zone",
"dataUsage":943718,
"dataUsageUnit":"bytes",
"voiceMTUsage":null,
"voiceMTUsageUnit":null,
"voiceMOUsage":943718,
"voiceMOUsageUnit":"seconds",
"smsmtusage":null,
"smsmousage":null
}
]
}
}

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 152
 Code Samples
Make sure to use your own URL and user credentials.
Python

import requests
import json
import base64
import pprint

cobrandURL=input("Cobrand URL: ")

url = 'https://'+cobrandURL+'/rws/api/v1/devices/'+input("iccid:
")+'/usageInZone'
myResponse = requests.get(url,auth=(input("username: "),input("api_key: ")))
# For successful API call, response code will be 200 (OK)
if(myResponse.ok):
# Loading the response data into a dict variable
# json.loads takes in only binary or string variables so using content
to fetch binary content
# Loads (Load String) takes a Json file and converts into python data
structure (dict or list, depending on JSON)
jData = json.loads(myResponse.content)
pp=pprint.PrettyPrinter(indent=4)
pp.pprint(jData)
else:
# If response code is not ok (200), print the resulting http error
code with description
print("Failure")
myResponse.raise_for_status()

Node.js

var request = require('request');

var body = [];
request.get
('https://restapi1.jasper.com/rws/api/v1/devices/8988216716970004975/usageIn
Zone').auth('username', 'password', false)
.on('error', function(error){
console.log('Error:', error);
})
.on('response', function(response) {
console.log(response.statusCode); // return statusCode
console.log(response.headers['content-type']); // return contentType
})
.on('data',function(chunk){
body.push(chunk);
})
.on('end',function(){
body = Buffer.concat(body).toString();
console.log(body);
});

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 153
 Ruby

#!/usr/bin/ruby -w
require 'rest-client'
require 'json'

url =
'https://restapi1.jasper.com/rws/api/v1/devices/89011704252318147060/usageIn
Zone'
response = RestClient::Request.execute(
method: :get,
url: url,
user: 'username',
password: 'password',
:headers => {:accept => :json}
)
puts JSON.pretty_generate(JSON.parse(response))

Errors

Error HTTP
Description
Code Code

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000012 400 Invalid date format.

10000013 404 Invalid ratePlan.

10000024 400 Invalid apiVersion.

10000028 400 Invalid request.

The request contained one or more unrecognized
parameters.

10000031 400 Invalid Zone.

10000032 400 Cycle Start Date should be greater than or equal to

20xx-xx-xx.
The cycleStartDate must specify one of the last three
billing cycles (including the current cycle).

20000001 404 Resource not found - Invalid ICCID.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 154
 Get Session Details
Description
Returns information about the current or most recent data session for a
given device.

Resource URL
GET BaseURL/v{apiVersion}/devices/{iccid}/sessionInfo

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

iccid The ICCID of the device you want information about.

Response Parameters

Return Value Description

iccid The ICCID of the device.

dateSessionStarted The time when the current or most recent data

session began. For a device that has never had a
session, this date is null.

dateSessionEnded The time when the most recent data session ended.
For a device currently in a session, this field is null.
For a device that has never had a session, this date is
null.

ipAddress The IPv4 address used by the device during the

current or most recent session. A session has at least
one IP Address value (ipAddress or ipv6Address) and,
in some cases, may have values for both fields. This
field is always returned, even if the device does not
have an IPv4 address.
For a device that has never been in session, this field
is null.

ipv6Address The IPv6 address used by the device during the

current or most recent session. A session has at least
one IP Address value (ipAddress or ipv6Address) and,
in some cases, may have values for both fields. This
field is returned only when the device has an IPv6
address. The field never has a null value.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 155
 Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic ZHB0cmlhbFVzZXIxOmQ3MDNmNTJiLTEyMDAtNDMxOC1hZTBkLTBmNjA5MmIyZTZhYg=="
"https://restapi1.jasper.com/rws/api/v1/devices/8988216716970004975/sessionI
nfo"

Response Example

{
"iccid": "8988216716970004975",
"ipAddress": "null",
"ipv6Address": "2605:9780:309e::/64",
"dateSessionStarted": "2016-07-06 01:31:46.893+0000",
"dateSessionEnded": "2016-07-06 01:31:46.893+0000"
}

Code Samples
Make sure to use your own URL and user credentials.
Python

import requests
import json
import base64
import pprint

cobrandURL=input("Cobrand URL: ")

url = 'https://'+cobrandURL+'/rws/api/v1/devices/'+input("iccid:
")+'/sessionInfo'
myResponse = requests.get(url,auth=(input("username: "),input("api_key: ")))
# For successful API call, response code will be 200 (OK)
if(myResponse.ok):
# Loading the response data into a dict variable
# json.loads takes in only binary or string variables so using content
to fetch binary content
# Loads (Load String) takes a Json file and converts into python data
structure (dict or list, depending on JSON)
jData = json.loads(myResponse.content)
pp=pprint.PrettyPrinter(indent=4)
pp.pprint(jData)
else:
# If response code is not ok (200), print the resulting http error
code with description
print("Failure")
myResponse.raise_for_status()

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 156
 Node.js

var request = require('request');

var body = [];
request.get
('https://restapi1.jasper.com/rws/api/v1/devices/8988216716970004975/session
Info').auth('username', 'password', false)
.on('error', function(error){
console.log('Error:', error);
})
.on('response', function(response) {
console.log(response.statusCode); // return statusCode
console.log(response.headers['content-type']); // return contentType
})
.on('data',function(chunk){
body.push(chunk);
})
.on('end',function(){
body = Buffer.concat(body).toString();
console.log(body);
});

Ruby

#!/usr/bin/ruby -w
require 'rest-client'
require 'json'

url =
'https://restapi1.jasper.com/rws/api/v1/devices/89011704252318147060/session
Info'
response = RestClient::Request.execute(
method: :get,
url: url,
user: 'username',
password: 'password',
:headers => {:accept => :json}
)
puts JSON.pretty_generate(JSON.parse(response))

Errors

Error HTTP
Description
Code Code

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000024 400 Invalid apiVersion.

10000031 400 Invalid Zone.

20000001 404 Resource not found - Invalid ICCID.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 157
Echo
Echo
Description
Returns any value passed to the function. This information can be useful for
debugging.

Resource URL
GET BaseURL/v{apiVersion}/echo/{param}

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

param The string you want to echo.

Response Parameters

Return Value Description

context The string that you passed into the function.

Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic
RW5nbGlzaFNQQWRtaW5RQTpkOGUwOTdhZi04NWQ0LTQzNDQtYTIwNi0xZWQzOWQ3MTQzNjM="
"https://restapi1.jasper.com/rws/api/v1/echo/hello-world"

Response Example

{
"context": "hello-world"
}

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 158
 Code Samples
Make sure to use your own URL and user credentials.
Python

import requests
import json
import base64

cobrandURL=input("Cobrand URL: ")

params = input("params: ")
url = 'https://'+cobrandURL+'/rws/api/v1/echo/'+params
myResponse = requests.get(url,auth=(input("username: "),input("api_key: ")))
# For successful API call, response code will be 200 (OK)
if(myResponse.ok):
# Loading the response data into a dict variable
# json.loads takes in only binary or string variables so using content
to fetch binary content
# Loads (Load String) takes a Json file and converts into python data
structure (dict or list, depending on JSON)
jData = json.loads(myResponse.content)
print(jData)
print("The response contains {0} properties".format(jData))
print("\n")
for key in jData:
print (key + " : " + jData[key])
else:
# If response code is not ok (200), print the resulting http error
code with description
print("Failure")
myResponse.raise_for_status()

Ruby

#!/usr/bin/ruby -w
require 'rest-client'
require 'json'

url = 'https://restapi1.jasper.com/rws/api/v1/echo/hello%20World'
response = RestClient.get(url)
puts JSON.parse(response)

Node.js

var request = require('request');

var body = [];
request.get
('https://restapi1.jasper.com/rws/api/v1/echo/hello%20world!').auth
('username', 'password', false)
.on('error', function(error){
console.log('Error:', error);
})
.on('response', function(response) {
console.log(response.statusCode); // return statusCode
console.log(response.headers['content-type']); // return contentType
})
.on('data',function(chunk){
body.push(chunk);

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 159
 })
.on('end',function(){
body = Buffer.concat(body).toString();
console.log(body);
});

Errors

Error HTTP
Description
Code Code

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000011 400 One or more required fields are missing.

10000024 400 Invalid apiVersion.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 160
Multi-Party Billing
Get Partner Accounts for Device
Description
Used in Multi-Party Billing , this function returns information about the
partner accounts currently associated with a particular device. To get
information about past associations, you must use the web interface. See
Viewing Partner Accounts for a Device in the Multi-Party Billing section of
the Control Center User Guide.
You must have a ServiceProviderAdmin role to execute this function.

Resource URL
GET BaseURL/v{apiVersion}/devices/{iccid}/partnerAccounts

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

iccid The ICCID of the device you want information about.

Response Parameters

Return Value Description

iccid The ICCID of the device you want information about.

partnerAccounts An array containing information about each partner

account associated with the device. If the device
doesn't have any partner accounts, the function
returns an empty array and a successful HTTP code
(200).

Parameters in the partnerAccounts array

partnerAcctId A Control Center-generated identifier for the account.

partnerAcctName The account name appears throughout Control Center

as an identifier for the account.

associationDate The date and time when the device was assigned to
the partner account. If the device and the account have
been associated more than once, this timestamp
reflects the most recent association.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 161
 Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic
cWFTUEFkbWluUWFBd3RCaWxsT3ByOjI1NThkZjQ5LTNjMjgtNDQyOC04YzBlLTY0NThiN2VjYjM
5Mw=="
"https://restapi1.jasper.com/rws/api/v1/devices/9846897774444000099/partner
Accounts"

Response Example

"iccid": "9846897774444000099",
"partnerAccounts": [
{
"partnerAcctId": 130222403,
"partnerAcctName": "QaAwtBillOprMPBAC001",
"associationDate": "2019-01-31 17:44:16+0000"
},
{
"partnerAcctId": 130222503,
"partnerAcctName": "QaAwtBillOprMPB_AC002",
"associationDate": "2019-02-01 03:05:57+0000"
}
]
}

Errors

Error HTTP
Description
Code Code

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000024 400 Invalid apiVersion.

10000030 400 Your role does not have access to this API function.

10000062 400 Access Denied.

20000001 404 Resource not found - Invalid ICCID.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 162
 Assign Device to Partner Account
Description
Used in Multi-Party Billing , this function assigns a device to a partner
account. As part of the function call, you can also specify a partner rate
plan. The device's enterprise account must have a trust relationship with
the partner account. At the end of the current billing cycle, Control Center
determines whether the device is billable and calculates the subscription
fee and any overage charges.
This function assigns one device to one partner account. To assign multiple
devices to a partner account or a single device to multiple accounts, you
must use several function calls.
You must have a ServiceProviderAdmin role to execute this function.

Resource URL
POST BaseURL/v{apiVersion}/devices/{iccid}/partnerAccounts

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

iccid The ICCID of the device you want to assign to a

partner account.

partnerAcctId An identifier for the partner account.

partnerRatePlanName (Optional) The name of the rate plan Control Center

will use to rate partner services usage. This partner
rate plan must be associated with the partner
account. If you omit this parameter, Control Center
uses the default rate plan for the partner account.

effectiveDate (Optional) This field is not currently supported. If you

do supply a value, the date format is yyyy-MM-ddZ.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 163
 Response Parameters
This function returns an HTTP 202 Accepted code to indicate that the
request is scheduled for processing and the task should be complete within
several seconds.

Return Value Description

iccid The device ICCID.

partnerAcctId The partner account ID.

partnerRatePlanName The name of the partner rate plan.

Request Example
Make sure to use your own URL and user credentials.

curl -X POST --header "Content-Type: application/json" --header "Accept:

application/json" --header "Authorization: Basic
cWFTUEFkbWluUWFBd3RCaWxsT3ByOjI1NThkZjQ5LTNjMjgtNDQyOC04YzBlLTY0NThiN2VjYjM
5Mw==" -d "{
\"partnerAcctId\": 130222403,
\"partnerRatePlanName\": \"QaAwtBillOprMPB_RP003\"
}"
"https://restapi1.jasper.com/rws/api/v1/devices/304689444405000/partnerAcco
unts"

Response Example

{
"iccid": "9846897774444000095",
"partnerAcctId": 130222403,
"partnerRatePlanName": "QaAwtBillOprMPB_RP003"
}

Errors

Error HTTP
Description
Code Code

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000002 400 AccoundId is required.

10000012 400 Invalid date format.

10000013 404 Invalid ratePlan.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 164
 Error HTTP
Description
Code Code

10000023 400 The JSON in the request is not well formed. Please
ensure that commas, colons, braces etc. are formatted
properly.

10000024 400 Invalid apiVersion.

10000030 400 Your role does not have access to this API function.

10000045 400 Invalid date.

10000062 400 Access Denied.

10000074 400 Account is not of Partner Type.

10000075 400 Trust Relationship is not established with Partner

Account.

10000076 400 Trust Relationship is not active.

10000077 400 Device is already assigned to Partner Account.

20000001 404 Resource not found - Invalid ICCID.

20000003 404 Resource not found - Invalid accountId.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 165
 Change Partner Rate Plan for Device
Description
Used in Multi-Party Billing , this function changes the partner rate plan for
a device associated with a particular partner account. You must supply the
name of a different partner rate plan linked to the partner account.
You must have a ServiceProviderAdmin role to execute this function.

Resource URL
PUT BaseURL/v{apiVersion}/devices/{iccid}/partnerAccounts/
{partnerAcctId}

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

iccid The ICCID of the device whose partner rate plan you
want to change.

partnerAcctId An identifier for the partner account.

partnerRatePlanName The name of the partner rate plan you want the
device to start using. This rate plan must be
associated with the specified partner account and the
rate plan must be different from the current partner
rate plan.

Response Parameters

Return Value Description

iccid The ICCID of the device with the changed partner

rate plan.

partnerAcctId The identifier for the partner account associated

with the partner rate plan.

partnerRatePlanName The name of the new partner rate plan associated

with the device.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 166
 Request Example
Make sure to use your own URL and user credentials.

curl -X PUT --header "Content-Type: application/json" --header "Accept:

application/json" --header "Authorization: Basic
cWFTUEFkbWluUWFBd3RCaWxsT3ByOjI1NThkZjQ5LTNjMjgtNDQyOC04YzBlLTY0NThiN2VjYjM
5Mw==" -d "{ \"partnerRatePlanName\": \"QaAwtBillOprMPB_RP005\" }"
"https://restapi1.jasper.com/rws/api/v1/devices/9856897774444002318/partner
Accounts/130307603"

Response Example

{
"iccid": "9856897774444002318",
"partnerAcctId": 130307603,
"partnerRatePlanName": "QaAwtBillOprMPB_RP005"
}

Errors

Error HTTP
Description
Code Code

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000004 400 Invalid accountId.

10000013 404 Invalid ratePlan.

10000024 400 Invalid apiVersion.

10000030 400 Your role does not have access to this API function.

10000045 400 Invalid date.

10000062 400 Access Denied.

10000074 400 Account is not of Partner Type.

10000078 400 Device is not assigned to Partner Account.

20000001 404 Resource not found - Invalid ICCID.

20000003 404 Resource not found - Invalid accountId.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 167
 Remove Device from Partner Account
Description
Used in Multi-Party Billing , this function removes a device from a given
partner account. Control Center charges the full subscription fee at the end
of the billing cycle. There is no proration for subscription fees in the last
billing cycle.
You must have a ServiceProviderAdmin role to execute this function.

Resource URL
DELETE BaseURL/v{apiVersion}/devices/{iccid}/partnerAccounts/
{partnerAcctId}

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

iccid The ICCID of the device you want to remove.

partnerAcctId The identifier for the partner account.

effectiveDate (Optional) This field is not currently supported.

The date and time when the removal takes effect. You
can select a time in the future, but not in the past. The
date format is yyyy-MM-ddZ.

Response Parameters
This function returns an HTTP 202 Accepted code to indicate that the
request is scheduled for processing and the task should be complete within
several seconds.

Return Value Description

iccid The ICCID of the target device.

partnerAcctId The identifier for the target partner account.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 168
 Request Example
Make sure to use your own URL and user credentials.

curl -X DELETE --header "Content-Type: application/json" --header "Accept:

application/json" --header "Authorization: Basic
cWFTUEFkbWluUWFBd3RCaWxsT3ByOjI1NThkZjQ5LTNjMjgtNDQyOC04YzBlLTY0NThiN2VjYjM
5Mw==" -d "{ \"effectiveDate\": \"2019-06-17\" }"
"https://restapi1.jasper.com/rws/api/v1/devices/8988216716970004975"

Response Example

{
"iccid": "9856897774444002318",
"partnerAcctId": 130307603
}

Errors

Error HTTP
Description
Code Code

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000004 400 Invalid accountId.

10000024 400 Invalid apiVersion.

10000030 400 Your role does not have access to this API function.

10000062 400 Access Denied.

10000078 400 Device is not assigned to Partner Account.

20000001 404 Resource not found - Invalid ICCID.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 169
Rate Plans
Get Rate Plans
Description
Get detailed information about a group of rate plans. The user can specify
the rate plans of interest:
l All rate plans (shared and account-specific)
l All shared rate plans
l All rate plans associated with a particular account (including shared
rate plans)

Resource URL
GET BaseURL/v{apiVersion}/ratePlans

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version for
all functions is 1.

accountId (Optional) The ID of the account whose rate plan you

want to retrieve. The response includes account-specific
and shared rate plans. If you do not specify an account,
the response includes all rate plans for the operator.

shared (Optional) If set to true operators can retrieve shared

rate plans across accounts.
The following values are not supported:
l If set to true and accoundId is used, an error occurs.
l A false value is not supported. Rate plans specific to
any account are not returned.

pageSize (Optional) Specifies the number of records returned in

each response page. The maximum value is 50. The
value defaults to 50. See Pagination on page 27.

pageNumber (Optional) Specifies the number of response pages to

return. This value defaults to 1. See Pagination on
page 27.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 170
 Response Parameters

Return Value Description

operatorName The name of the operator associated with the

logged in user.

operatorId The identification number of the operator.

timeStamp The point in time when the usage information was

returned. The date format is yyyy-MM-
ddTHH:mm:ss.SSSZ. See Date Formats for more
details.

pageNumber An integer specifying the number of the current

response page. See Pagination on page 27.

Rate Plans

ratePlans An array of rate plans.

name Descriptive rate plan name. Names are unique

within an operator.

id Identifies a particular rate plan. Control Center

generates this number. Because a rate plan can
have multiple versions, this value might not be
unique. Version ID is the only unique rate plan
identifier.

accountName The name of the account using the rate plan. If the
rate plan is available for multiple accounts to use,
this value is Shared.

versionId Uniquely identifies a particular version of a rate

plan in relation to every other rate plan version in
the system, including different versions of the
same rate plan and different versions of other rate
plans. Because a rate plan may have multiple
active versions at any one time, the versionId, not
the id, is the only truly unique rate plan identifier.

version Specifies the version of the current rate plan. Two

different versions of the same rate plan may
coexist if there are billable devices assigned to
each version (for prepaid plans only). All rate
plans use the same version number sequence (1, 2,
3, and so on).

status The rate plan status is Published . A published plan

has been approved by the operator and is
available for use by devices.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 171
 Return Value Description

type The type refers to the payment method (monthly

vs. prepaid) and included usage type (individual vs.
pooled vs. event).

subscriptionCharge This charge is the monthly subscription fee for

each of the subscribers in the tier. For prepaid
rate plans, the Per Subscriber Charge is a one-
time charge that covers the entire term of the
plan.

numberOfTiers The number of tiers specifies how many

subscription tiers the rate plan has. Each tier can
have different subscription fees, account charges
(for certain plan types), usage allotments, and
overage charges.

tierTreatment If this value is Retroactive, then all subscribers are

charged the rate defined in the highest tier used.
If the value is Incremental, each subscriber is
charged the fee for its own tier. Fixed pool plans
are limited to retroactive tier treatment only.

expireTermBasedOnUsage For prepaid rate plans, if set to true the rate plan
is capped. When the device uses up the included
usage allotment in the first zone, Control Center
shuts down access and ends the subscription term.

lengthOfTerm For prepaid rate plans, length of term is the term

length measured in days or minutes. This field
does not appear for monthly plans or add-on plans,
which are limited to the current billing cycle only.

frequencyOfPer For prepaid fixed pool rate plans, this value

SubscriberCharge specifies how often the per-subscriber fee is
charged: once during the term or at the end of
each month. The subscriber must be active at the
beginning of the month in order for the per
subscriber charge to be charged at month-end.

subscriptionChargeUnit The currency associated with the subscription.

lastPage (Optional) A true or false value indicating whether

the current response page is the last in the series.
See Pagination on page 27.

tiers See the Tiers parameters table below.

dataUsage See the Data Usage parameters table below.

smsUsage See the SMS Usage parameters table below.

voiceUsage See the Voice Usage parameters table below.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 172
 Tiers

Parameter Description

tiers An array of tiers that specify subscription charges.

tierLevel This number identifies the tier level (1 - 5). If the

tierLevel is 0, it indicates that there is one tier only.

subscriberThreshold This number identifies the first subscriber in the tier.

subscriberCapacity This number identifies the last subscriber in the tier.

perSubscriberCharge This charge is the monthly subscription fee for each

of the subscribers in the tier. For prepaid rate plans,
the Per Subscriber Charges is a one-time charge that
covers the entire term of the plan.
For prepaid rate plans, the Per Subscriber Charges is
a one-time charge that covers the entire term of the
plan.

Zones

Parameter Description

zones An array of zones.

reportOverageAsRoaming label.
A list of zone names. Each zone has a value of true or
false that indicates whether or not Control Center
categorizes the usage as roaming on an invoice.

default zone Applies to all the zones list in the

reportOverageAsRoaming.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 173
 Data Usage

Parameter Description

dataUsage Labels of data usage.

useDefaultRating If true, the default rate specified in the default rate

pricing plan is used. If false, the ratings are returned
from the customized data usage values.

usageLimitUnit The data usage limit unit is MB per billing cycle.

Zones

zones The zones associated with the data usage for the
rate plan.

default zone label

All of the parameters associated with the specified
zone.

includedData The included data value specifies the amount of data

a device receives as part of the subscription fee.
This information is not available for fixed-pool plans.

includedDataUnit The included data unit is MB per billing cycle.

This information is not available for fixed-pool plans.

zoneUsageLimitUnit The zone usage limit unit specifies a data usage limit
for each zone in the current billing cycle. The unit is
MB per subscriber.

bulkOverageEnabled Available for postpaid plans only. If set to true, you

can charge for data overage in discrete chunks
rather than charging for overage on a per kilobyte
basis. For example, you might charge a set fee for
every gigabyte of overage. The account would pay
for 1 gigabyte of overage regardless of whether the
device on the rate plan had 4MB of overage or
800MB of overage. Similarly, the account would pay
for two gigabytes of data if the device used between
1 and 2 gigabytes of overage. You can define data
chunks of virtually any size (KB, MB, GB, and TB) for
each zone in the rate plan.

useTheseDataRounding If set to true, the rounding rules apply to all zones. If

SettingsForAllZones set to false, each zone has its own rounding rules.

dataRoundingUnit The data rounding unit determines if Control Center

rounds the amount of data up to the nearest 1KB,
10KB, 50KB or 1 MB before calculating the overage
charges in a particular zone. This return value can
also be None.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 174
 Parameter Description

dataRoundingFrequency The data rounding frequency determines how often

Control Center rounds the data values ― every day,
for each data session, or for each call detail record.
The data rounding frequency values are Per CDR or
Daily.

Tiers

tiers These tiers identify specific overage charges for each

of the subscription tiers.

tierLevel This number identifies the tier level (0 - 5).

subscribersMoreThan The number of subscribers that are more than the

set number.

sharedData For fixed pool plans only. This number specifies the
size of the pool that the devices on the plan can use.

sharedDataUnit The shared data unit is MB.

subscribersUpTo These numbers define a range of subscribers for the

tier:
l subscriberMoreThan. This number identifies the
first subscriber in the tier.
l SubscribersUpTo. This number identifies the last
subscriber in the tier.

dataOverage This number specifies the cost of each kilobyte of

data used by the subscriber over the included
amount specified in the includedData parameter. If
the plan is pooled and there is surplus usage
available, a single subscriber may exceed the
individual usage allotment without being charged for
overage. These numbers are per KB, not per MB. If a
default rating is used, Control Center will supply the
data overage charge from the default pricing rate
plan.

dataOverageUnit The data overage unit is per KB.

SMS Usage

Parameter Description

smsUsage The SMS usage for the rate plan.

type The type of SMS usage: Subscription Tiers or

Destination Based Rating.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 175
 Parameter Description

useDefaultRating If true, Control Center supplies the SMS usage from

the default rate plan.

moAndMtRating Available for rate plans with tier-based SMS rating

only. This parameter specifies whether SMS MO and
SMS MT messages are rated together (Rate Both
Together) or separately (Rate MO Only or Rate MT
Only).

poolSMSUsage Available for rate plans with destination-based SMS

rating only. If true, the rate plan pools SMS usage for
all the subscribers using this rate plan.

poolSMSMOUsage The SMS MO is rated separately. If true, the plan

pools the SMS MO usage.

poolSMSMTUsage The SMS MT is rated separately. If true, the plan

pools the SMS MT usage.

smsMOOverage The amount of SMS MO overage charge.

smsMOOverageUnit The SMS MO overage unit is per msg.

smsMTOverage The amount of SMS MT overage charge.

smsMTOverageUnit The SMS MT overage unit is per msg.

Zones

zones The zones associated with the data usage for the rate
plan.

default zone label

All of the parameters associated with the specified
zone.

includedSMS The included SMS value (SMS MT or SMS MO)

specifies the amount of text messages a device
receives as part of the subscription fee.
This information is not available for fixed-pool plans.

includedSMSUnit The included SMS unit (SMS MT or SMS MO) is smgs.

This information is not available for fixed-pool plans.

Tiers

tierLevel This number identifies the tier level (1 - 5). If no tiers

are used, the value is 0.

subscribersMoreThan The number of subscribers that are more than the set
number.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 176
 Parameter Description

subscribersUpTo These numbers define a range of subscribers for the

tier:
l subscriberMoreThan. This number identifies the
first subscriber in the tier.
l SubscribersUpTo. This number identifies the last
subscriber in the tier.

sharedSMS For fixed pool rate plans only. This number specifies
the size of the pool that the devices on the plan can
use. If mobile-terminated (SMS MT) and mobile-
originated (SMS MO) messages are rated separately,
two values display.

sharedSMSUnit The shared SMS unit is msgs.

sharedSMSMT For fixed pool rate plans only. This number specifies
the size of the pool that the devices on the plan can
use for rated mobile-terminated SMS (SMS MT).

sharedSMSMTUnit The shared SMS MT unit is per MT msg.

sharedSMSMO For fixed pool rate plans only. This number specifies
the size of the pool that the devices on the plan can
use for rated mobile-originated SMS (SMS MO).

sharedSMSMOUnit The shared SMS MO unit is per MO msg.

SMSOverage This number specifies the cost of each message used

by the subscriber in excess of the number specified in
the IncludedSMS field. If the moAndMtRating
messages are rated separately, two values display.

SMSOverageUnit The data overage unit is per msg.

Voice Usage

Parameter Description

voiceUsage The voice usage for the rate plan.

useDefaultRating If true, Control Center supplies the voice usage from

the default rate plan.

poolVoiceUsage Available for rate plans with destination-based voice

rating. If true, the rate plan pools voice usage for all
the subscribers using this rate plan. This parameter
applies to rate plans with tier-based voice rate plans
only.

poolVoiceMTUsage The voice MT is rated separately. If true, the plan

rates pools voice MT usage.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 177
 Parameter Description

poolVoiceMOUsage The voice MO is rated separately. If true, the plan

rates pools voice MO usage.

sharedVoice For fixed pool rate plans only. This number specifies
the size of the pool that the devices on the plan can
use. If mobile-terminated (voice MT) and mobile-
originated (voice MO) calls are rated separately,
there are be two fields.

sharedVoiceUnit The shared voice unit is per min.

sharedVoiceMT For fixed pool rate plans only. This number specifies
the size of the pool that the devices on the plan can
use for rated mobile-terminated voice (voice MT).

sharedVoiceMTUnit The shared voice MT unit is per MT min.

sharedVoiceMO For fixed pool rate plans only. This number specifies
the size of the pool that the devices on the plan can
use for rated mobile-originated voice (voice MO).

sharedVoiceMOUnit The shared voice MO unit is per MO min.

voiceMOOverage The amount of voice MO overage.

voiceMOOverageUnit The voice MO overage unit is per Mo min.

voiceMTOverage This amount of voice MT overage.

voiceMTOverageUnit The voice MT overage unit is per MT min.

Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic
TDEwblNQQWRtaW5NaXhlZDplYmJiMmY4NC0wNTZkLTQyYjYtYWY1OS02YWE1Nzk4NTUzMTA=
"
"https://restapi1.jasper.com/rws/api/v1/rateplans?pageSize=50&pageNumber=1"

Response Example

{
"operatorName": "Jasper Systems",
"operatorId": 8410,
"timeStamp": "2019-03-15T18:02:25.013Z",
"pageNumber": 1,
"ratePlans": [
{
"name": "QaAwtRP-180421030819",
"id": 30884203,
"accountName": "Shared",
"versionId": 30885703,
"version": 1,

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 178
 "status": "Published",
"type": "Monthly - Individual Subscriber",
"subscriptionCharge": 0,
"numberOfTiers": 1,
"tierTreatment": "Incremental",
"tiers": [
{
"tierLevel": 0,
"subscriberThreshold": 0,
"subscriberCapacity": "And Up",
"perSubscriberCharge": 0
}
],
"expireTermBasedOnUsage": false,
"lengthOfTerm": 0,
"subscriptionChargeUnit": "USD",
"zones":
{
"reportOverageAsRoaming":
{
"default zone": "false"
}
},
"dataUsage":
{
"useDefaultRating": false,
"usageLimitUnit": "MB per cycle",
"zones":
{
"default zone":
{
"includedData": 0,
"includedDataUnit": "MB",
"zoneUsageLimitUnit": "MB per subscriber",
"bulkOverageEnabled": false,
"useTheseDataRoundingSettingsForAllZones": true,
"dataRoundingUnit": "None",
"dataRoundingFrequency": "Per CDR",
"tiers": [
{
"tierLevel": 0,
"subscribersMoreThan": 0,
"subscribersUpTo": "And Up",
"sharedData":0,
"sharedDataUnit":"MB",
"dataOverage": 0,
"dataOverageUnit": "per KB"
}
]
}
}
},
"smsUsage":
{
"useDefaultRating": false,
"type": "Subscription Tiers",
"moAndMtRating": "Rate Both Together",
"poolSMSUsage": false,
"poolSMSMOUsage": false,

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 179
 "poolSMSMTUsage": false,
"zones":
{
"default zone":
{
"includedSMS": 0,
"includedSMSUnit": "msgs",
"tiers": [
{
"tierLevel": 0,
"subscribersMoreThan": 0,
"subscribersUpTo": "And Up",
"sharedSMS":0
"sharedSMSUnit":"msgs",
"smsOverage": 0,
"smsOverageUnit": "per msg"
}
]
}
}
},
"voiceUsage":
{
"useDefaultRating": true,
"poolVoiceUsage": false,
"poolVoiceMTUsage": false,
"poolVoiceMOUsage": false,
"voiceMOOverage": 0,
"voiceMOOverageUnit": "per MO min",
"voiceMTOverage": 0,
"voiceMTOverageUnit": "per MT min"
}
},
],
"lastPage": true
}

Code Samples
Make sure to use your own URL and user credentials.
Node.js

var request = require('request');

var body = [];
request.get('https://restapi1.jasper.com/rws/api/v1/rateplans?accountId=acct_
id&pageSize=page_size&pageNumber=page_number').auth('user_name', 'password',
false)
.on('error', function(error){
console.log('Error:', error);
})
.on('response', function(response) {
console.log(response.statusCode); // return statusCode
console.log(response.headers['content-type']); // return contentType
})
.on('data',function(chunk){
body.push(chunk);
})
.on('end',function(){
body = Buffer.concat(body).toString();

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 180
 console.log(body);
});

Python

import requests
import json
import base64
import pprint

apiUrl= 'https://restapi1.jasper.com/rws/api/v1/rateplans'

parameters= {'accountId':"acct_id", 'pageSize': "page_size", 'pageNumber':

"page_number"}

myResponse = requests.get(url=apiUrl, auth=(raw_input("username: "),raw_input

("api_key: ")), params=parameters)
# For successful API call, response code will be 200 (OK)
if(myResponse.ok):
# Loading the response data into a dict variable
# json.loads takes in only binary or string variables so using content to
fetch binary content
# Loads (Load String) takes a Json file and converts into python data
structure (dict or list, depending on JSON)
pp = pprint.PrettyPrinter(indent=4)
jData = json.loads(myResponse.content)
pp.pprint(jData)
else:
# If response code is not ok (200), print the resulting http error code with
description
myResponse.raise_for_status()

Ruby

#!/usr/bin/ruby -w
require 'rest-client'
require 'json'

url = 'https://restapi1.jasper.com/rws/api/v1/rateplans?accountId=acct_
id&pageSize=page_size&pageNumber=page_number'
response = RestClient::Request.execute(
method: :get,
url: url,
user: 'user_name',
password: 'password',
:headers => {:accept => :json}
)
puts JSON.pretty_generate(JSON.parse(response))

Errors

Error Code HTTP Code Description

10000004 400 Invalid accountId.

10000006 400 Invalid pageSize.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 181
 Error Code HTTP Code Description

10000007 400 Invalid pageNumber.

10000024 400 Invalid apiVersion.

10000436 400 Shared can only be true.

10000437 400 Shared can not be used along with accountId.

20000000 404 Requested resource not found.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 182
SMS Messages
Search SMS
Description
Returns a list of SMS message IDs associated with a particular account
during a specified time period. Optionally, you can restrict the search to a
specific device.
The function returns messages between Control Center and a device. You
cannot get information about messages exchanged between a device and a
non-Control Center SMS client.

Resource URL
GET BaseURL/v{apiVersion}/smsMessages

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version for
all functions is 1.

accountId (Optional) Unique identifier for the account associated

with the messages you want to retrieve.

iccid (Optional) Restricts the list of returned messages to just

those messages sent or received by a particular device.
This device must be owned by the specified account.

fromDate A date and time using the ISO 8601 format (see Date
Formats). The function returns any messages that were
sent or received on or after this date.

toDate (Optional) A date and time using the ISO 8601 format
(see Date Formats). Use this parameter to specify a
particular period of time for the messages. If you do not
specify a toDate, Control Center returns all messages up
to the current date and time.

pageSize (Optional) Specifies the number of records returned in

each response page. The maximum value is 50. The
value defaults to 50.

pageNumber (Optional) Specifies the number of response pages to

return. This value defaults to 1.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 183
 Response Parameters
The function returns an array of SMS message IDs. Records are sorted by
modification date in ascending order with the oldest message listed first.

Return Value Description

smsMsgIds An array of message identifiers. You must use the Get

SMS Details API to retrieve the content of each
message.

pageNumber An integer specifying the number of the current page.

lastPage A true or false value indicating whether the current

page is the last in the series.

Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic ZHB0cmlhbFVzZXIxOmQ3MDNmNTJiLTEyMDAtNDMxOC1hZTBkLTBmNjA5MmIyZTZhYg=="
"https://restapi1.jasper.com/rws/api/v1/smsMessages"

Response Example

{
"smsMsgIds": [
106184,
105025
],
"pageNumber": 1,
"lastPage": true
}

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 184
 Code Samples
Make sure to use your own URL and user credentials.
Python

import requests
import json
import base64
import pprint

cobrandURL=input("Cobrand URL: ")

url = 'https://'+input("Cobrand URL: ")+'/rws/api/v1/smsMessages?accountId='
+input("Account ID: ")+'&fromDate=2016-04-
18T17%3A31%3A34%2B00%3A00&pageSize=50&pageNumber=1'
myResponse = requests.get(url,auth=(input("username: "),input("api_key: ")))
# For successful API call, response code will be 200 (OK)
if(myResponse.ok):
# Loading the response data into a dict variable
# json.loads takes in only binary or string variables so using content
to fetch binary content
# Loads (Load String) takes a Json file and converts into python data
structure (dict or list, depending on JSON)
jData = json.loads(myResponse.content)
pp=pprint.PrettyPrinter(indent=4)
pp.pprint(jData)
else:
# If response code is not ok (200), print the resulting http error
code with description
print("Failure")
myResponse.raise_for_status()

Node.js

var request = require('request');

var body = [];
request.get
('https://restapi1.jasper.com/rws/api/v1/devices/smsMessages?accountId=14706
0908&fromDate=2016-04-
18T17%3A31%3A34%2B00%3A00&pageSize=50&pageNumber=1').auth('username',
'password', false)
.on('error', function(error){
console.log('Error:', error);
})
.on('response', function(response) {
console.log(response.statusCode); // return statusCode
console.log(response.headers['content-type']); // return contentType
})
.on('data',function(chunk){
body.push(chunk);
})
.on('end',function(){
body = Buffer.concat(body).toString();
console.log(body);
});

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 185
 Ruby

#!/usr/bin/ruby -w
require 'rest-client'
require 'json'

url =
'https://restapi1.jasper.com/rws/api/v1/smsMessages?accountId=147060908&from
Date=2016-04-18T17%3A31%3A34%2B00%3A00&pageSize=50&pageNumber=1'
response = RestClient::Request.execute(
method: :get,
url: url,
user: 'username',
password: 'password',
:headers => {:accept => :json}
)
puts JSON.pretty_generate(JSON.parse(response))

Errors

Error HTTP
Description
Code Code

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000002 400 AccoundId is required.

10000004 400 Invalid accountId.

10000006 400 Invalid pageSize.

10000007 400 Invalid pageNumber.

10000012 400 Invalid date format.

10000021 400 Invalid iccid.

10000022 400 FromDate is required.

10000024 400 Invalid apiVersion.

10000027 400 ToDate must be after fromDate.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 186
 Get SMS Details
Description
Returns detailed information about a particular SMS message sent by
Control Center to a device or sent by a device to Control Center. You cannot
get information about messages exchanged between a device and a non-
Control Center SMS client.

Resource URL
GET BaseURL/v{apiVersion}/smsMessages/{smsMsgId}

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

smsMsgId A unique identifier for the SMS message you want to

retrieve.

messageEncoding (Optional) The type of message encoding used. Valid

values are: LITERAL (default) or BASE64.

Response Parameters

Return Value Description

smsMsgId A unique identifier for the SMS message.

status The message delivery status. Valid values depend on

the message type.
l Mobile-Originated (MO): Received
l Mobile-Terminated (MT): Cancelled, CancelFailed,
CancelPending, Delivered, Pending, Failed, Unknown.

messageText The content of the SMS message.

senderLogin Identifies the message sender. For mobile-originated

messages, this value is Mobile Device. For mobile-
terminated messages, the value is the Control Center
user name.

sentTo Identifies the recipient of the message. If the recipient

is Control Center, the value is Server. Otherwise, the
recipient device’s MSISDN, the equivalent of a phone
number, appears.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 187
 Return Value Description

sentFrom Identifies the device or computer that sent the message.

If the sender is Control Center, the value is Server.
Otherwise, the sending device’s MSISDN, the equivalent
of a phone number, appears.

msgType Message Type indicates whether the message was sent

by the device (MO, mobile-originated) or received by
the device (MT, mobile-terminated).

dateSent The date and time (including the time zone) when the
message was sent. See Date Formats.

dateReceived The date and time (including the time zone) when
Control Center received the message. See Date Formats.

dateModified The date and time (including the time zone) when the
delivery status changed. See Date Formats.

Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic ZHB0cmlhbFVzZXIxOmQ3MDNmNTJiLTEyMDAtNDMxOC1hZTBkLTBmNjA5MmIyZTZhYg=="
"https://restapi1.jasper.com/rws/api/v1/smsMessages/106184"

Response Example

{
"smsMsgId": 106184,
"status": "Pending",
"messageText": "Hello world",
"senderLogin": "dpTrialUser2",
"iccid": "8988216716970004975",
"sentTo": "882351697004975",
"sentFrom": "Server",
"msgType": "MT",
"dateSent": "2016-07-06 16:05:16.280-0700",
"dateModified": "2016-07-06 16:05:16.522-0700"
}

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 188
 Code Samples
Make sure to use your own URL and user credentials.
Python

import requests
import json
import base64
import pprint

cobrandURL=input("Cobrand URL: ")

url = 'https://'+input("Cobrand URL: ")+'/rws/api/v1/smsMessages/'+input("SMS
Message ID: ")
myResponse = requests.get(url,auth=(input("username: "),input("api_key: ")))
# For successful API call, response code will be 200 (OK)
if(myResponse.ok):
# Loading the response data into a dict variable
# json.loads takes in only binary or string variables so using content
to fetch binary content
# Loads (Load String) takes a Json file and converts into python data
structure (dict or list, depending on JSON)
jData = json.loads(myResponse.content)
pp=pprint.PrettyPrinter(indent=4)
pp.pprint(jData)
else:
# If response code is not ok (200), print the resulting http error
code with description
print("Failure")
myResponse.raise_for_status()

Node.js

var request = require('request');

var body = [];
request.get
('https://restapi1.jasper.com/rws/api/v1/smsMessages/23178931802').auth
('username', 'password', false)
.on('error', function(error){
console.log('Error:', error);
})
.on('response', function(response) {
console.log(response.statusCode); // return statusCode
console.log(response.headers['content-type']); // return contentType
})
.on('data',function(chunk){
body.push(chunk);
})
.on('end',function(){
body = Buffer.concat(body).toString();
console.log(body);
});

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 189
 Ruby

#!/usr/bin/ruby -w
require 'rest-client'
require 'json'

url = 'https://restapi1.jasper.com/rws/api/v1/smsMessages/25830319302'
response = RestClient::Request.execute(
method: :get,
url: url,
user: 'username',
password: 'password',
:headers => {:accept => :json}
)
puts JSON.pretty_generate(JSON.parse(response))

Errors

Error HTTP
Description
Code Code

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000017 400 Invalid messageEncoding.

10000024 400 Invalid apiVersion.

20000002 404 Resource not found - Invalid smsMsgId.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 190
 Send SMS
Description
Sends an SMS message to a given device or short code.
This function is available to users with the following roles:
ServiceProviderAdmin, ServiceProviderDemo, AccountAdmin,
AccountAPIOnly, TrialUser, AccountDemo, and CustomerAdmin.

Resource URL
POST BaseURL/v{apiVersion}/devices/{iccid}/smsMessages

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

iccid The ICCID of the device you want information about.

messageText The SMS message text. The maximum length of the

message depends on the data coding type (see
dataCoding).
l 0 - 160 characters
l 1 - 160 characters
l 3 - 160 characters
l 4 - 140 characters
l 8 - 70 characters

messageEncoding (Optional) The type of message encoding used. Valid

values are: LITERAL (default) or BASE64.

dataCoding (Optional) The type of data encoding used.

l 0 - SMSC default alphabet; often GSM encoding
l 1 - IA5/ASCII, but sometimes GSM encoding,
depending on the SMSC implementation
l 3 - Latin 1 (ISO-8859-1)
l 4 - Binary SMS
l 8 - Unicode UCS2

tpvp (Optional) The length of time the message is available

before expiring. For more information about setting
this value, see Validity Period.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 191
 Response Parameters

Return Value Description

smsMsgId A unique identifier for the SMS message. You can use
this ID to get details about a particular message with
the Get SMS Details API.

Request Example
Make sure to use your own URL and user credentials.

curl -X POST --header "Content-Type: application/json" --header "Accept:

application/json" --header "Authorization: Basic
ZHB0cmlhbFVzZXIxOmQ3MDNmNTJiLTEyMDAtNDMxOC1hZTBkLTBmNjA5MmIyZTZhYg==" -d "{
\"messageText\": \"Hello world\"
}"
"https://restapi1.jasper.com/rws/api/v1/devices/89302720396916018117/smsMess
ages"

Response Example

{
"smsMsgId": 106184
}

Code Samples
Make sure to use your own URL and user credentials.
Node.js

var request = require('request');

var body = [];
var auth = "Basic " + new Buffer("username:password").toString("base64");
request.post({
url:
'https://restapi1.jasper.com/rws/api/v1/devices/8988216716970004975/smsMessa
ges',
headers : {"Authorization" : auth},
body: {"messageText": "Test"},
json: true
},
function(error, response, body) {
if(error) {
console.log('Error:', error);
return;
} else {
// return statusCode
console.log(response.statusCode);
// return contentType
console.log(response.headers['content-type']);
console.log(body);
}
}
)

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 192
 Ruby

#!/usr/bin/ruby -w
require 'rest-client'
require 'json'

url =
'https://restapi1.jasper.com/rws/api/v1/devices/89011704252318147060/smsMess
ages'
response = RestClient::Request.execute(
method: :post,
url: url,
user: 'dpSKit20',
password: 'b09c4266-83c6-411a-a475-ca4925b3bb4a',
:payload => '{"messageText":"testing from minde: sent by ruby"}',
:headers => {:accept => :json,
:content_type => :json}
)
puts JSON.pretty_generate(JSON.parse(response))

Errors

Error HTTP
Description
Code Code

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000017 400 Invalid messageEncoding.

10000018 400 Invalid dataCoding.

10000019 400 Invalid tpvp.

The validityPeriod is invalid.

10000020 400 Message length exceeds the maximum permissible

length.

10000023 400 The JSON in the request is not well formed. Please
ensure that commas, colons, braces etc. are formatted
properly.

10000024 400 Invalid apiVersion.

10000028 400 Invalid request.

The request contained one or more unrecognized
parameters.

10000030 400 Your role does not have access to this API function.

10000031 400 Invalid Zone.

20000001 404 Resource not found - Invalid ICCID.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 193
 Error HTTP
Description
Code Code

30000001 500 Unknown server error.

30000002 500 Control Center failed to submit the message to the

SMSC.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 194
Usages
Get Usage by Rate Plan
Description
Returns usage information associated with a single rate plan during a
specified billing cycle. By default, the function returns cycle-to-date data,
SMS, and voice usage for all devices using the current version of the rate
plan. However, you can request a particular usage type, a past billing cycle,
or a different rate plan version.

No Support for Shared or Unpublished Rate Plans. Be aware that you

cannot request usage information for a shared rate plan. In addition, rate
plans must be published.

This function is available for service providers, accounts, and customers. A

user can request usage information about rate plans associated with
accounts they have access to. Customer users can view usage for their own
devices, but not for devices in the same account, using the same rate plan,
that are owned by a different customer.
See the API/Role matrix in the Knowledge Base for a complete list of roles
that can use this API.

Resource URL
GET BaseURL/v{apiVersion}/usages

Request Parameters
The rate plan name and API version number are required. All other
parameters are optional.

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

ratePlanName The name of the desired rate plan.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 195
 Parameter Description

cycleStartDate (Optional) The start date of a desired billing cycle. The

format is yyyy-MM-dd. The function returns cycle-to-
date usage information if this parameter is not used.
You can get the cycle start day for an account using the
Get Account Billing Settings API
(currentBillingCycleStart response parameter). Or, in
the web interface, see the Billing Settings (Admin >
Accounts > Account ID link > Billing Settings subtab >
Current Billing Cycle Start).

usageType (Optional) The type of usage information the function

should return. Options are: DATA, SMS, and VOICE. You
can specify only one type. However, the function returns
all types of usage information if this parameter is not
present.

ratePlanVersion (Optional) The desired rate plan version. It's possible

for two versions of the same rate plan to be active
during the same billing cycle. This parameter allows
you to specify which version you want to use. The
function returns information for the most recent version
of the rate plan if this parameter is not present.

pageNumber (Optional) Specifies the number of response pages to

return. This value defaults to 1. See Pagination on
page 27.

pageSize (Optional) Specifies the number of records returned in

each response page. The maximum value is 50. The
value defaults to 50. See Pagination on page 27.

Response Parameters
The function returns an array of zones, where each zone contains an array
of devices. For each device, there are total usage numbers for the requested
usage types. A device may have usage in more than one zone and, as a
result, may appear multiple times in the response.

Return Value Description

accountId The ID of the account using the rate plan.

accountName The name of the account using the rate plan.

ratePlanName The name of the rate plan.

ratePlanVersion The version of the rate plan.

pageNumber An integer specifying the number of the current

response page.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 196
 Return Value Description

lastPage A true or false value indicating whether the current

response page is the last in the series.

Zones

zones An array of zones used in the rate plan.

zone The name of a zone.

Devices

devices An array of devices that used network services in the

zone. The following information is returned for each
device.

deviceId The ICCID for the device. This field does not contain the
Device ID found on the Device Details page. The ICCID
is a unique identifier for a device in Control Center.
Device ID is an optional identifier that the account or
customer can give to each device.

usage A label that indicates the usage fields for the current
device. The function returns all usage information
unless you specify a particular usage type. If you
request one type of usage, the function returns all
usage fields, but inserts zero values in the non-
requested usage fields, regardless of the actual values.

dataUsage The volume of data (in bytes) used by the device during
the time period (cycle to date or a particular billing
cycle). If you request a different usage type, the value
in this field will be zero, regardless of the actual value.

smsMOUsage The number of messages sent by the device during the

time period (cycle to date or a particular billing cycle).
If you request a different usage type, the value in this
field will be zero, regardless of the actual value.

smsMTUsage The number of messages received by the device during

the time period (cycle to date or a particular billing
cycle). If you request a different usage type, the value
in this field will be zero, regardless of the actual value.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 197
 Return Value Description

voiceMOUsage The number of seconds a device used for outbound calls

during the time period (cycle to date or a particular
billing cycle). If you request a different usage type, the
value in this field will be zero, regardless of the actual
value.

voiceMTUsage The number of seconds a device used for inbound calls

during the time period (cycle to date or a particular
billing cycle). If you request a different usage type, the
value in this field will be zero, regardless of the actual
value.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 198
 Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic
TDEwblNQQWRtaW5NaXhlZDplYmJiMmY4NC0wNTZkLTQyYjYtYWY1OS02YWE1Nzk4NTUzMTA="htt
ps://restapi1.jasper.com/rws/api/v1/usages?ratePlan=Monthly-Flexible-
Pool&pageNumber=1&pageSize=50"

Response Example

{
"accountId": 100477039,
"accountName": "Acme Corp",
"ratePlanName": "Monthly-Flexible-Pool",
"ratePlanVersion": 1,
"zones": [
{
"zone": "Zone A",
"devices": [
{
"deviceId": "8988209000000000723",
"usage": {
"dataUsage": 54765,
"smsMOUsage": 37,
"smsMTUsage": 42,
"voiceMOUsage": 0,
"voiceMTUsage": 0
}
},
{
"deviceId": "8988209000000000747",
"usage": {
"dataUsage": 23456,
"smsMOUsage": 15,
"smsMTUsage": 11,
"voiceMOUsage": 0,
"voiceMTUsage": 0
}
}
]
"zone": "Zone B",
"devices": [
{
"deviceId": "8988209000000000859",
"usage": {
"dataUsage": 94480,
"smsMOUsage": 0,
"smsMTUsage": 0,
"voiceMOUsage": 900,
"voiceMTUsage": 0
}
}
]
}
]
"pageNumber": 2,

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 199
 "lastPage": true
}

Errors

Error HTTP
Description
Code Code

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000006 400 Invalid pageSize.

10000007 400 Invalid pageNumber.

10000012 400 Invalid date format.

10000013 404 Invalid ratePlan.

10000024 400 Invalid apiVersion.

10000030 400 Your role does not have access to this API function.

10000062 400 Access Denied.

10000441 400 Invalid RatePlan Version.

10000442 400 More than one RatePlan having the same name.
The rate plan name is not unique. Try using the rate
plan version number along with the name to indicate
a unique rate plan.

10000443 400 Invalid BillingCycleStart.

The billing cycle start date doesn't correspond to a
valid billing cycle.

20000058 400 Requested resource not available for Shared Rate

plan.
You cannot use shared rate plans in this function.

30000001 500 Unknown server error.

30000003 400 Invalid Usage Type.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 200
Users
Get User Details
Description
Returns the user details for a given user ID. All users can request their own
user details. Account administrators can view details for all account and
customer users in their account. Service provider administrators can view
details for all operator, account, and customer users. Other roles may have
access to user information as well. See the API/Role matrix in the
Knowledge Base for a complete list of roles that can use this API.

Resource URL
GET BaseURL/v{apiVersion}/users/{userId}

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version for
all functions is 1.

userId The ID of the user for which you want information. The
user ID is not available in the Control Center web
interface, but you can use the Get All User Details API to
find a user ID. Use a partial response to return the
username and userId only. For more information, see
Partial Response Guidelines.

Response Parameters

Return Value Description

username A unique identifier for the person within Control

Center. A user must supply this user name and a
password to log into Control Center. The user name is
unique across all accounts in Control Center.

userId A unique identifier for the user.

accountName The name of the account to which the user is assigned.

accountId A Control Center-generated identifier for the account.

operatorName The name of the service provider.

operatorId A unique identifier for the service provider.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 201
 Return Value Description

roleName The role name defines the application privileges for

the user. See User Role Values on page 31 for a list of
possible values.

status The user status valid values include:

l Active. The user is active in the system.
l Deactivated. The user hasn't reset their password
within the given time frame. The user can be
activated.
l Deleted. The user is no longer active in the system.
l PasswordReset. This value indicates that a password
reset is in process. See Reset User Password on
page 216 for details.
l LockedOut. The user cannot log in because they
have had too many failed login attempts. To
provide user access before the lock out period ends,
you can initiate a password reset using the Reset
User Password API or set the userLocked
parameter to true using the Modify User Details
API.
l Unknown. The user has no status value.

Control Center automatically deactivates users that

haven't reset their password within a given time
frame and have exceeded the user deactivation grace
period.

userLocked Indicates whether the user is locked out of their

account because of too many incorrect login attempts.
If this value is true, you can change it to false to
restore user access before the lockout period ends.

accessType Indicates the method(s) a user can use to access

Control Center: UI, API, or API_UI (both).

firstName The user first name.

lastName The user last name.

email The user email address.

phone The user phone number.

language The language used to display all the text in the web
interface.

timeZone Control Center uses this value to determine the date

and time to display throughout the web interface.
Valid values are Java 7-supported time zones.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 202
 Return Value Description

customerName The customer with which this user is associated, if

applicable. Applies only to accounts that use
customers, and only if this user is a customer user.
Otherwise, the parameter is null.

customerId A unique identifier for the customer with which this

user is associated, if applicable. Applies only to
accounts who use customers, and only if this user is a
customer user.

customerGroup The customer group to which the user is assigned, if

any. A customer group contains one or more
customers belonging to a common enterprise account.
For account users, a customer group restricts their
view of device information to just the customers in the
group. For customer users, a customer group expands
their view of device information to all the customers
in the group.
The field is always null for service provider users.

accountGroup For service provider users only, indicates the name of

the service provider account group, if any, associated
with the user. Account groups filter the information a
user can view. This field is always null for account and
customer users.

lastLogin The date and time the user last accessed the system
using the web interface.

lastPasswordReset The date and time when the user last reset the
Date password. Timestamp format: yyyy-MM-dd
HH:mm:ss:SSSZ.

passwordExpiration The number of days before the user's password

InDays expires. Seven days before the expiration, Control
Center begins sending email notifications to the user
asking them to reset their password.

liveUpdateEnabled Indicates whether Control Center automatically pushes

device changes to the web interface without requiring
a manual page refresh (true or false).

dateAdded The date and time when the user was created.
Timestamp format: yyyy-MM-dd HH:mm:ss:SSSZ.

dateModified The date and time of the last change to the user
details. Timestamp format: yyyy-MM-dd
HH:mm:ss:SSSZ.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 203
 Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic
RW5nbGlzaFNQQWRtaW5RQTozOGFkNDI0Zi0yMjEzLTQ3ZDAtYjlmNS05OWEzZDdmNzEwNjg="
"https://restapi1.jasper.com/rws/api/v1/users/84176"

Response Example

{
"username": "JohnDoe",
"userId": 84176,
"accountName": "Acme Inc",
"accountId": 100210811,
"operatorName": null,
"operatorId": null,
"roleName": "ACCOUNTADMIN",
"status": "Active",
"userLocked": false,
"accessType": "API_UI",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@jasper.com",
"phone": null,
"language": "English",
"timeZone": "India Standard Time",
"customerName": null,
"customerId": null,
"customerGroup": null,
"accountGroup": null,
"lastLogin": "2017-09-18 12:28:58:828+0000",
"lastPasswordResetDate": "2017-09-18 12:26:02:000+0000",
"passwordExpirationInDays": 180,
"liveUpdateEnabled": true,
"userPrivacyEnabled": true,
"dateAdded": "2017-09-18 12:26:01:789+0000",
"dateModified": "2018-01-10 08:40:43:000+0000"
}

Errors

HTTP
Error Code Description
Code

1400109 404 User not found.

10000024 400 Invalid apiVersion.

10000030 400 Your role does not have access to this API function.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 204
 Get All User Details
Description
Returns the user details for all users. See the API/Role matrix in the
Knowledge Base for a complete list of roles that can use this API.

Resource URL
GET BaseURL/v{apiVersion}/users

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

pageSize (Optional) Specifies the number of records returned in

each response page. The maximum value is 50. The
value defaults to 50. See Pagination on page 27.

pageNumber (Optional) Specifies the number of response pages to

return. This value defaults to 1. See Pagination on
page 27.

Response Parameters
Returns an array of users along with the pagination parameters. For more
information about the user parameters, see Get User Details on page 201.

Return Value Description

pageNumber An integer specifying the number of the current

response page.

users An array of users with details about each. See Get User
Details on page 201 for information about the response
parameters.

lastPage A true or false value indicating whether the current

response page is the last in the series.

Request Example
Make sure to use your own URL and user credentials.

curl -X GET --header "Accept: application/json" --header "Authorization:

Basic
RW5nbGlzaFNQQWRtaW5RQTozOGFkNDI0Zi0yMjEzLTQ3ZDAtYjlmNS05OWEzZDdmNzEwNjg="
"https://restapi1.jasper.com/rws/api/v1/users?pageSize=50&pageNumber=1"

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 205
 Response Example

{
"pageNumber": 1,
"users": [{
"username": "JohnDoe",
"userId": 84176,
"accountName": "Acme Inc",
"accountId": 100210811,
"operatorName": null,
"operatorId": null,
"roleName": "ACCOUNTADMIN",
"status": "Active",
"userLocked": false,
"accessType": "API_UI",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@jasper.com",
"phone": null,
"language": "English",
"timeZone": "India Standard Time",
"customerName": null,
"customerId": null,
"customerGroup": null,
"accountGroup": null,
"lastLogin": "2017-09-18 12:28:58:828+0000",
"lastPasswordResetDate": "2017-09-18 12:26:02:000+0000",
"passwordExpirationInDays": 180,
"liveUpdateEnabled": true,
"userPrivacyEnabled": true,
"dateAdded": "2017-09-18 12:26:01:789+0000",
"dateModified": "2018-01-10 08:40:43:000+0000"
}, {
"username": "JaneAdmin",
"userId": 75677,
"accountName": "Network J",
"accountId": 100530743,
"operatorName": null,
"operatorId": null,
"roleName": "ACCOUNTADMIN",
"status": "Active",
"userLocked": false,
"accessType": null,
"firstName": "Jane",
"lastName": "Doe",
"email": "jane.doe@cisco.com",
"phone": null,
"language": "English",
"timeZone": "Pacific Standard Time",
"customerName": null,
"customerId": null,
"customerGroup": null,
"accountGroup": null,
"lastLogin": "2018-04-02 08:39:53:318+0000",
"lastPasswordResetDate": "2017-07-25 12:04:27:000+0000",
"passwordExpirationInDays": 180,
"liveUpdateEnabled": true,
"userPrivacyEnabled": false,
"dateAdded": "2016-07-21 08:54:09:078+0000",
"dateModified": "2018-04-02 08:40:17:103+0000"

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 206
 }],
"lastPage": false
}

Errors

HTTP
Error Code Description
Code

10000006 400 Invalid pageSize.

10000007 400 Invalid pageNumber.

10000024 400 Invalid apiVersion.

10000030 400 Your role does not have access to this API function.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 207
 Create User
Description
Creates a new user. Control Center sends a welcome email to the new user
with a link to the password set-up page in the product. If you create a
passwordless API user, Control Center does not send a welcome email. You
must send the user name and API key to the new user.
See the API/Role matrix in the Knowledge Base for a complete list of roles
that can use this API.

Resource URL
POST BaseURL/v{apiVersion}/users

Request Parameters
All parameters are required unless they are marked as optional.

Parameter Description

apiVersion The version number for this API. The current version
for all functions is 1.

username The user name is a unique identifier for the person

within Control Center. A user must supply this user
name and a password to log in to Control Center. The
name must be 6-25 alphanumeric characters, with no
special characters or punctuation. No spaces are
allowed at the beginning, middle, or end of the string.
The user name must be unique across all accounts in
Control Center.

roleName The role name defines the application privileges for

the user. For a list of valid values, see User Role
Values on page 31. Be aware that not all users can
create all types of users. The types of users you can
create depend on your user role.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 208
 Parameter Description

accessType Users can access Control Center information through a

web interface or an API. This value determines which
method is available to the user: UI, API, or API_UI
(both). If you create an API Only user, you must
provide them with API documentation because they
will not be able to access it online.
For users who log into Control Center through an
external system that provides single sign-on access,
this value is irrelevant. Control Center treats the user
as if the accessType were API_UI, regardless of the
actual value.
To avoid API and web interface abuse, we recommend
that you select one or the other option rather than
giving the user access to both. The combination option
is intended for developers who are coding with APIs
and want to view test results in the web interface. If
necessary, the operator can remove the Both API and
UI option from the drop down.

accountName The name of the account to which the user is assigned.

customerName (Optional) The customer with which this user is

associated, if applicable. Applies only to accounts that
use customers, and only if this user is a customer
user. Otherwise, the parameter is null.

firstName The user first name.

lastName The user last name.

email Control Center uses this email address to send the

new user a welcome email with a link to the password
setup page.

phone (Optional) You can provide a phone number for the

new user.

language Control Center uses the supplied language to display

all the text in the user interface. The new user can
change this setting in their user profile. See Language
Values on page 30 for a list of valid values.

timeZone Control Center uses this value to determine the date

and time to display throughout the web interface. The
new user can change this setting in their user profile.
Valid values are Java 7-supported time zones.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 209
 Parameter Description

liveUpdateEnabled (Optional) Indicates whether Control Center

automatically pushes device changes to the web
interface without requiring a manual page refresh
(true or false).

passwordlessApiUser (Optional) Indicates that Control Center creates the

API-only user without a password (true or false).

Response Parameters

Return Value Description

userId A unique identifier for the new user.

timestamp The date and time when the user was created. The
timestamp displays in UNIX Epoch clock format. See
Date/Time Formats on page 28 for more information.

Request Example
Make sure to use your own URL and user credentials.

{ curl -X POST --header "Content-Type: application/json" --header "Accept:

application/json" --header "Authorization: Basic
RW5nbGlzaFNQQWRtaW5RQTozOGFkNDI0Zi0yMjEzLTQ3ZDAtYjlmNS05OWEzZDdmNzEwNjg=" -d
"{
\"username\": \"AcmeUser\",
\"roleName\": \"ACCOUNTUSER\",
\"accessType\": \"UI\",
\"accountName\": \"Acme Inc\",
\"firstName\": \"Acme\",
\"lastName\": \"User\",
\"email\": \"acme_user@acme.com\",
\"language\": \"English\",
\"timeZone\": \"Pacific Standard Time\"
}" "https://restapi1.jasper.com/rws/api/v1/users"

Response Example

{
"userId": 30466103,
"timestamp": 1527590173
}

Errors

HTTP
Error Code Description
Code

1400103 400 Could not create user.

1400112 400 Email is blank.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 210
 HTTP
Error Code Description
Code

1400113 400 First Name is blank.

1400114 400 Last Name is blank.

1400118 400 Timezone is missing.

1400119 400 Language is missing.

1400121 400 First Name invalid.

1400122 400 Last Name invalid.

1400123 400 Phone invalid.

1400128 400 Invalid entry. User name must be 6 to 25

alphanumeric characters.

1400129 400 Invalid user access type specified. Permissible access

types are API, UI, API_UI.

1700281 400 Invalid Access type for Passwordless API user.

1700282 400 Passwordless API user cannot be created as feature

is not enabled for requested service provider.

10000024 400 Invalid apiVersion.

10000030 400 Your role does not have access to this API function.

10000567 404 Invalid Account Name.

10000568 400 Username already used. Please try a different one.

10000569 400 Invalid Authority.

10000570 400 Authority is required.

10000571 400 Account Name is required.

10000572 400 Operator Name is required.

10000574 400 AccessType is required.

10000575 400 Invalid Language value provided. For permissible

values, please check the API documentation.

20000005 404 Resource not found - Invalid Role.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 211
 Edit User Details
Description
Changes one or more attributes for a given user. See the API/Role matrix in
the Knowledge Base for a complete list of roles that can use this API.

Resource URL
PUT BaseURL/v{apiVersion}/users/{userId}

Request Parameters
You can change any of the user attributes shown below. One function call
can update multiple attributes.

Parameter Description

apiVersion The version number for this API. The current

version for all functions is 1.

userId An identifier for the user you want to modify. You

cannot change this attribute.
The user ID is not available in the Control Center
web interface, but you can use the Get All User
Details API to find a user ID. Use a partial
response to return the username and userId only.
For more information, see Partial Response
Guidelines.

roleName The role name defines the application privileges

for the user. For a list of valid values, see User
Role Values on page 31. Be aware that not all users
can assign all user roles. The types of roles you
can assign depend on your user role.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 212
 Parameter Description

accessType Users can access Control Center information

through a web interface or an API. This value
determines which method is available to the user:
UI, API, or API_UI (both). If you create an API Only
user, you must provide them with
API documentation because they will not be able
to access it online.
For users who log into Control Center through an
external system that provides single sign-on
access, this value is irrelevant. Control Center
treats the user as if the accessType were API_UI,
regardless of the actual value.
To avoid API and web interface abuse, we
recommend that you select one or the other option
rather than giving the user access to both. The
combination option is intended for developers who
are coding with APIs and want to view test results
in the web interface. If necessary, the operator can
remove the Both API and UI option from the drop
down.

userLocked Indicates whether the user is locked out of their

account because of too many incorrect login
attempts. If this value is true, you can change it to
false to restore user access before the lockout
period ends.

liveUpdateEnabled Indicates whether Control Center automatically

pushes device changes to the web interface
without requiring a manual page refresh (true or
false).

firstName The user first name.

lastName The user last name.

email The user email address.

phone The user phone number.

language Control Center uses the supplied language to

display all the text in the user interface. The new
user can change this setting in their user profile.
See Language Values on page 30 for a list of valid
values.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 213
 Parameter Description

timeZone Control Center uses this value to determine the

date and time to display throughout the web
interface. The new user can change this setting in
their user profile. Valid values are Java 7-
supported time zones.

passwordlessApiUser Indicates that Control Center creates the API-only

user without a password (true or false).

Response Parameters

Return Value Description

userId The ID of the user whose information was updated.

timestamp The date and time when the user details were modified.
The timestamp displays in UNIX Epoch clock format. See
Date/Time Formats on page 28 for more information.

Request Example
Make sure to use your own URL and user credentials.

curl -X PUT --header "Content-Type: application/json" --header "Accept:

application/json" --header "Authorization: Basic
RW5nbGlzaFNQQWRtaW5RQTozOGFkNDI0Zi0yMjEzLTQ3ZDAtYjlmNS05OWEzZDdmNzEwNjg=" -d
"{
\"phone\": \"925-457-0399\",
\"liveUpdateEnabled\": true
}" "https://restapi1.jasper.com/rws/api/v1/users/30466103"

Response Example

{
"userId": 30466103,
"timestamp": 1527590173
}

Errors

HTTP
Error Code Description
Code

1400109 404 User not found.

1400116 400 Email is not valid.

1400117 400 Could not update user.

1700281 400 Invalid Access type for Passwordless API user.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 214
 HTTP
Error Code Description
Code

10000024 400 Invalid apiVersion.

10000030 400 Your role does not have access to this API function.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 215
 Reset User Password
Description
Resets the web interface password for a given user. Control Center sends an
email to the user with instructions for resetting their password. The user
status automatically changes to PasswordReset until the user supplies a
new password.
See the API/Role matrix in the Knowledge Base for a complete list of roles
that can use this API.

Resource URL
PUT BaseURL/v{apiVersion}/users/{userId}/resetPassword

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version for
all functions is 1.

userId The ID of the user whose password you want to reset.

The user ID is not available in the Control Center web
interface, but you can use the Get All User Details API to
find a user ID. Use a partial response to return the
username and userId only. For more information, see
Partial Response Guidelines.

Response Parameters

Return Value Description

userId The ID of the user affected by the password reset.

timestamp The date and time when the password reset process was
initiated. The timestamp displays in UNIX Epoch clock
format. See Date/Time Formats on page 28 for more
information.

Request Example
Make sure to use your own URL and user credentials.

curl -X PUT --header "Content-Type: application/json" --header "Accept:

application/json" --header "Authorization: Basic
RW5nbGlzaFNQQWRtaW5RQTozOGFkNDI0Zi0yMjEzLTQ3ZDAtYjlmNS05OWEzZDdmNzEwNjg=" -d
"https://restapi1.jasper.com/rws/api/v1/users/30466103/resetPassword"

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 216
 Response Example

{
"userId": 30466103,
"timestamp": 1527590173
}

Errors

HTTP
Error Code Description
Code

1400109 404 User not found.

10000024 400 Invalid apiVersion.

10000030 400 Your role does not have access to this API function.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 217
 Delete User
Description
Deletes a given user so the user details are no longer available through the
web interface or the APIs. Control Center retains the data throughout the
operator's default data retention period and then begins the data erasure
process.
See the API/Role matrix in the Knowledge Base for a complete list of roles
that can use this API.

Resource URL
DELETE BaseURL/v{apiVersion}/users/{userId}

Request Parameters

Parameter Description

apiVersion The version number for this API. The current version for
all functions is 1.

userId An identifier for the user you want to delete. The user ID
is not available in the Control Center web interface, but
you can use the Get All User Details API to find a user ID.
Use a partial response to return the username and
userId only. For more information, see Partial Response
Guidelines.

Response Parameters

Return Value Description

userId The ID of the deleted user.

timestamp The date and time when the user was deleted. The
timestamp displays in UNIX Epoch clock format. See
Date/Time Formats on page 28 for more information.

Request Example
Make sure to use your own URL and user credentials.

curl -X DELETE --header "Accept: application/json" --header "Authorization:

Basic
RW5nbGlzaFNQQWRtaW5RQTozOGFkNDI0Zi0yMjEzLTQ3ZDAtYjlmNS05OWEzZDdmNzEwNjg="
"https://restapi1.jasper.com/rws/api/v1/users/30466103"

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 218
 Response Example

{
"userId": 30466103,
"timestamp": 1527590173
}

Errors

HTTP
Error Code Description
Code

1400109 404 User not found.

10000024 400 Invalid apiVersion.

10000030 400 Your role does not have access to this API function.

30000001 500 Unknown server error.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 219
REST Error Messages
Error HTTP
Description
Code Code

1000621 400 Invalid Industry Vertical.

1400103 400 Could not create user.

1400109 404 User not found.

1400112 400 Email is blank.

1400113 400 First Name is blank.

1400114 400 Last Name is blank.

1400116 400 Email is not valid.

1400117 400 Could not update user.

1400118 400 Timezone is missing.

1400119 400 Language is missing.

1400121 400 First Name invalid.

1400122 400 Last Name invalid.

1400123 400 Phone invalid.

1400128 400 Invalid entry. User name must be 6 to 25 alphanumeric

characters.

1400129 400 Invalid user access type specified. Permissible access

types are API, UI, API_UI.

1700281 400 Invalid Access type for Passwordless API user.

1700282 400 Passwordless API user cannot be created as feature is

not enabled for requested service provider.

10000001 401 Invalid credentials.

Control Center uses this error message when the API
credentials are invalid or when the IP address is not
within the allowed range.

10000002 400 AccoundId is required.

10000003 400 ModifiedSince is required.

10000004 400 Invalid accountId.

10000005 400 Invalid status.

10000006 400 Invalid pageSize.

10000007 400 Invalid pageNumber.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 220
 Error HTTP
Description
Code Code

10000008 400 Your role does not have access to operator and
customer custom fields.

10000009 400 Your role does not have access to account custom
fields.

10000010 400 Your role does not have access to customer custom
field.

10000011 400 One or more required fields are missing.

10000012 400 Invalid date format.

10000013 404 Invalid ratePlan.

Two scenarios can cause this error:
l The rate plan name doesn't exist.
l The specified rate plan is not allowed with the
device's communication plan.

10000014 400 Invalid communicationPlan.

10000015 400 Invalid customer.

10000016 400 Invalid overageLimitOverride.

10000017 400 Invalid messageEncoding.

10000018 400 Invalid dataCoding.

10000019 400 Invalid tpvp.

The validityPeriod is invalid.

10000020 400 Message length exceeds the maximum permissible

length.

10000021 400 Invalid iccid.

10000022 400 FromDate is required.

10000023 400 The JSON in the request is not well formed. Please
ensure that commas, colons, braces etc. are formatted
properly.

10000024 400 Invalid apiVersion.

10000025 400 Invalid deviceID.

10000026 400 Invalid modemID.

10000027 400 ToDate must be after fromDate.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 221
 Error HTTP
Description
Code Code

10000028 400 Invalid request.

The request contained one or more unrecognized
parameters.

10000029 400 This SIM may not be moved back to a Pre Activation
status.

10000030 400 Your role does not have access to this API function.

10000031 400 Invalid Zone.

10000032 400 Cycle Start Date should be greater than or equal to

20xx-xx-xx.
The cycleStartDate must specify one of the last three
billing cycles (including the current cycle).

10000033 400 Invalid contactName.

10000045 400 Invalid date.

10000049 400 The daysOfHistory must be less than or equal to 365.

10000062 400 Access Denied.

10000074 400 Account is not of Partner Type.

10000075 400 Trust Relationship is not established with Partner

Account.

10000076 400 Trust Relationship is not active.

10000077 400 Device is already assigned to Partner Account.

10000078 400 Device is not assigned to Partner Account.

10000079 400 Account does not have access to this API.

10000080 403 The API access is forbidden.

This error can occur if your role doesn't have access to
the function or if the operator doesn't have access to
the Custom Charges REST APIs.

10000301 400 Test Ready Data Limit length must be between 0 and
10.

10000302 400 Test Ready Sms Limit length must be between 0 and
10.

10000303 400 Test Ready Voice Limit length must be between 0 and
10.

10000304 400 Test Ready Csd Limit length must be between 0 and 10.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 222
 Error HTTP
Description
Code Code

10000305 400 Test Ready Data Limit must be a positive number.

10000306 400 Test Ready Sms Limit must be a positive number.

10000307 400 Test Ready Voice Limit must be a positive number.

10000308 400 Test Ready Csd Limit must be a positive number.

10000309 400 Invalid Default Sim State.

10000310 400 Invalid Test ready data state.

10000311 400 Invalid File export method

10000312 400 No support information to show. Either Account

Support Email and/or Account Support Phone must be
specified.

10000313 400 Account Support Email must be a correctly formatted

email address and cannot contain commas.

10000314 400 Account Support Phone cannot be more than 25

characters and cannot contain commas (,) or asterisks
(*).

10000315 400 Invalid SMS Enabled value Only true/false allowed.

10000316 400 Invalid Voice Enabled value Only true/false allowed.

10000321 400 Application feature cannot be null.

10000322 400 Sim feature cannot be null.

10000323 400 Site configuration cannot be null.

10000324 400 Support cannot be null.

10000325 400 AccessCommPlan cannot be null.

10000326 400 CsdAccess cannot be null.

10000327 400 BusinessRulesEnabled cannot be null.

10000328 400 GlobalAccountEnabled cannot be null.

10000329 400 PoliciesEnabled cannot be null.

10000330 400 SimOrderingEnabled cannot be null.

10000331 400 SmsAccess cannot be null.

10000332 400 SubscriptionChannel cannot be null.

10000333 400 VoiceAccess cannot be null.

10000334 400 SmsEnabled cannot be null.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 223
 Error HTTP
Description
Code Code

10000335 400 VoiceEnabled cannot be null.

10000336 400 BlockBackwardSimState cannot be null.

10000337 400 DefaultSimState cannot be null.

10000338 400 DisplayDiagnosticWizard cannot be null.

10000339 400 DisplaySpotlight cannot be null.

10000340 400 FixedIpEnabled cannot be null.

10000341 400 TestReadyDataLimit cannot be null.

10000342 400 TestReadySmsLimit cannot be null.

10000343 400 TestReadyVoiceLimit cannot be null.

10000344 400 TestReadyCsdLimit cannot be null.

10000345 400 TestReadyDataState cannot be null.

10000346 400 FileExportMethod cannot be null.

10000347 400 EulaEnabled cannot be null.

10000348 400 ShowAcctSupport cannot be null.

10000349 400 ShowSpSupport cannot be null.

10000436 400 Shared can only be true.

10000437 400 Shared can not be used along with accountId.

10000438 404 Resource not found - Invalid username.

10000439 400 Unauthorized access to the user.

10000441 400 Invalid RatePlan Version.

10000442 400 More than one RatePlan having the same name.
The rate plan name is not unique. Try using the rate
plan version number along with the name to indicate a
unique rate plan.

10000443 400 Invalid BillingCycleStart.

The billing cycle start date doesn't correspond to a
valid billing cycle.

10000500 400 Service provider not found.

10000501 400 Could not create account.

10000504 400 Account already exists.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 224
 Error HTTP
Description
Code Code

10000505 400 Invalid region Id.

10000515 400 Invalid BillingCycleStart.

10000516 400 Not allow to set BillingCycleStart.

10000521 400 Invalid Country Code.

10000528 400 Partner Account creation not allowed.

10000530 400 Account Id cannot be null.

10000532 500 CUSTOM_CHARGE: Error creating a new custom

charge.

10000533 404 Resource not found - invalid charge ID.

10000534 400 Custom Charge reference Id cannot be empty/null.

10000535 400 Custom Charge description cannot be empty/null.

10000536 400 Charge amount cannot be null.

10000537 400 Charge frequency cannot be null.

10000538 400 Empty Rate Plan Id.

10000539 400 Empty Device State.

10000540 404 Resource not found - Invalid operatorId.

10000541 400 Invalid Custom Charge Status.

10000542 400 Empty charge status.

10000543 400 Invalid charge ID.

10000545 400 Invalid charge frequency value.

10000546 400 Invalid Device State.

10000547 400 Unpermitted Charge Status.

10000548 400 Primary contact firstName and lastName are required.

10000549 400 Error deleting custom charge.

10000550 400 Invalid status transition.

You cannot delete a charge unless its status is NEW or
INACTIVE.

10000551 400 AccountId mismatch for given chargeID.

The specified account doesn't contain the specified
charge.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 225
 Error HTTP
Description
Code Code

10000552 400 ReferenceId mismatch with given chargeId.

The reference ID/charge ID combination does not exist
in the account.

10000553 400 The service provider doesn't contain the charge ID.

10000557 404 Resource not found - accounts for given operator.

10000559 500 Unable to fetch custom charges.

10000562 400 Invalid OperatorId for the account provided.

10000563 400 Empty OperatorId.

10000567 404 Invalid Account Name.

10000568 400 Username already used. Please try a different one.

10000569 400 Invalid Authority.

10000570 400 Authority is required.

10000571 400 Account Name is required.

10000572 400 Operator Name is required.

10000574 400 AccessType is required.

10000575 400 Invalid Language value provided. For permissible

values, please check the API documentation.

10000580 400 Customer details required.

10000581 400 Customer name is required.

10000582 400 Invalid customer name. Number of characters allowed

1 - 60.

10000583 400 Account Id is required.

10000584 400 Security answer missing.

10000585 400 Security question missing.

10000586 400 Invalid security question. Number of characters

allowed 0 - 100.

10000587 400 Invalid security answer. Number of characters allowed

0 - 100.

10000588 400 Maximum 4 contacts can be associated with a

customer.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 226
 Error HTTP
Description
Code Code

10000589 400 Invalid contact name. Number of characters allowed 0 -

40.

10000590 400 Invalid contact title. Number of characters allowed 0 -

40.

10000591 400 Invalid contact phone. Number of characters allowed 0

- 25.

10000592 400 Invalid contact mobile. Number of characters allowed 0

- 40.

10000593 400 Invalid contact email. Number of characters allowed 0

- 320.

10000594 400 Invalid address line1. Number of characters allowed 0 -

40.

10000595 400 Invalid address line2. Number of characters allowed 0 -

40.

10000596 400 Invalid city. Number of characters allowed 0 - 40.

10000597 400 Invalid state/region. Number of characters allowed 0 -

40.

10000598 400 Invalid country. Number of characters allowed 0 - 100.

10000599 400 Invalid postal code. Number of characters allowed 0 -

15.

10000602 400 Duplicate customer name.

10000603 400 Invalid account. Account erasure request is in progress

for the account.

10000604 400 Invalid Customer Id.

10000605 404 Customer not found with given Id.

20000000 404 Requested resource not found.

20000001 404 Resource not found - Invalid ICCID.

20000002 404 Resource not found - Invalid smsMsgId.

20000005 404 Resource not found - Invalid Role.

20000003 404 Resource not found - Invalid accountId.

20000013 400 Account billing settings cannot be edited for operator

account.

20000014 400 Empty monthly devices minimum term (months).

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 227
 Error HTTP
Description
Code Code

20000015 400 Empty monthly device minimum.

20000016 400 Invalid activation proration.

20000017 400 Invalid renewal proration.

20000018 400 Invalid sim fee scale.

20000019 400 Sim fee should be between [0-9999999].

20000020 400 Invalid default activation plan.

20000021 400 Invalid default activation fee scale.

20000022 400 Default activation fee should be between [0-9999999].

20000023 400 Invalid enable retail billing.

20000024 400 Invalid default timezone.

20000025 400 Invalid prepaid renewal policy.

20000026 400 Invalid prepaid renewal rate plan.

20000027 400 Invalid activation grace period.

20000028 400 Monthly devices minimum term should be between [0-

999].

20000029 400 Monthly device minimum should be between [0-

999.99].

20000030 400 Invalid minimum activation term.

20000031 400 Invalid request to view account billing settings.

20000032 400 Billing commitment settings cannot be edited for

Essential/Partner accounts.

20000033 400 Invalid request to perform edit operation.

20000034 400 Account billing settings cannot be edited for NBIOT

account.

20000035 400 Shared rate plans can only be viewed by

Advantage/Essential accounts.

20000036 400 Invalid request to assign shared rate plans to the

account.

20000037 400 Operation cannot be performed as there are no rate

plans available for this account.

20000038 400 Cannot perform operation as one or more shared rate

plans not available for this account.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 228
 Error HTTP
Description
Code Code

20000039 500 Error adding shared rate plan id mappings to the

account.

20000040 400 Shared rate plans can only be added by

Advantage/Essential accounts.

20000041 400 Taxable cannot be null.

20000042 400 Billable cannot be null.

20000043 400 ProrationRule cannot be null.

20000044 400 RenewalProration cannot be null.

20000045 400 ActivationPlan cannot be null.

20000046 400 RetailBilling cannot be null.

20000047 400 ImmediateRatePlanChange cannot be null.

20000048 400 EventPlanEnabled cannot be null.

20000049 400 PrepaidRenewalPolicy cannot be null.

20000050 400 PrepaidRenewalRatePlanId cannot be null.

20000051 400 BillActivationGracePeriod cannot be null.

20000052 400 MonthlyDevicesMinimumTerm cannot be null.

20000053 400 MonthlyDeviceMinimum cannot be null.

20000054 400 BillMonthlyDeviceMinimum cannot be null.

20000056 400 Commitments settings cannot be null.

20000057 400 Failed to update shared plans. Cannot remove the

account default rate plan.

20000055 400 BillMinimumActivationTerm cannot be null.

20000058 400 Requested resource not available for Shared Rate plan.
You cannot use shared rate plans in this function.

30000001 500 Unknown server error.

30000002 500 Control Center failed to submit the message to the

SMSC.

30000003 400 Invalid Usage Type.

50001225 400 Shipping Address cannot be null as it is not same as

the billing address.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 229
 Error HTTP
Description
Code Code

50001226 400 PPU Address cannot be null is it as not same as the

shipping address.

50001224 400 Billing Contact cannot be null is it is not same as

primary contact.

50001227 400 Operator name is invalid.

50001228 400 Account type is invalid.

50001229 400 Currency code is invalid.

50001233 400 JSON validation error.

50001230 400 Language is invalid.

50001231 400 Sim state name is invalid.

50001234 400 CommPlan not allowed for Partner Account.

50001235 400 Invalid AccountSegment.

50001236 400 Unsupported Account Type.

REST API/Role Matrix

Control Center provides different API access for different user roles. Take a
look at the REST API/Role matrix for all the details. You can download the
matrix from the Downloads page in the Knowledge Base.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 230
REST API Troubleshooting Checklist
You can quickly troubleshoot REST API issues and identify the main points
of failure by answering the questions in the following checklist. If you
answer Yes, continue to the next question, unless the instructions tell you
otherwise. If you answer No to a question, you've found the problem.
Follow the instructions for correcting the issue.

API Setup and Access

1. Is the URL correct?
Make sure you're using the correct URL with the HTTPS protocol. You
can find the URL in the Knowledge Base on the APIs > REST APIs >
Getting Started page.
2. Is the API key valid?
Each user has a unique key that you can find in the user profile (click
the Show API key button to see it) or at the top of each REST API
function page in the Knowledge Base. Users in the same account cannot
share API keys.
3. Is the authorization header valid?
Ensure that you followed the 3-step process for creating a valid
authorization header: (1) concatenate the user name and API key
(separated by a colon) (2) encrypt the resulting string using Base64 (3)
set the authorization header value to "Basic" followed by the encoded
string.
4. Does the API user have feature access?
If the API user has access to the web interface, log into Control Center
and try to access the same feature in the web interface. (Remember the
Control Center password is different from the API key.) If you can make
the feature work in the web interface, you can make it work via API.
You may need to use multiple user roles as there is no single role that
will guarantee access for all API function calls. Cisco recommends
creating a dedicated user or group of users whose sole purpose is to
execute API functions. For more information about user roles and
access, see REST API/Role Matrix on the previous page.
5. Is the SSL certificate valid and included in your trusted store?
The REST APIs support the HTTPS protocol (not HTTP). The Cisco API
server uses an SSL certificate signed by a top tier Certificate Authority
(CA) to handle HTTPS access. We recommend that you include the root
certificate in your trust store (this is included by default on many
platforms) and use a CA-based chain of trust, rather than hard coding
the Cisco certificate in your API code.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 231
 API Coding
6. Are the request parameters valid?
Typically, the returned error codes will help you identify any problems
with incorrect parameter values. Common problems include: improper
date formats (see Date/Time Formats) and invalid values for device
attributes.
7. Did you verify input parameters and output data with the Try It
feature?
If you're unsure about the request parameters or the returned data, try
executing the API function from within the Knowledge Base using the
Try It feature. This approach can help you isolate problem areas in a
particular function.
8. Is the API code able to process the error codes returned by
Control Center?
When an error occurs, Control Center returns a JSON-formatted
response that contains a human-readable error message and an error
code. Ensure that your code can handle all the errors that may be
returned. The API documentation provides a list of possible errors for
each function.
9. Does the API response coding follow best practices?
After checking your network connection to Control Center, review your
receiver code and error handling. Ensure that your code allows for
additional, unexpected items in the response. Cisco may add new return
values to the APIs.

API Results and Performance

10. Did the API call return the expected results?
You can use a web services testing tool to set up and run API function
tests and test suites to verify variable values at different stages of the
API execution. Also, keep in mind that the role of the API user
determines the features and data that the API call can access and return.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 232
 11. Did the API call return data with the expected performance?
Follow these standards to improve Control Center API performance.
l Limit the number of active calls to one at a time and avoid
concurrent API processing.
l Do not exceed the calls per second limit.
l Page size is limited to 50 records. Make sure your code handles
pagination properly.
l Align the timing of your API calls with the frequency of your
operator's record updates. For example, if your operator updates
their usage information once per 6 hours, there's no need to request
the information via API more often than once per 6 hours.
l Be aware that the API calls are not intended to provide real-time
monitoring of service usage. For more immediate feedback when
certain conditions occur, use automation rules and push APIs.
You can poll API calls that return small amounts of data more
frequently (once per minute, if necessary) without affecting the overall
performance of Control Center. See API Policies and Best Practices on
page 7 for more details.

If you haven't been able to identify the cause of the API issue, contact Cisco
Product Support.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 233
 Chapter 2

SOAP APIS
SOAP API support is included with all Control Center accounts, including
trial accounts. This section provides an overview of the APIs, including the
development process and coding standards.
l Function Documentation. For reference information about
individual API functions, see the online API schema. Within the
Knowledge Base, go to the APIs > SOAP APIs page and click the Go to
API Schema button.
l Path/License Key. To access the SOAP API path and license key for
your account, go to the APIs > SOAP APIs page in the Knowledge Base.

Roles with Access

Service provider, account, and customer users can use the APIs. However,
user access is limited by the following:
l Access Type. The user must have an Access Type of API Only or Both
API and UI in order to access the APIs. You can find that information
on the User Details page: Admin > Users > User Name link > Access
Type.
l Role. If a user with UI access can perform the function within the
Control Center web interface, then a user with the same role and
API access will be able to complete the task via an API call. There is
no single role that will guarantee access for all function calls. See the
API/Role matrix in the Knowledge Base for a complete list of roles
and the APIs they can use.

Typically, an enterprise will create user accounts with access to both the UI
and the APIs for their engineering team during development. For auditing
purposes, Cisco recommends that production code use a dedicated Control
Center user whose sole purpose is to execute API functions. When you
create the user, you can specify that the user has API-only access to Control
Center.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 234
 Field Restrictions. While multiple roles may have access to the same API,
not every role will have access to all the fields listed in the documentation.
You can verify field access for a particular role by logging into the web
interface as a user with the same role who also has web interface access
and then looking for the field.

AccountAPIOnly Role. This legacy role has access to Control Center

through the API, but not through the web interface. The purpose of this
role was to provide restricted access to Control Center for operator
partners using a different platform. We recommend that current users take
advantage of the Access Type attribute to create users with API-only access
to Control Center rather than creating users with the AccountAPIOnly role.

IP Address Restrictions . If an enterprise implements IP Address

Restrictions, an API user might not have API access if their IP address falls
within a restricted range.

Terminology
Terminals. Many API functions refer to a device as a “terminal.” The terms
are interchangeable.
Network Access Config. This is a legacy Control Center term for a
communication plan. We continue to use the term because several long-
standing APIs use the term in their function names.
For information about other terms, refer to the Glossary in the main user
guide.

Getting Started
To get started with the SOAP APIs, read through the following information:

Topic Description

SOAP API Development Describes the steps involved in API development from
Process setting up the environment to going live in production.

SOAP API Code Explains topics such as authentication, common

Standards function parameters, scheduling, and more.

WSDL Files Describes all the WSDL files that are available.

Best Practices Provides guidance for creating programs that ensure

effective API performance for all users.

SOAP API Error Discusses the standard SOAP Fault element.

Handling

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 235
 SOAP API Development Process
Here’s the overall SOAP API development process:

Step 1: Set up development environment

First, you’ll need to download the WSDL and XML schema files for the API.
You can get these files from the Knowledge Base: APIs > SOAP APIs >
Getting Started > WSDL Files. Then, follow the tutorial instructions for
your preferred coding environment (Java, C#, Perl, PHP, or Ruby). You can
use any language that supports SOAP web services.

Step 2: Locate your API license key

To use any API calls, you must supply a license key. You will find both the
license key and the SOAP API path on the APIs > SOAP APIs page in the
Knowledge Base.
You will need separate license keys for the sandbox environment and the
production environment. When you request access to the sandbox
environment, Cisco sends you the sandbox path and a license key.

Customer Access. Be aware that Control Center doesn’t display the API
license key to users with customer roles. A customer must request the key
from their enterprise.

Step 3: Create/test code

The online technical documentation provides code samples as well as
detailed function descriptions to help you create your own code. When
you’re ready, you can test the code in the sandbox (if a sandbox account
has been created for you) or in your production account. Be aware that the
sandbox and production environments are completely separate. When you
use the sandbox environment, there’s no way you can damage production
data with your test code.

Step 4: Go live
If you are using a sandbox account to test your code, you'll need to replace
the credentials, license key, and URL in your calls when you’re ready to put
your code into production. Be aware that you cannot migrate any data from
the sandbox environment to the production environment or vice versa.
In production environments, make sure you replace the sandbox URL with
the production URL. Production URLs must use the full path URL, for
example:
l Sandbox SOAP URL: https://jpotest.jasper.com/ws/service/echo
l Production URL: https://api.jasper.com/ws/service/echo

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 236
 One caveat. Cisco may, at its discretion, disrupt or remove access to the
API sandbox (testing) environment for any reason. We will do our best to
notify you in advance if we anticipate a service interruption. Also, we
cannot guarantee continuous support for the sandbox environment.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 237
 SOAP API Code Standards
This section provides some high level information about how the SOAP API
calls work.

Standard Description

SOAP request and Each API function maps to two SOAP functions, a
response request that sends the input to Control Center and a
response from Control Center containing the
requested data. This document treats each API pair as
a single entity for the sake of discussion.

Authentication For authentication, Control Center requires three

pieces of information: user name, password or API
key, and a license key.
User Name/Password. All Control Center users have
a user name, but some users might not have a
password, depending on the account password policies.
SOAP API calls must contain the user name and can
use either the password or an API key for
authentication.
API Key. Every user with API Only or Both API and UI
access has a unique API key. Users can use either an
API key or a password for authentication. Users with
web interface access can generate and view their own
API key on the User Profile page. Users without
web interface access must request an API key from an
administrator user with web interface access. Be
aware that you'll need different API keys for the
production and sandbox environments.
License Key. Every account has one license key that is
shared by all users and required for SOAP API
authentication. To get your license key, open the
Knowledge Base and go to the APIs > SOAP APIs page.
If you access different operators using separate
instances of Control Center, you’ll need a separate
license key for each operator. For more information,
see Working with Multiple Operators on page 253. Be
aware that the license key for the sandbox
environment is different from the license key for the
production environment.

Role Access See the SOAP API/Role Matrix on page 273 for details
about which functions each user role can perform.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 238
 Standard Description

URL When you use an API function, you must send the
request to an operator-specific URL. To get your URL,
open the Knowledge Base and go to the APIs > SOAP
APIs page. Use the HTTPS protocol for data security
and do not modify the path in any way.
If your company uses multiple operators, you’ll have a
unique SOAP URL for each of them (see Working with
Multiple Operators on page 253). Be aware that the
URL for the sandbox environment is different from the
URL for the production environment.

Effective Date Some APIs have an effective date attribute that allows
you to schedule the task at a future date. Be aware
that all dates are in UTC. For the task to take effect
immediately, pass a null value for the effective date.

Build ID Every API response contains the build ID of the

current Control Center release. This value has a
maximum length of 100 characters.

Message ID/ If you anticipate sending multiple API requests within

Correlation ID a short period of time, you can use message IDs to
match the function request with the corresponding
response. In the request, simply send a unique string
(called a message ID). Control Center will include the
same string (called a correlation ID) in the response.
Even if you don’t intend to use this parameter, you
must supply a placeholder value (for example, fred) in
every request.

Version Number Both the API request and response contain a version
number. In the API request, the version number refers
to the version of the API that you're using. Because
Control Center doesn't currently use this string, the
value is optional. However, we recommend using "1.0"
as a best practice. In the API response, the version
number refers to the current release of Control
Center, for example: 6.14. Both version numbers have
a maximum length of 100 characters.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 239
 Standard Description

Input Array For APIs that take an array as input, there is a limit of
50 input items. The API returns results for any items
in the array that have data. An error occurs only when
all of the items in the array are invalid.
For example, GetSessionInfo allows you to retrieve
session information for up to 50 different ICCIDs. If you
supply an array of four ICCIDs where one of the ICCIDs
is invalid, Control Center will return data for the three
valid ICCIDs and no error for the fourth. You would
receive an error only if all four ICCIDs were invalid.

Pagination For APIs that typically return numerous results,

Control Center supports two pagination parameters:
pageNumber and totalPages. You request a specific
page number and the function returns an array of
records from that page and a count of the total pages
in the result set. Once you know the total number of
pages, we recommend you request each page in
sequence until you receive the entire result set. The
page size is limited to 50 records, a number that you
cannot change. However, if you do not specify a page
number, Control Center will return only the first 1000
records and a totalPages value of -1.

Extra Elements in the Over time, Cisco may add new elements to an API. All
Response API responses will continue to conform to the
published XML schema, but it's important to design
your code so unexpected elements in the API response
won't cause a process failure.

SSL Certificates The Cisco API server uses an SSL certificate signed by
a top tier Certificate Authority (CA) to handle HTTPS
access. We recommend that you include the root
certificate in your trust store (this is included by
default on many platforms) and use a CA-based chain
of trust, rather than hard coding the Cisco certificate
in your API code. Otherwise, you will need to update
your API code if the Cisco certificate changes in the
future.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 240
 WSDL Files
The following table describes the WSDL files available for Control Center's
API functions. To download the files, open the Knowledge Base from within
Control Center and go to APIs > SOAP APIs > Getting Started > WSDL Files.

WSDL File Description

JasperAPI.xsd XML Schema for all Cisco web service calls.

Terminal.wsdl WSDL for device-related calls such as

GetTerminalDetails, EditTerminal, etc.

Billing.wsdl WSDL for usage and invoice calls such as

GetTerminalUsage, GetInvoice, etc.

Sms.wsdl WSDL for SMS calls such as GetSMSDetails,

SendSMS, etc.

Echo.wsdl WSDL for basic testing of the Cisco web

service (echoes a message back to you).

Account.wsdl WSDL for account calls such as GetAccount,

GetAccountIdByAcctName, etc.

NetworkAccess.wsdl WSDL for communication plan calls such as

GetNetworkAccessConfig,
EditNetworkAccessConfig, etc.

Eventplan.wsdl WSDL for event plan calls such as

GetTerminalEvents, ActivateTerminalEvent,
etc.

GlobalSimTransfer.wsdl WSDL for Global SIM transfer calls such as

TransferGlobalSim,
GetGlobalSimTransferStatus etc.

Order.wsdl WSDL for SIM order calls such as

UpdateOrderStatus etc.

AddRoutableMSISDN.wsdl WSDL to request a routable MSISDN.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 241
 SOAP API Error Handling
When a SOAP fault occurs, Control Center returns a standard Fault element.
See the W3C documentation for information about the standards. Control
Center uses the fields as follows. A safe maximum length for these fields is
100 characters.

Fault Element Field Description

faultCode Standard value defined by the W3C, such as "SOAP-

ENV:Server". It is always 100 characters or less.

faultString Control Center error code, for example "200100". See

SOAP Error Messages on page 264 for details. This
string is always 100 characters or less.

faultActor Currently unused by Control Center.

detail An XML structure containing the error details,

intended for troubleshooting purposes. See an
example below. This can have an arbitrary length
depending on the error. It is optional for customers to
process, so they can ignore the field (or truncate at a
certain number of characters) as needed.

<detail>
<jws:requestId xmlns:jws="http://api.jasperwireless.com/ws/schema">
AM6Sm6OiMPqsiF2T
</jws:requestId>
<jws:error xmlns:jws="http://api.jasperwireless.com/ws/schema">
No terminal usage found
</jws:error>
<jws:exception xmlns:jws="http://api.jasperwireless.com/ws/schema">
com.jasperwireless.ws.ApiException
</jws:exception>
<jws:message xmlns:jws="http://api.jasperwireless.com/ws/schema">
iccid=12345
</jws:message>
</detail>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 242
SOAP API Functions
This section lists all the Control Center SOAP API functions by category. For
detailed reference information about each function, look in the Knowledge
Base: APIs > SOAP APIs > SOAP API Schema.

Devices
The device APIs provide access to detailed device information, including the
current session. You can also change attribute values.

API Call Description

AssignOrUpdateIPAddress Changes the value of a given device IPv4

address. This function allows you to manage IPv4
addresses yourself without relying on the
operator. You can assign any IPv4 address you
like, as long as it falls within a given range. In
particular, you can reuse IP addresses that were
associated with devices that are no longer in
use.
To assign IPv6 addresses, you must use the Edit
Device Details REST API.

EditNetworkAccessConfig Changes the communication plan (Network

Access Config) associated with a given device.

EditTerminal Changes the value of a single attribute for a

given device. You can specify that the change
take effect immediately or schedule it for some
future date.

GetModifiedTerminals Returns a list of ICCIDs for all the devices that

have been modified since a given date and time.
To get a list of all devices, simply omit the
"since" parameter.

GetNetworkAccessConfig Returns the communication plan ID (Network

Access Config ID) for one or more devices.

GetSessionInfo Returns the current session information (IP

address and session start time) for one or more
devices. If the specified device is not in session,
no information is returned.

GetTerminalDetails Returns detailed information for each of the

devices in a list.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 243
 API Call Description

GetTerminalLatestNetwork Returns the same information as

Registration GetTerminalLatestRegistration, but works for
both SS7 and Diameter events. This API works
with devices using either the GSM/GPRS or the
LTE network.

GetTerminalLatest Returns information about a given device’s most

Registration recent SS7 network registration, including the
name of the registering operator and the global
title address of the network node. For devices
using the LTE network, you must use
GetTerminalLatestNetworkRegistration instead.
This information can help you troubleshoot
network problems by identifying when and
where the device last successfully attached to
the network.

GetTerminalsByIMSI Returns a list of ICCIDs corresponding to a given

set of device IMSIs.

GetTerminalsByMsisdn Returns a list of ICCIDs corresponding to a given

set of device phone numbers (MSISDNs).

GetTerminalsBySecureSimId Returns a list of devices corresponding to a

given Secure SIM ID.

SendCancelLocation Forces a device off the network, causing it to re-

register. Commonly used to correct network
registration problems, this function is currently
available in Control Center through Spotlight.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 244
 Global SIMs
The Global SIM APIs allow you to manage over-the-air SIM swaps for
devices that contain global SIMs. These APIs mirror many of the functions
you can perform through the Control Center user interface. To identify a
device, you must use the ICCID of the SIM under the primary operator (the
Primary ICCID).

API Call Description

CancelGlobalSimTransfer Cancels a global SIM transfer request for a given

device.

GetGlobalSimTransferStatus Returns the status of the swap process for a

specified Global SIM.

TransferGlobalSim Transfers a SIM from one operator to another by

changing the device IMSI. You must supply the
ICCID of the SIM under the primary operator, the
name of the target operator, the name of the
global alliance, and the transfer type (standard
or revert). If you supply a callback URL, Cisco
sends a confirmation message when the process
is complete.

Related API: Use the GetTerminalLatestRegistration API to help you

locate a SIM before transferring it to a different operator. This function
returns information about a given device’s most recent network
registration, including the name of the registering operator and the global
title address of the network node.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 245
 Messages (SMS)
The message APIs provide historical information about messages that a
particular device has sent to or received from Control Center. You can also
send messages to one or more devices.

API Call Description

GetModifiedSMS Returns a list of IDs for the messages that have been
sent by a device to Control Center or received by a
device from Control Center during a specified time
period.

GetSMSDetails Returns detailed information about one or more

messages exchanged between the device and Control
Center.

SendBulkSMS Sends a message to one or more devices (by SIM ID).

SendBulkSMSToMsisdn Sends a message to one or more phone numbers (by

MSISDN).

SendSMS Sends a message to a single device (by SIM ID).

SendSMSToMsisdn Sends a message to a single phone number (MSISDN).

Message Text Encoding

The SendSMS API supports more than a half dozen types of SMS message
encoding schemes. You specify the encoding scheme in the
messageTextEncoding field. This composite field defines the encoding
format for the message text itself (defaults to LITERAL) as well as the
encoding scheme Control Center will use when submitting the message to
the SMSC.
Use the information in the following table to determine which values to
use.
l Field Value. The value used in the messageTextEncoding field in the
SMS APIs.
l SMS Encoding. The encoding scheme used for the message text you
supply in the API. Please ensure the value supplied in the
messageText field uses the encoding scheme defined in the
messageTextEncoding field.
l Control Center Encoding. Encoding scheme Control Center uses
when submitting the message to the SMSC. The operator's SMSC must
be configured to support this scheme.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 246
 Field Value SMS Encoding Control Center Encoding

LITERAL LITERAL Default encoding scheme that

depends on your operator’s network
configuration.

BASE64 BASE64 Default encoding scheme that

depends on your operator’s network
configuration.

LITERAL_IRA LITERAL ASCII

BASE64_IRA BASE64 ASCII

LITERAL_BINARY LITERAL 8 bit encoding

BASE64_BINARY BASE64 8 bit encoding

LITERAL_GSM7 LITERAL GSM 7 bit encoding

BASE64_GSM7 BASE64 GSM 7 bit encoding

Be aware that only LITERAL and BASE64 encoding apply to the GetSMS
API.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 247
 Rate Plans
This set of APIs allows you to manage the rate plans connected with a
particular device. You can modify a device’s standard rate plan, change the
plans in the device’s queue, and manage any events associated with the
device. These APIs do not allow you to create or edit the rate plans
themselves.

API Call Description

ActivateTerminalEvent Assigns an event rate plan to a device.

DeleteTerminalEvent Cancels a scheduled event for a particular

device. You cannot cancel an event that’s in
progress.

EditTerminalRating Adds a rate plan to the top of a device’s queue. If

a device is using a monthly rate plan and has an
Activated SIM state, you can change the rate plan
immediately using EditTerminal.

GetAvailableEvents Returns a list of all the event rate plans

available to a given device.

GetTerminalEvents Returns a list of all events associated with a

device, including historic events, current events,
and future scheduled events.

GetTerminalRating Returns the current base rate plan and all

queued rate plans for a given device.

QueueTerminalRatePlan Adds a rate plan to the end of a device’s queue.

To add a plan to the beginning of the queue, use
EditTerminalRating.

RemoveRatePlanFromQueue Removes the specified rate plan from a device’s

queue.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 248
 Usage
You can examine the data, message, and voice usage for an individual device
with the following APIs. For information about usage across all devices and
rate plans during a billing cycle, refer to the invoice API.

API Call Description

GetTerminalUsage Returns the data usage amount for a device

during a particular billing cycle. To access the
device usage for the current month, use
GetTerminalDetails and examine the
MonthToDateUsage field.

GetTerminalUsageDataDetails Returns information about all the data

sessions that occurred during a particular
billing cycle for a given device.

GetTerminalUsageSmsDetails Returns information about all the messages

sent or received by a device during a
particular billing cycle.

GetTerminalUsageVoiceDetails Returns information about all the voice calls

received or placed by a device during a
particular billing cycle.

Invoices
Control Center provides a single API to access the high level details of an
invoice. For more information about individual device usage during a
billing cycle, refer to the usage APIs.

API Call Description

GetInvoice Returns invoice data for a given account and billing

cycle. This data includes the Details information that
appears at the top of the Billing > Invoices > Invoice
Details page, but not the information that appears in
the tabs across the bottom of the page. For example,
you can get:
• Total subscription charges
• Total usage charges for data and/or SMS messages
in excess of included usage
• Total billable usage volume by all billable SIMs
• Activation charges, should any apply
• Other charges such as network services fees
You can also use the Usage APIs to access device
usage information for each billing cycle.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 249
 Users
The user API allows you to create new users.

API Call Description

CreateUser Creates a Control Center user with the given

information.

Test
A single test API allows you to test your connection to Control Center
during development.

API Call Description

Echo Simple test call that returns a value you send as input.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 250
SOAP API Use Cases
This section describes several use cases or design patterns that are
common across all applications that access Control Center.

Analyzing Device Usage

Using the API set you can analyze device usage on a regular basis to
determine if any devices are approaching or exceeding their included usage.
If so, you can move the devices to a different rate plan with a higher usage
allotment and a lower fee, as compared with the subscription and overage
fees in the original rate plan. The following API functions give you slightly
different views into device usage:
l GetTerminalUsage returns the data usage of a device during a
particular billing cycle. The TotalDataVolume attribute tells you how
much data the device used overall. The BillableDataVolume attribute
tells you how much of that data was subject to overage charges.
l GetTerminalUsageDataDetails returns usage information by zone
or by country. You can also examine the length of each data session.
GetTerminalUsageSMSDetails and GetTerminalUsageVoiceDetails will
provide the same information for SMS and voice service.
l GetTerminalDetails provides the MonthToDateUsage for the current
billing cycle. The OverageLimitReached attribute will also tell you if
the device has started incurring overage charges.

If you discover that a device has used more data than you would like, you
can assign a different rate plan to the device using one of these two APIs:
l EditTerminal. If the device is currently using a monthly rate plan,
use this function to change the rate plan.
l EditTerminalRating. If the device is currently using a prepaid plan,
you can’t change the plan until the prepaid plan expires. Then you can
use the device queue to assign the next rate plan. If you can anticipate
which rate plan will be most appropriate, you can set up the queue in
advance or you can use EditTerminalRating to dynamically add a new
rate plan to the queue. When the prepaid rate plan expires, Control
Center will automatically assign the rate plan at the top of the queue
to the device.

In this way you can cycle through all your devices and adjust their rate
plans, if necessary.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 251
 Automation Rules. For certain use cases, you might consider using an
automation rule in Control Center (Automation > Rules > Actions menu >
Create New button). These rules offer a variety of ways to monitor usage,
manage subscriptions, and provision SIMs—without any programming.

Synchronizing Databases
Many enterprises maintain an internal database, separate from Control
Center, with device attributes, usage, and message information. The API set
gives you an easy way to synchronize your internal systems with Control
Center. Here’s the process:

For Device Attributes

1. Use GetModifiedTerminals to return a list of devices whose
information has changed since a specified date.
2. Use GetTerminalDetails to return the detailed information for just the
devices returned in step 1.
3. Update your internal database with the data returned in step 2.

For Messages
1. Use GetModifiedSMS to return a list of messages that have been sent
or received during a certain time period.
2. Use GetSMSDetails to return the detailed information for just the
messages returned in step 1.
3. Update your internal database with the data returned in step 2.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 252
 Working with Multiple Operators
Many companies with connected devices contract with more than one
operator. As long as all these operators use the Cisco platform, you can
create a single application that can access and manage information in any
operator’s instance of Control Center. All you need to do is store log-in
parameters for each operator instance and then use the appropriate set of
parameters when necessary.

Understanding Log-in Credentials

In Control Center every account, representing an enterprise, has one and
only one operator as a parent. Each account contains a collection of devices
as well as a set of users who can view and manipulate these devices. When
a user logs in, Control Center knows which account, operator, and devices
are associated with the user and limits the user's activities accordingly.
A global enterprise with a connected device deployment that spans multiple
operators will have multiple Control Center accounts and, thus, multiple
user log-ins within the web application. Since web services use the same
security infrastructure as the web application, each API request must
include a unique set of user log-in credentials for the corresponding service
provider.
For each operator, you'll need the following information:
l URL. Each operator has a unique URL for their instance of Control
Center.
l Account Credentials. Your company will have a unique account with
each operator. For each account you must supply a username and
password for a user with the appropriate privileges.
l License Key. You must use a different license key to access the data
in each operator's instance of Control Center.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 253
 Code Sample
The code sample below shows an API request for the
GetModifiedTerminals web service, with the credentials and custom
information shown in red. You must send the SOAP request to the
appropriate API URL for the operator you want to access. For example:
https://<OperatorApiHost>/ws/service/terminal

<soapenv:Envelope xmlns:sch="http://api.jasperwireless.com/ws/schema"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsse:UsernameToken wsu:Id="UsernameToken-16847597"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd">
<wsse:Username>UserName</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-
wss-username-token-profile-1.0#PasswordText">Password</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
<sch:GetModifiedTerminalsRequest>
<sch:messageId>?</sch:messageId>
<sch:version>?</sch:version>
<sch:licenseKey>xxxxxxx-xxxx-xxxx-xxxx-xxxx</sch:licenseKey>
<sch:since>2009-09-01T00:00:00Z</sch:since>
</sch:GetModifiedTerminalsRequest>
</soapenv:Body>
</soapenv:Envelope>

Storing Log-in Credentials

Global enterprises can build Control Center API access from a single code
base that works across operators by storing API request parameters for
each operator in a table structure. The operator table is accessible to the
calling logic, which uses the information in the table to build the web
service requests for each operator and then processes the results. This
data-driven approach is extensible and grows with you as you expand your
IoT footprint without requiring additional code.
The following example shows a logical view of how a single customer
(Acme Widgets) served by two operators could design a single solution to:

1. Find all devices that have been updated since their last check (on
09/01/2009).
2. Retrieve current status details for each device with updates and apply
those changes to their internal device tracking application.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 254
 The following table contains information for each operator serving Acme
Widgets through the Control Center platform.

Operator 1 Operator 2

URL api.operator1.com api.operator2.com

Username acmeOp1User acmeOp2User

Password acmeOp1Password acmeOp2Password

License Key c0b244928-2bc9-57d6-1111 b0a877928-de19-75a67-2222

API Logic
For each operator, the code must:
l Retrieve the URL, log-in credentials, and license key for the
enterprise's account with the operator.
l Construct the appropriate GetModifiedTerminalsRequest call using
the information.
l Submit the GetModifiedTerminalsRequest to the operator's API URL.
l Receive the resulting list of modified ICCIDs from
GetModifiedTerminalsResponse.
l For each modified ICCID returned in GetModifiedTerminalsResponse,
pass the ICCID to GetTerminalDetailsRequest and then store the
returned device attributes in the local device tracking system.

If the enterprise expands into a new geography, the standard API logic
above works without modification as long as you insert a new row into the
credential table for the operator serving the new region.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 255
Tutorials
This section contains instructions and tips for using various coding
languages with the Control Center APIs.

Java
Follow these steps to begin using Java:

1. Install the Java(TM) Development Kit 1.5+.

2. Install Maven.
3. Download the javaSample.zip file from the Knowledge Base: Home >
APIs > SOAP APIs > Tutorials > Java. Extract the files in any directory.
4. Open a command prompt at that directory. Type the following to install
xmldsig.jar into your local Maven repository (use "/" instead of "\" if
you're on Linux or Mac):
mvn install:install-file -Dfile=lib\xmldsig.jar -DgroupId=javax.xml.crypto -
DartifactId=xmldsig -Dversion=1.0 -Dpackaging=jar

5. Then type the following to compile and package the sample files:
mvn clean package assembly:single

6. Type the following to call Echo API (use "/" instead of "\" if you're on
Linux or Mac):
java -cp target\Sample-1.0-jar-with-dependencies.jar
com.jasperwireless.ws.client.sample.EchoClient <licenseKey>

7. Type the following to call the GetTerminalDetails API for the given
ICCID (use "/" instead of "\" if you're on Linux or Mac):
java -cp target\Sample-1.0-jar-with-dependencies.jar
com.jasperwireless.ws.client.sample.GetTerminalDetailsClient <licenseKey>
<username> <password> <iccid>

8. (Optional) If you need to pass binary text (for SMS messages, for
example), use the following code for Base64 encoding/decoding.

Encode Base64 base64 = new Base64();

byte[] encodedMsg = base64.encode
(smsMessage.getMessageText().getBytes());

Decode byte[] decodedMsg = base64.decode(msgTxt.getBytes

());
if (decodedMsg != null) {
msgTxt = new String(decodedMsg);}

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 256
 Notes
l Request/Response XML strings are printed to System.out for
debugging purposes.
l The SAAJ library is used to handle SOAP calls.
l The XWSS library is used to secure the message with
username/password token (which requires the file
securityPolicy.xml).
l You can use an XML binding library (such as JAXB) to further simplify
your development process.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 257
 C#
Follow these steps to begin using C#:

1. Right click on the project in the "Solution Explorer" window and choose
"Add Web Reference ..." In Visual Studio® 2008, right click on the
project in the "Solution Explorer" window, choose "Add Service
Reference ...", then click "Advanced...", then click "Add Web Reference..."
2. Input the correct URL for WSDL file, for example
http://apitest.jasperwireless.com/ws/schema/Terminal.wsdl. See WSDL Files on
page 241 for the production URL.
3. Add the file SecurityHeader.cs into your project to override the
generated proxy and add the XWSS security header to every request.
4. Go to the class TerminalService in the newly-created web reference (for
example, Reference.cs). You can do this by going to Object Browser,
searching for "TerminalService", and double-clicking on the
TerminalService class.
5. Add the following line above the namespace declaration at the top of
Reference.cs:
using com.jaspersystems.api;

6. Add this public member to every service class in the auto generated
Web Reference proxy, say in class TerminalService:
public SecurityHeader securityHeader;

7. Add the following line to every method that will be called in the auto
generated Web Reference proxy, say in TerminalService just above
public GetModifiedTerminalsResponse GetModifiedTerminals(...):
[System.Web.Services.Protocols.SoapHeaderAttribute("securityHeader")]

8. Follow the sample GetModifiedTerminals.cs to make the API call.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 258
 9. (Optional) If you need to pass binary text (for SMS messages, for
example), use the following code for Base64 encoding/decoding.

Encode byte[] inArray = new byte[msgTxt.Length];

int x;
for(x=0; x < msgTxt.Length; x++) {
inArray[x] = (byte)charArray[x];
}
string encodedString = Convert.ToBase64String
(inArray,0,inArray.Length,Base64FormattingOptions.Non
e);

Decode byte[] outArray = Convert.FromBase64String(respMsg);

char[] outCharArray =new char[outArray.Length];
for (x = 0; x < outArray.Length; x++)
{
outCharArray[x] = (char)outArray[x];
}
string decodedString = new string(outCharArray);

Sample Files
You can download the sample files from the Knowledge Base: Home >
APIs > SOAP APIs > Tutorials > C# > Sample Files.
l GetModifiedTerminals.cs
l SecurityHeader.cs

Troubleshooting
When there is a SOAP exception, Visual Studio displays the error code only.
To see the detailed message, click on "View Detail...", expand
SOAPException > Detail, and take a look at the InnerText field.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 259
 Perl
Follow these steps to begin using Perl:

1. Install the following modules:

l SOAP::Lite: simple SOAP library

For example, if you're using ActivePerl on Windows, use the

following command:
ppm install http://theoryx5.uwinnipeg.ca/ppms/SOAP-Lite.ppd

l Crypt::SSLeay: HTTPS support

For example, if you're using ActivePerl on Windows, use the
following command:
ppm install http://theoryx5.uwinnipeg.ca/ppms/Crypt-SSLeay.pp

2. Download the sample files below.

3. Open the echo.pl sample file in a text editor and put in your own license
key. Then type perl echo.pl to call the Echo API.
4. Open the getTerminalDetails.pl sample file in a text editor and put in
your own license key, userName, password, and ICCIDs. Then type perl
getTerminalDetails.pl to call the GetTerminalDetails API.

Note: The SOAP::Lite debug messages are enabled in the sample files, so
that you can see the request/response XML. Once you are comfortable
with the calls, you may want to turn this off by replacing SOAP::Lite
+trace => ['debug']; with SOAP::Lite;

5. (Optional) If you need to pass binary text (for SMS messages, for
example), use the following code for Base64 encoding/decoding.

Encode use MIME::Base64;

my $encoded = encode_base64('Hello World');

Decode my $decoded = decode_base64($encoded);

Sample Files
You can download the sample files from the Knowledge Base: Home >
APIs > SOAP APIs > Tutorials > Perl > Sample Files.
l echo.pl
l getTerminalDetails.pl

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 260
 PHP
Follow these steps to begin using PHP:

1. Install the following libraries:

l NuSOAP: simple SOAP library

l PHP cURL: HTTPS support

2. Download the sample files below.

3. Open the echo.php sample file in a text editor and put in your own
license key. To call the Echo API, type php echo.php. Be aware that
nusoap 0.9.5 shows some warnings at runtime. These are harmless and
can be ignored.
4. Open the getTerminalDetails.php sample file in a text editor and put in
your own license key, userName, password, and ICCIDs. To call the
GetTerminalDetails API, type php getTerminalDetails.php.
5. (Optional) If you need to pass binary text (for SMS messages, for
example), use the following code for Base64 encoding/decoding.

Encode $encoded = base64_encode('Hello World');

Decode $decoded = base64_decode($encoded);

Sample Files
You can download the sample files from the Knowledge Base: Home >
APIs > SOAP APIs > Tutorials > PHP > Sample Files.
l echo.php
l getTerminalDetails.php

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 261
 Ruby
Follow these steps to begin using Ruby:

1. Install the Savon SOAP client. Type gem install savon to install via Ruby
Gems.
2. Download the sample files below.
3. Open the echo.rb sample file in a text editor and put in your own
license key. To call the Echo API, type ruby echo.rb.
4. Open the getTerminalDetails.rb sample file in a text editor and put in
your own license key, userName, password, and ICCIDs. To call the
GetTerminalDetails API, type ruby getTerminalDetails.rb.
5. (Optional) If you need to pass binary text (for SMS messages, for
example), use the following code for Base64 encoding/decoding.

Encode require 'base64'

encoded = Base64.encode64('Hello World');

Decode decoded = Base64.decode64(encoded);

Sample Files
You can download the sample files from the Knowledge Base: Home >
APIs > SOAP APIs > Tutorials > Ruby > Sample Files.
l echo.rb
l getTerminalDetails.rb

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 262
XML Samples
The online API schema contains XML samples for some commonly used
function calls:
l GetTerminalDetails
l GetTerminalUsage
l GetInvoice
l EditTerminal (change the SIM status)
l EditTerminal (change the rate plan)
l GetModifiedTerminals
l GetTerminalUsageDataDetails
l UpdateSecureSimCredentials

You can view the samples in the Knowledge Base: Home > APIs >
SOAP APIs > XML Samples.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 263
SOAP Error Messages
Error Code Message

General

10000 Wildcard search is too general

10001 Maximum size exceeded

Devices

100000 Device error

100100 Device not found.

The ICCID doesn't exist in the caller's account. This type of
error can occur when you try to use a sandbox account to
access a production device.

100200 Invalid device change type

100300 Invalid edit terminal request

100400 Invalid device(s) specified

100401 Invalid device ID specified

100500 Offer not found

100501 Invalid offer

100510 Campaign not found

100520 Invalid rate plan

100101 Invalid ICCID

Billing

200000 Billing error

200100 Invoice does not exist

200200 No device usage found

Admin

300000 Admin error

300100 Invalid Qcode

300200 Invalid account name

300201 Account name not unique

300300 Invalid email

300301 Email not unique

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 264
 Error Code Message

API

400000 API error

400100 Invalid license key. Please use a valid API license key.
Make sure you're using the correct license key for the
current environment. Sometimes people mistakenly use
their sandbox license key on the production site or vice
versa.

400101 License has exceeded the rate limit for API calls.

400200 Security validation error. Your username or password is

incorrect.
Make sure you're using the right credentials for the
current environment. Sometimes people mistakenly use
their apitest credentials on the production site or vice
versa.

400201 Access violation error. Please check your login; you may
be trying to access a device that belongs to a different
account or service provider.
This error can happen if the caller has accounts with
multiple operators and they're using the login from the
wrong operator.

400300 System internal error

400400 Too many entries

400500 Invalid ICCID

SMS

500000 SMS error

500100 From Date greater than To Date

500200 Too many entries

500300 SMS message not found

500400 Message text null

500500 Message text greater than 160 characters

500600 Send message failure

500700 Device not active

500800 Decoding error

500900 Decoded message text null

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 265
 Error Code Message

Network Access Config (also called a Communication Plan)

800000 Network Access Config not found

800100 Invalid edit Network Access Config request

Messaging

900100 No active session

900101 Protocol not supported

900102 Invalid port

900103 Communication failed

900104 Communication timeout

Accounts

1000100 Account not found

1000400 Too many accounts

1000500 Service provider not found

1000501 Could not create account

1000502 Internal Error - default trial communication plan not found

for service provider

1000503 Internal Error - default trial rate plan not found for
service provider

1000504 Account already exists

1000505 Invalid region ID

1000506 Default communication plan not found for service provider

1000507 Operator Account ID is not unique; multiple accounts

found.

1000508 Cannot transfer device to this account

1000509 Cannot transfer device to the same account

1000510 Cannot transfer device when one of the accounts is an

inventory account

Edit Device Rating

1100100 Edit device rating error

1100200 Term end date must be greater than term start date

1100300 Renewal rate plan is blank

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 266
 Error Code Message

1100400 Renewal rate plan is not valid for the device

1100500 Renewal mode is not valid

1100600 Access denied. Cannot edit term start and end dates

1100700 Failed to remove rate plan from queue

1110100 Add device renewal error

LinePayStatus

1120100 Edit LinePayStatus error

1120101 Invalid LinePayStatus parameter

1120102 Invalid operation for SimStatus is Purged

1120104 No terminals associated with Operator Account ID

Event Plans

1200100 Invalid event name

1200200 Event instance not found

1200300 Event instance started already

Connection Manager

1300100 Configuration file not found

1300200 Failed to upload diagnostics data

1300300 Invalid sequence number

Users

1400100 Try a different user name.

1400101 Customer not found

1400102 Role not found

1400103 Could not create user

1400104 Control Center uses this error message for an invalid

password and an invalid IP address:
l The password is invalid.
l IP address restriction failure.

1400105 Invalid authentication token

1400106 Not authorized to create this role

1400107 Peered user information must be specified

1400108 Account not peered

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 267
 Error Code Message

1400109 User not found

1400110 Could not delete user

1400111 Could not reset user password

Passwords

1400133 Password should not contain user name

1400134 Password contains consecutively repeated alphanumeric

characters that exceeds the maximum

1400135 Password contains alphanumeric sequence that exceeds

the maximum

1401001 Illegal characters in password

1401002 Password length less than the required minimum

1401003 Password length more than the maximum

1401004 Contains fewer alphabetic characters than the required

minimum

1401005 Contains more alphabetic characters than the maximum

1401006 Contains fewer numeric characters than the required

minimum

1401007 Contains more numeric characters than the maximum

1401008 Contains fewer special characters than the required

minimum

1401009 Contains more special characters than the maximum

1401010 Password matches one of the previous passwords

1401011 Contains fewer uppercase characters than the required

minimum

Vault

1500100 IMSI not found

1500200 Start Date is not before End Date

Rate Plans

1600100 Invalid rate plan or not a wholesale rate plan

Communication Plans

1700100 Invalid communication plan

1700101 Invalid APN

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 268
 Error Code Message

1700102 Invalid IP address

Global SIM

1800100 Unknown

1800101 Global SIM not found

1800102 Global partner not found

1800103 Invalid GlobalSimTransferId in the request

1800104 Invalid transfer request. Primary ICCID hasn't been

transferred to any partner.

1800105 ICCID already has a global transfer pending.

1800106 ICCID doesn't have any pending Global Transfer request.

1800107 Global Alliance not found.

1800108 Target operator doesn't exist.

1800109 Target Global SIM subscription information not found.

1800110 Account mapping not defined for Global SIM transfer.

1800111 Global SIM is in invalid state for Global SIM transfer.

1800112 Target subscription is already in use.

1800113 G&D IMSI swap failed for the Global SIM.

1800114 Cisco IMSI swap failed for the Global SIM.

1800115 Global SIM not live

1800116 Global SIM transfer can't be cancelled for the SIM at this
stage.

1800117 Global SIM target subscription partially in use.

1800118 Global SIM target IMSI already in use.

1800119 Target SIM not present in expected account.

1800120 Subscription already associated with a chip.

1800121 No free slots found for chip.

1800122 Selected slot is not found for chip.

1800123 Selected slot is occupied for chip.

1800124 The provided login session is not valid.

1800125 The login session has expired, please re-authenticate.

1800126 The user is not authorized to perform the operation.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 269
 Error Code Message

1800127 The user could not be found.

1800128 The provided password is not valid.

1800129 The user is blocked.

1800130 The user is expired.

1800131 Too many failed login attempts, user is now blocked.

1800132 Invalid request, duplicate messageId used.

1800133 Global SIM has always roaming reimsi rule associated

with it.

1800134 Target Global SIM subscription mapping cannot be

created.

1800135 Global SIM transfer type not specified.

1800136 Global SIM has already been transferred.

1800138 No suitable target subscription found in the inventory pool

of the target account.

1800139 SIM Profile with given External Profile ID does not exist.

1800140 Target SIM does not exist.

1800141 Source SIM cannot be prepared for Global SIM transfer.

1800142 Source SIM cannot be un-prepared on failed Global SIM

transfer.

1800143 Global SIM Profile mapping does not exist.

1800144 Target Global SIM subscription mapping does not exist.

1800145 The SIM is not of a valid Global SIM type.

1800146 Target SIM cannot be prepared for reverse Global SIM

transfer.

1800147 Target SIM cannot be un-prepared on failed reverse Global

SIM transfer.

1800148 Read timeout while invoking transfer scheduling API.

1800149 Connection timeout while invoking transfer scheduling API.

1800150 Error while invoking transfer scheduling API.

1800160 Error in changing SIM State.

1800161 Target SIM cannot be created for Global SIM transfer.

1800162 Source SIM cannot be deactivated for Global SIM transfer.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 270
 Error Code Message

1800163 Target SIM cannot be activated for Global SIM transfer.

1800164 Global SIM is in invalid state for reverse Global SIM

transfer.

1800165 Target SIM creation cannot be un-done on failed Global

SIM transfer.

1800166 Global SIM transfer can't be resumed because it has

already been scheduled for cancel.

1800167 Invalid cancel request. ICCID has no FAILED transfer

associated with it.

1800168 G&D subscription cleanup failed for the Global SIM.

1800169 Internal configuration error in setting up the API

invocation, please contact customer support.

1800170 The OTA Algorithm chosen for this partner is not

supported. Please choose a different partner that supports
G&D OTA algorithm.

1800171 Global SIM Transfer to Agency partners is not supported

for now.

1800172 Global SIM target MSISDN assignment failed.

1800173 Can not get the acctBillSetting according to the ICCID.

1800174 Partner MSISDN Assignment API invocation limit reached.

1800175 Partner MSISDN Assignment API invocation failed.

1800176 G&D API authentication error: failed to verify password.

1800177 Could not update MSISDN on the Subscription, either IMSI

is wrong or Subscription is locked due to Subscription
Management activity.

1800178 Target Subscription is already associated with this chip.

1800179 Card Profile for the chip is not allowed by profile whitelist
associated with the subscription.

1800180 Could not reserve the virtual subscription for a slot of the
chip.

1800181 There is already an ongoing transaction for the chip.

1800182 Unhandled exception in G&D server.

1800183 Either IMSI or CustomerId is wrong, or IMSI is not

associated with a Chip

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 271
 Error Code Message

1800184 Not possible to perform the operation on the subscription

due to its wrong state.

1800185 Target virtual-subscription does not exist in G&D.

1800186 The target virtual-subscription either does not exist in

G&D or cannot be imported from partner server.

1800187 The primary subscription does not exist in G&D.

1800188 The Account Custom Field or Operator account ID should

not be null while making SolicitarSWAP request.

1800189 The request to the Target operator's NMS for MSISDN

assignment was not successful, and the swap has Failed.

1800190 The eUICC ID for the SIM is not found.

1800191 The request to the Target operator's NMS for MSISDN

assignment timed out, and the swap has Failed.

1800195 The G&D API invocation failed.

1800601 The SIM has a fixed IP Address.

1800211 The SIM is in an invalid state for InterSP Transfer.

1800215 There is no inventory account associate with the target

SIM operator.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 272
SOAP API/Role Matrix
Control Center provides different API access for different user roles. For
details, take a look at the API/Role matrix. You can download the matrix
from the Downloads page in the Knowledge Base. The SOAP APIs appear
on the second page.

SOAP API Troubleshooting Checklist

You can quickly troubleshoot API issues and identify the main points of
failure by answering the questions in the following checklist. If you answer
Yes, continue to the next question, unless the instructions tell you
otherwise. If you answer No to a question, you've found the problem.
Follow the instructions for correcting the issue.

Sandbox APIs. When troubleshooting API issues, keep in mind that the
sandbox APIs do not migrate to the production environment.

API Setup and Access

1. Is the URL correct?
Make sure you're using the correct URL with the HTTPS protocol. You
can find the API server URL on the APIs > SOAP APIs page in the

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 273
 Knowledge Base. In production environments, make sure you replace
the sandbox URL with the production URL. Production URLs must use
the full path URL, for example:
https://api.jasper.com/ws/service/echo
2. Is the API license key valid?
Each account has one license key that you can find on the APIs > SOAP
APIs page in the Knowledge Base. You will need to use a separate
license key for the sandbox environment and the production
environment. When you get access to the sandbox, you receive a license
key. See Authentication on page 238.
3. Does the API user have login access?
Each time you use an API function call, you must supply a user name for
a user who is allowed to perform that function. You may need multiple
user roles as there is no single role that will guarantee access for all API
function calls. Cisco recommends creating a dedicated user or group of
users whose sole purpose is to execute API functions. For more
information about user roles and access, see SOAP API/Role Matrix on
the previous page.
4. Is the password/API key valid?
In addition to the user name and license key, every API call must have
either a password or an API key for authentication purposes. Ensure
that you're using the correct value.
5. Does the API user have feature access?
If the API user has access to the web interface, log into Control Center
and try to access the same feature in the web interface. (Remember the
Control Center password is different from the API key.) If you can make
the feature work in the web interface, you can make it work via API.
6. Is the SSL certificate valid and included in your trusted store?
The Cisco API server uses an SSL certificate signed by a top tier
Certificate Authority (CA) to handle HTTPS access. We recommend that
you include the root certificate in your trust store (this is included by
default on many platforms) and use a CA-based chain of trust, rather
than hard coding the Cisco certificate in your API code. For more
information see, SOAP API Code Standards on page 238.

API Coding
7. Do the SOAP tags in the request specify valid definitions?
Verify that the SOAP envelope tag specifies the Cisco schema. Also, make
sure the SOAP header tag contains the correct username and password
definitions. The correct license key should be included in the SOAP body

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 274
 tag. A separate license key is used for the sandbox environment and the
production environments. The body tag should also include any method
calls and parameter values. For more examples of valid XML used in
common API calls, see XML Samples on page 263.

<!-- Description of API call -->

<soapenv:Envelope xmlns:sch="http://api.jasperwireless.com/ws/schema"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsse:UsernameToken wsu:Id="UsernameToken-16847597"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd">
<wsse:Username>username</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-
200401-wss-username-token-profile-1.0#PasswordText">password</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
<sch:API call>
<sch:messageId>?</sch:messageId>
<sch:version>?</sch:version>
<sch:licenseKey>xxxxxxx-xxxx-xxxx-xxxx-xxxx</sch:licenseKey>
<sch:iccid>device ID</sch:iccid>
</sch:API call>
</soapenv:Body>
</soapenv:Envelope>

8. Does the API request coding follow the code standards and best
practices?
When coding with Cisco APIs, we recommend that you follow these
standards:
l Limit the number of active calls to one at a time and avoid
concurrent API processing.
l Do not exceed the calls per second limit.
l Use pagination controls to limit the number of returned records.
l Use UTC date and time formats. Pass a null value for a scheduled
task to take effect immediately.
l Specify a message ID in each request. Control Center includes the
message ID as the correlation ID in the response. You can use these
IDs to match the function requests with the corresponding
responses.
l Limit input arrays to 50 input items. Be aware that an error occurs
only when every item in the array is invalid. For example, if you
supply an array of four ICCIDs where one of the ICCIDs is invalid,
Control Center will return data for the three valid ICCIDs and no
error for the fourth.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 275
 l Be aware that the version number in the request is optional and
refers to the version of the API. The maximum length is 100
characters.
For more details, see SOAP API Code Standards on page 238 and API
Policies and Best Practices on page 7. If you receive an error code
related to the API request, see SOAP Error Messages on page 264 for a
complete list of error descriptions.

9. Does the API response coding follow the code standards and
best practices?
After checking your network connection to Control Center, review your
receiver code and error handling.
l Design your code to allow for additional unexpected items in the
response. Cisco may add additional return values to the APIs.
l Be aware that the build ID in the response indicates the current
Control Center build number. This value has a maximum length of
100 characters.
l Be aware that the version number in the response indicates the
current version of Control Center. The maximum length is 100
characters.
l Be aware that Control Center includes the message ID as the
correlation ID in the response. You can use these IDs to match the
function requests with the corresponding responses.
For more information see, SOAP API Code Standards on page 238. If
you receive an error code related to the API response, see SOAP Error
Messages on page 264 for a complete list of error descriptions.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 276
 10. Is the API code able to process standard SOAP fault elements
from Control Center?
When a SOAP fault occurs, Control Center returns a detail element in
the response body element that contains the standard fault elements
(faultCode, faultString, and faultActor). The maximum length for these
fields is 100 characters.

Fault Element Field Description

faultCode Standard value defined by the W3C, such as

"SOAP-ENV:Server". It is always 100 characters
or less.

faultString Control Center error code, for example

"200100". See SOAP Error Messages on page 264
for details. This string is always 100 characters
or less.

faultActor Currently unused by Control Center.

detail An XML structure containing the error details,

intended for troubleshooting purposes. See an
example below. This can have an arbitrary
length depending on the error. It is optional for
customers to process, so they can ignore the
field (or truncate at a certain number of
characters) as needed.

<detail>
<jws:requestId xmlns:jws="http://api.jasperwireless.com/ws/schema">
AM6Sm6OiMPqsiF2T
</jws:requestId>
<jws:error xmlns:jws="http://api.jasperwireless.com/ws/schema">
No terminal usage found
</jws:error>
<jws:exception xmlns:jws="http://api.jasperwireless.com/ws/schema">
com.jasperwireless.ws.ApiException
</jws:exception>
<jws:message xmlns:jws="http://api.jasperwireless.com/ws/schema">
iccid=12345
</jws:message>
</detail>

API Results and Performance

11. Did the API call complete without an error code related to API
access?
Control Center supports a wide variety of error codes to help clarify
function call usage. The most common access-related errors are shown
below.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 277
 Error Code Description/Corrective Actions

100100 Terminal not found. The requested ICCID does not

exist. Make sure the API call environment has access to
the device.

400100 Invalid license key. Sometimes API users enter the

sandbox license on the production site or vice versa.
Verify the API license key.

400101 License has exceeded the rate limit for API calls. This
error indicates that your account exceeded calls per
second limit. Cisco may curtail API usage by returning
error responses for any subsequent API calls within the
measurement period (one second).

400200 Security validation error. This error commonly occurs

when an API call uses the sandbox credentials on the
production site or vice versa. Verify the correct
username and password for the environment.
For C# API calls, this error indicates an incorrect or
missing SOAP security header. Add the
SecurityHeader.cs file to your project and add
SoapHeaderAttribute("securityHeader") to every
method that is called.

400201 Access violation error. This error typically occurs

when the API user does not have access to the device
or device attribute, such as a communication plan.
Verify user access to the device or attribute. If the
caller has accounts with multiple operators, verify the
login is from the right operator. If the error persists,
check the XML syntax with an XML validation tool.

1000504 Error creating account <account_name>. The entered

account name already exists. Enter a different account
name.

For a complete list of error descriptions, see SOAP Error Messages on

page 264.
12. Did the API call return the expected results?
You can use a web services testing tool, such as SOAP UI, to set up and
run API function tests and test suites to verify variable values at
different stages of the API execution. Also, keep in mind that the role of
the API user determines the features and data that the API call can
access and return. If you receive an error code related to the returned
data, see SOAP Error Messages on page 264 for a complete list of error
descriptions.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 278
 13. Did the API call return data with the expected performance?
Follow these standards to improve Control Center API performance.
l Limit the number of active calls to one at a time and avoid
concurrent API processing.
l Do not exceed the rate limit for API calls. Otherwise, you may receive
error code 400101: License has exceeded the rate limit for API calls.
l Align the timing of your API calls with the frequency of your
operator's record updates. For example, if your operator updates
their usage information once per 6 hours, there's no need to request
the information via API more often than once per 6 hours.
l Be aware that the API calls are not intended to provide real-time
monitoring of service usage. For more immediate feedback when
certain conditions occur, use automation rules and push APIs.
You can poll API calls that return small amounts of data, such as
GetModifiedTerminals, more frequently (once per minute, if necessary)
without affecting the overall performance of Control Center. For more
details about API performance recommendations and coding practices,
see SOAP API Code Standards on page 238.

If you haven't been able to identify the cause of the API issue, contact Cisco
Product Support.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 279
 Chapter 3

PUSH APIS
Control Center also maintains a “push API” system that sends a
programmatic notification to your application whenever a certain event
occurs. For example, you might choose to receive notification when a device
nears its data limit. Or, you might want to know if a device makes too many
connections during a certain period of time.
To receive a notification, you must create an automation rule in Control
Center and then configure it to send an API message. For this process to
work, you need to set up a push receiver, or server, on your end to listen
for messages, interpret the data, and then act on it appropriately.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 280
Typical Event Sequence
Here is the typical sequence of events for push APIs:

Step 1: You Define an Automation Rule

First, you create an automation rule with the push API action. Using the
rule creation pop-up (Automation > Rules >Actions menu > Create New
button), find the rule that monitors the activity you’re interested in. For
example, you may want to receive notification when an activated device
using a particular rate plan has failed to make a connection for more than
24 hours. Then, you instruct Control Center to send notification via the
push API.
Depending on the URL you enter, Control Center will send the notification
using either the HTTP or HTTPS protocol. For increased security, we
recommend using HTTPS in the URL.

Step 2: Control Center Sends a Push API

When all the conditions of your automation rule are met, Control Center
sends a message via push API to the server whose URL you specified in the
rule settings. If a time-out occurs or your server returns a status code other
than 200, Control Center will wait a few minutes and resend the message.
Control Center will retry each notification a maximum of 20 times (with
exponential back-off between attempts) before giving up. Be aware that the
Cisco operations team may reduce the maximum number of retries during
peak loads or error conditions in order to protect the network.

Step 3: You Verify the Signature (Optional)

You can add another level of security to the communication by
implementing a Push API Shared Secret. In your account profile (Admin >
Account Profile > Edit button), you can specify a string that Control Center
will encrypt and include in the message. When you receive a message, you
decrypt the signature and verify that it matches the original value. See
Implementing a Push Receiver on the facing page for detailed instructions.

Step 4: You Process the Data

Then, you can parse the data in the message and take the appropriate
action. In some cases that action might involve using the pull APIs to
change values in the Control Center database. For the connectivity example,
you might deactivate the device until a technician can diagnose the issue.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 281
Implementing a Push Receiver
To receive push API notifications, you must implement a simple receiver
(for example, a Java servlet) that understands HTTPS or HTTP POST
requests — depending on which protocol you specify in the URL.

Push API Notification Format

Each push API notification is an HTTPS/HTTP POST with the following
URL-encoded form parameters:

Parameter Description

eventId A unique identifier for the event that remains the same even if
the same event is re-sent multiple times due to network
problems, server downtime, and so on. See Retry Handling on the
next page.

eventType The type of event, such as "SESSION_START" or "SESSION_STOP".

See Push API Reference on page 290 for the event type
corresponding to each push API.

timestamp The request time in UTC, such as: 2009-12-10T01:16:20.026Z.

signature An HMAC SHA2 hash of the timestamp using the API shared
secret, which can be used to verify the identity of the caller. See
Signature Verification (Optional) on the next page.

data The XML content, specific to the event type. For Session Start
and Session End, we use SessionInfoType. Refer to Push API
Reference on page 290. Here is a sample of the XML data content
for a Session End event:
<Session xmlns="http://api.jasperwireless.com/ws/schema">
<iccid>8901650500000002918</iccid>
<ipAddress>10.98.214.86</ipAddress>
<dateSessionStarted>2009-12-
10T01:16:20.026Z</dateSessionStarted>
<dateSessionEnded>2009-12-10T01:16:25.026Z</dateSessionEnded>
</Session>

For a notification sample, see Sample Push API Message on page 285.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 282
 Signature Verification (Optional)
To verify that the request came from a trusted caller (such as Cisco), you
can independently construct the signature using your Push API Shared
Secret and confirm that it matches the signature in the request. You
configure the Push API Shared Secret in your account profile (Admin >
Account Profile > Edit button). Be aware that the Push API Shared Secret is
a secret value, 1-100 characters in length, that you choose. It is different
from the API license key.
To construct the signature, you take the bytes of the timestamp and apply a
standard HMAC SHA2 hash using your shared secret as the key. See the
sample code for an example. If the signatures don’t match, you should not
process the event. Instead, you should respond with the HTTP status code
“403 Forbidden”.

Data Processing
After parsing the notification, you can take the appropriate action in your
system, such as inserting the event into a database. You might also call the
Cisco APIs to take related actions on the device, such as changing the SIM
state.
Once you have successfully processed the notification, respond with the
HTTP status code “200 OK”. If you return any other status code, Control
Center will retry the notification.

Backward Compatibility. From time to time Cisco may make changes to

the format of the push API notifications. Follow the best practices outlined
in Backward Compatibility on page 10 to ensure that your parsing code can
handle any format changes.

Retry Handling
Although we expect your receiver to be up-and-running most of the time,
Control Center provides an automatic retry mechanism to recover from
temporary downtime or errors. If Control Center gets a time-out or a status
code other than 200 when contacting your receiver, Control Center will
wait a few minutes and then re-send the notification. Control Center will
retry each notification a maximum of 20 times (with exponential back-off
between attempts) before giving up.
After attempting the maximum number of tries, Control Center drops the
message. If the failure state persists, Control Center will disable the rule.
Control Center does not resend dropped messages; these messages are not
recoverable. Be aware that the Cisco operations team may reduce the
maximum number of retries during peak loads or error conditions in order
to protect the network.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 283
 SSL Certificate
In the automation rule interface, you can supply an HTTP or HTTPS URL as
a destination for the push API. If you use an HTTPS URL, that URL must
have an SSL certificate signed by one of the common trusted Certificate
Authorities (CA). Ensure that all certificates in the chain are current and
signed, and the host name matches the certificate. You may use a third
party tool to validate the certificate setup.

Sample Code
The receiver can be written in any language that supports HTTP requests,
such as Java, C#, or PHP. See the Java sample code in the
pushApiJavaSample.zip file that you can download from the Knowledge
Base (APIs > Push APIs > Implementing a Push Receiver > Sample Code).
This archive contains a basic push receiver that prints out the events that it
receives. Sample output:

Received message from: [ip address]

timestamp=2010-01-07T01:20:55.685Z
eventId=SESSION_START-123
data=<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Session xmlns="http://api.jasperwireless.com/ws/schema">
<iccid>8901311242888845458</iccid>
<ipAddress>12.34.56.78</ipAddress>
<dateSessionStarted>2010-01-07T01:20:55.200Z</dateSessionStarted>
<dateSessionEnded>2010-01-07T01:20:55.200Z</dateSessionEnded>
</Session>
eventType=SESSION_START
signature=8DYYAlzX5TbzChTK/qpMWdi8flA=
===== Push event: session started for ICCID 12345 at 2010-01-07T01:20:55.200Z

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 284
Sample Push API Message
Here is a sample push API message generated by the SIM Custom Field
Change rule. All messages have similar headers. See the Push API Reference
on page 290 for the format of the data returned in each message.

Time: Wed, 01 Jul 15 04:00:04 -0700

Source ip: 218.107.13.5

Headers (Some may be inserted by server)

REQUEST_URI = /post.php
QUERY_STRING =
REQUEST_METHOD = POST
GATEWAY_INTERFACE = CGI/1.1
REMOTE_PORT = 45639
REMOTE_ADDR = 218.107.13.5
HTTP_CONNECTION = close
HTTP_HOST = posttestserver.com
CONTENT_TYPE = application/x-www-form-urlencoded>
CONTENT_LENGTH = 591
>UNIQUE_ID = VZPINNBx6hIAAGozNLkAAAAG
REQUEST_TIME_FLOAT = 1435748404.998
REQUEST_TIME = 1435748404

Post Parameters
key: 'eventId' value: 'SIM_CUSTOM_FIELD_CHANGE-151888917'
key: 'eventType' value: 'SIM_CUSTOM_FIELD_CHANGE'
key: 'timestamp' value: '2015-07-01T11:00:03.812Z'
key: 'signature' value: 'gBdsWXnCSllbu9uYktPY6bmu1RU='
key: 'signature2' value: '5F10RgcohjWBhlBP9h80w5i/jIiHJiv8eMsxRC+G+4I='
key: 'data' value: '<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><SimFieldChange
xmlns="http://api.jasperwireless.com/ws/schema"><iccid>8986061569000000161</
iccid><oldValue>testForPush1</oldValue><newValue>testForPush2</newValue><fie
ldName>OPERATORCUSTOM1</fieldName></SimFieldChange>'

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 285
SSL Certificates
To secure the communication between Control Center and your application
server, we recommend you use an HTTPS URL as the destination for the
push API information we send. When you use HTTPS, you must purchase
an SSL certificate and install it on your server. An SSL certificate encrypts
the data connection and provides identification for your server so Control
Center doesn't send sensitive data to the wrong location.
A certificate authority (CA) is an entity that issues SSL certificates and
ensures that the owner of the certificate is who they say they are. Control
Center accepts certificates from CAs in Cisco's trusted root store. When you
purchase a certificate it must come from a trusted CA or the trusted CA
must appear in the certificate's chain of trust.
A chain of trust refers to a series of certificates where one CA issues a
certificate to another CA who in turn issues a certificate to another CA and
so on. A chain of trust has a root certificate, multiple intermediate
certificates, and the final certificate for the domain requiring certification.
As long as the chain of trust associated with your SSL certificate contains
one of the CAs in Cisco's trusted root store, Control Center will accept your
SSL certificate.

Legacy CAs. Cisco will continue to support the CAs we have supported in
the past (see Legacy Trusted Certificate Authorities). However, we
encourage users to purchase new certificates from the Cisco-approved list.

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 286
 Tips for Purchasing SSL Certificates
l Talk to the CA vendor. Most CAs offer different types of
SSL certificates with varying levels of security. Before purchasing a
certificate from a CA on the list below, we recommend that you
contact the CA's support team and ask them to provide the chain of
trust for the certificate you plan to purchase. Verify that the chain of
trust contains a CA on the trusted list.
l Check the return policy. Make sure you purchase a certificate from
a CA with a reasonable return policy so you can get your money back
if if you happen to purchase a certificate Control Center doesn't
support. Many vendors offer a 15 or 30 day return policy.
l Validate the certificate. Test the certificate as soon as you receive
it. We recommend installing the certificate on a different server from
the one you're currently using so you don't disrupt a functioning
environment. Create a test rule with a push API action and specify the
location of the test server.
l Keep certificates current. SSL certificates expire. You'll need to
renew the certificate on a regular basis to ensure the push APIs
continue to function properly.

Cisco-Approved Certificate Authorities

For a list of Cisco-approved CAs, open the certificate authority spreadsheet
in the Knowledge Base. You'll find it on the Downloads page and in this
online topic (APIs > Push APIs > SSL Certificates > Cisco-Approved
Certificate Authorities). The list is updated on a quarterly basis.

Legacy Trusted Certificate Authorities

See below for a list of legacy trusted certificate authorities. Control Center
will continue to support these CAs. However, if you need to purchase a new
certificate, we recommend you purchase one from the Cisco-approved list.
The CAs below are shown alphabetically by alias.

Trusted Certificate Authorities

Alias: baltimorecodesigningca
Owner DN:
CN=Baltimore CyberTrust Code Signing Root,
OU=CyberTrust,
O=Baltimore, C=IE

Alias: baltimorecybertrustca
Owner DN:
CN=Baltimore CyberTrust Root,
OU=CyberTrust, O=Baltimore, C=IE

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 287
 Trusted Certificate Authorities

Alias: entrust2048ca
Owner DN:
CN=Entrust.net Certification Authority (2048),
OU=(c) 1999 Entrust.net Limited,
OU=www.entrust.net/CPS_2048 incorp. by ref. (limits liab.),
O=Entrust.net

Alias: entrustclientca
Owner DN:
CN=Entrust.net Client Certification Authority,
OU=(c) 1999 Entrust.net Limited,
OU=www.entrust.net/Client_CA_Info/CPS incorp. by ref. limits liab.,
O=Entrust.net, C=US

Alias: entrustglobalclientca
Owner DN:
CN=Entrust.net Client Certification Authority,
OU=(c) 2000 Entrust.net Limited,
OU=www.entrust.net/GCCA_CPS incorp. by ref. (limits liab.),
O=Entrust.net

Alias: geotrustglobalca
Owner DN:
CN=GeoTrust Global CA,
O=GeoTrust Inc., C=US

Alias: godaddyclass2ca
Owner DN:
OU=Go Daddy Class 2 Certification Authority,
O="The Go Daddy Group, Inc.", C=US

Alias: soneraclass1ca
Owner DN:
CN=Sonera Class1 CA,
O=Sonera, C=FI

Alias: soneraclass2ca
Owner DN:
CN=Sonera Class2 CA,
O=Sonera, C=FI

Alias: starfieldclass2ca
Owner DN:
OU=Starfield Class 2 Certification Authority,
O="Starfield Technologies, Inc.", C=US

Alias: verisignclass1ca
Owner DN:
OU=Class 1 Public Primary Certification Authority,
O="VeriSign, Inc.", C=US

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 288
 Trusted Certificate Authorities

Alias: verisignclass2ca
Owner DN:
OU=Class 2 Public Primary Certification Authority,
O="VeriSign, Inc.", C=US

Alias: verisignclass1g2ca
Owner DN: OU=VeriSign Trust Network,
OU="(c) 1998 VeriSign, Inc. - For authorized use only",
OU=Class 1 Public Primary Certification Authority - G2,
O="VeriSign, Inc.", C=US

Alias: verisignclass1g3ca
Owner DN:
CN=VeriSign Class 1 Public Primary Certification Authority - G3,
OU="(c) 1999 VeriSign, Inc. - For authorized use only",
OU=VeriSign Trust Network, O="VeriSign, Inc.", C=US

Alias: verisignclass2g2ca
Owner DN:
OU=VeriSign Trust Network,
OU="(c) 1998 VeriSign, Inc. - For authorized use only",
OU=Class 2 Public Primary Certification Authority - G2,
O="VeriSign, Inc.", C=US

Alias: verisignclass2g3ca
Owner DN: CN=VeriSign Class 2 Public Primary Certification Authority - G3,
OU="(c) 1999 VeriSign, Inc. - For authorized use only",
OU=VeriSign Trust Network,
O="VeriSign, Inc.", C=US

Alias: verisignclass3g2ca
Owner DN:
OU=VeriSign Trust Network,
OU="(c) 1998 VeriSign, Inc. - For authorized use only",
OU=Class 3 Public Primary Certification Authority - G2,
O="VeriSign, Inc.", C=US

Alias: verisignclass3g3ca
Owner DN: CN=VeriSign Class 3 Public Primary Certification Authority - G3,
OU="(c) 1999 VeriSign, Inc. - For authorized use only",
OU=VeriSign Trust Network,
O="VeriSign, Inc.", C=US

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 289
Push API Reference
This section contains reference information about each of the push APIs,
including the rules that call them, the format of the data contained in the
message, and the event type. The parser should look for the event type to
determine which rule caused the message.
The table below provides a quick summary of the rules and corresponding
push APIs.

Rule Push API

Available Static IP Address AvailableStaticIpAddress

Change of Cell ID LbsCellIdChange

Cycle To Date Data Usage CtdUsage

Cycle To Date Data Usage in a Zone CtdZUsage

Cycle To Date Voice Usage CtdVoiceUsage

Cycle To Date Voice Usage in a Zone CtdVoiceZUsage

IMEI Change SimImeiChange

IMEI Whitelist Action ImeiWhitelist

Monthly Pooled Data Usage MonthlyDataUsage

Monthly Pooled SMS Usage MonthlySmsUsage

Network Registration in a Zone NetworkRegistrationInZone

No connection NoConnection

Number of Session Connections (24 hours) TooManyDailyConnection

TooFewDailyConnection

Recent Data Usage (24 hours) Past24HDataUsage

Recent SMS Usage SmsUsage

Recent Voice Usage (24 hours) Past24HVoiceUsage

Registration in a Zone RegistrationInZone

Secure SIM SecureSimAlert

Session End Session

Session Start Session

SIM Account Change AccountTransfer

SIM Custom Field Change SimFieldChange

SIM Data Limit SimDataLimit

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 290
 Rule Push API

SIM Expiration SimExpiration

SIM MSISDN Change MsisdnChange

SIM Plan Completion SimPlanComplete

SIM Rate Plan Change SimRatePlanChange

SIM State Change SimStateChange

SMS-MO Received SmsMoReceived

Too many connections (Cycle to Date) TooManyCtdConnection

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 291
 AccountTransfer
Description
Contains detailed information about a device transferred from one account
to another.

Rule Name
SIM Account Change

Event Type
SIM_ACCOUNT_CHANGE

Source

<xs:complexType name="AccountTransferInfoType">
<xs:annotation>
<xs:documentation>
Detailed information about Account Transfer
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string" minOccurs="1"/>
<xs:element name="msisdn" type="xs:string" minOccurs="1"/>
<xs:element name="imei" type="xs:string" minOccurs="1"/>
<xs:element name="imsi" type="xs:string" minOccurs="1"/>
<xs:element name="previousSimState" type="xs:string" minOccurs="1"/>
<xs:element name="newSimState" type="xs:string" minOccurs="1"/>
<xs:element name="previousAccountId" type="xs:long" minOccurs="1"/>
<xs:element name="newAccountId" type="xs:long" minOccurs="1"/>
<xs:element name="previousAccountName" type="xs:string" minOccurs="1"/>
<xs:element name="newAccountName" type="xs:string" minOccurs="1"/>
<xs:element name="dateChanged" type="xs:dateTime" minOccurs="1"/>
<xs:element name="shippedDate" type="xs:dateTime" minOccurs="1"/>
<xs:element name="deferActionStartDate" type="xs:dateTime"/>
<xs:element name="deferActionPeriod" type="xs:int"/>
<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 292
 AvailableStaticIpAddress
Description
Specifies the total number of fixed IP addresses in a pool and determines
how many are still available for assignment.

Rule Name
Available Static IP Address

Event Type
AVAILABLE_STATIC_IP_ADDRESS

Source

<xs:complexType name="AvailableStaticIpInfoType">
<xs:annotation>
<xs:documentation>
The detail information about Available Static IP action
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="apnName" type="xs:string" minOccurs="1"/>
<xs:element name="totalNumberOfIpAddresses" type="xs:string"
minOccurs="1/>
<xs:element name="numberOfAvailableIpAddresses" type="xs:string"
minOccurs="1"/>
<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 293
 CtdUsage
Description
Contains cycle-to-date data usage information for the specified device
(ICCID).

Rule Name
Cycle To Date Data Usage

Event Type
CTD_USAGE

Source

<xs:complexType name="CtdUsageInfoType">
<xs:annotation>
<xs:documentation>
The information about SIM CTD Usage.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string"/>
<xs:element name="dataUsage" type="xs:string"/>
<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 294
 CtdVoiceUsage
Description
Contains cycle-to-date voice usage information for the specified device
(ICCID).

Rule Name
Cycle To Date Voice Usage

Event Type
CTD_VOICE_USAGE

Source

<xs:complexType name="CtdVoiceUsageInfoType">
<xs:annotation>
<xs:documentation>
The information about SIM CTD Voice Usage
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string"/>
<xs:element name="ctdVoiceMoUsage" type="xs:string"/>
<xs:element name="ctdVoiceMtUsage" type="xs:string"/>
<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 295
 CtdVoiceZUsage
Description
Contains cycle-to-date voice usage information in a zone for the specified
device (ICCID).

Rule Name
Cycle To Date Voice Usage in a Zone

Event Type
CTD_VOICE_ZUSAGE

Source

<xs:complexType name="CtdVoiceZUsageInfoType">
<xs:annotation>
<xs:documentation>
The information about SIM CTD Voice Usage in a zone.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string"/>
<xs:element name="ctdVoiceMoUsage" type="xs:string"/>
<xs:element name="ctdVoiceMtUsage" type="xs:string"/>
<xs:element name="zoneName" type="xs:string"/>
<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 296
 CtdZUsage
Description
Contains cycle-to-date data usage information in a zone for the specified
device (ICCID).

Rule Name
Cycle To Date Data Usage in a Zone

Event Type
CTD_ZUSAGE

Source

<xs:complexType name="CtdZUsageInfoType">
<xs:annotation>
<xs:documentation>
The information about SIM CTD Usage in a zone.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string"/>
<xs:element name="dataUsage" type="xs:string"/>
<xs:element name="zoneName" type="xs:string"/>
<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 297
 ImeiWhitelist
Description
Contains the IMEI value for a device that is not on the IMEI whitelist. Also
specifies whether Control Center blocked or allowed the data connection.

Rule Name
IMEI Whitelist Action

Event Type
IMEI_WHITELIST

Source

<xs:complexType name="ImeiWhitelistInfoType">
<xs:annotation>
<xs:documentation>
The detail information about Imei Whitelist action
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string" minOccurs="1"/>
<xs:element name="imsi" type="xs:string" minOccurs="1"/>
<xs:element name="msisdn" type="xs:string" minOccurs="1"/>
<xs:element name="accountName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="customerName" type="xs:string" maxOccurs="1"/>
<xs:element name="imei" type="xs:string" minOccurs="1"/>>
<xs:element name="whitelistAction" type="xs:string" minOccurs="1"/>
<xs:element name="dateAction" type="xs:dateTime" maxOccurs="1"/>
<xs:element name="simState" type="xs:string" maxOccurs="1"/>
<xs:element name="endConsumerId" type="xs:string" maxOccurs="1"/>
<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 298
 LbsCellIdChange
Description
Provides location information for a device.

Rule Name
Change of Cell ID

Event Type
LBS_CELL_ID_CHANGE

Source

<xs:complexType name="LbsCellIdChangeInfoType">
<xs:annotation>
<xs:documentation>
Location based service cell Id change Info for sim
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string" minOccurs="1"/>
<xs:element name="msisdn" type="xs:string" minOccurs="0" maxOccurs="1"/>
<xs:element name="date" type="xs:dateTime" minOccurs="1" maxOccurs="1"/>
<xs:element name="newCellId" type="xs:long" minOccurs="1" maxOccurs="1"/>
<xs:element name="newCellLAC" type="xs:int" minOccurs="1" maxOccurs="1"/>
<xs:element name="newServingMCC" type="xs:int" minOccurs="1"
maxOccurs="1"/>
<xs:element name="newServingMNC" type="xs:int" minOccurs="1"
maxOccurs="1"/>
<xs:element name="newAccuracy" type="xs:int" minOccurs="0"
maxOccurs="1"/>
<xs:element name="newCity" type="xs:string" minOccurs="0" maxOccurs="1"/>
<xs:element name="newState" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="newCountry" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="oldCellId" type="xs:long" minOccurs="0" maxOccurs="1"/>
<xs:element name="oldCellLAC" type="xs:int" minOccurs="0" maxOccurs="1"/>
<xs:element name="oldServingMCC" type="xs:int" minOccurs="0"
maxOccurs="1"/>
<xs:element name="oldServingMNC" type="xs:int" minOccurs="0"
maxOccurs="1"/>
<xs:element name="oldAccuracy" type="xs:int" minOccurs="0"
maxOccurs="1"/>
<xs:element name="oldCity" type="xs:string" minOccurs="0" maxOccurs="1"/>
<xs:element name="oldState" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="oldCountry" type="xs:string" minOccurs="0"
maxOccurs="1"/>
</xs:sequence>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 299
 MonthlyDataUsage
Description
Contains information about monthly billable data usage for pooled rate
plans.

Rule Name
Monthly Pooled Data Usage

Event Type
MONTHLY_DATA_USAGE_EXCEEDED

Source

<xs:complexType name="MonthlyDataUsageInfoType">
<xs:annotation>
<xs:documentation>
The information is about monthly billable data usage for pooled rate
plans
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="accountName" type="xs:string" minOccurs="1"
maxOccurs="1"/>
<xs:element name="zoneName" type="xs:string" minOccurs="1"
maxOccurs="1"/>
<xs:element name="ratePlanName" type="xs:string" minOccurs="1"
maxOccurs="1"/>
<xs:element name="totalIncludedZoneUsage" type="xs:decimal" minOccurs="1"
maxOccurs="1"/>
<xs:element name="totalActualZoneUsage" type="xs:decimal" minOccurs="1"
maxOccurs="1"/>
</xs:sequence>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 300
 MonthlySmsUsage
Description
Contains information about monthly billable SMS usage for pooled rate
plans.

Rule Name
Monthly Pooled SMS Usage

Event Type
MONTHLY_SMS_USAGE_EXCEEDED

Source

<xs:complexType name="MonthlySmsUsageInfoType">
<xs:annotation>
<xs:documentation>
The information is about monthly billable SMS usage for pooled rate
plans
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="accountName" type="xs:string" minOccurs="1"
maxOccurs="1"/>
<xs:element name="zoneName" type="xs:string" minOccurs="1"
maxOccurs="1"/>
<xs:element name="smsUsageType" type="xs:string" minOccurs="1"
maxOccurs="1"/>
<xs:element name="ratePlanName" type="xs:string" minOccurs="1"
maxOccurs="1"/>
<xs:element name="totalIncludedZoneUsage" type="xs:decimal" minOccurs="1"
maxOccurs="1"/>
<xs:element name="totalActualZoneUsage" type="xs:decimal" minOccurs="1"
maxOccurs="1"/>
</xs:sequence>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 301
 MsisdnChange
Description
Contains information about a device with a MSISDN change.

Rule Name
SIM MSISDN Change

Event Type
MSISDN_CHANGE

Source

<xs:complexType name="MsisdnChangeInfoType">
<xs:annotation>
<xs:documentation>
The detail information about msisdn change
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string" maxOccurs="1"/>
<xs:element name="imsi" type="xs:string" maxOccurs="1"/>
<xs:element name="imei" type="xs:string" maxOccurs="1"/>
<xs:element name="accountId" type="xs:long" maxOccurs="1"/>
<xs:element name="simState" type="xs:string" maxOccurs="1"/>
<xs:element name="customerName" type="xs:string" maxOccurs="1"/>
<xs:element name="endConsumerId" type="xs:string" maxOccurs="1"/>
<xs:element name="oldMsisdn" type="xs:string" maxOccurs="1"/>
<xs:element name="newMsisdn" type="xs:string" maxOccurs="1"/>
<xs:element name="accountName" type="xs:string" maxOccurs="1"/>
<xs:element name="dateChanged" type="xs:dateTime" maxOccurs="1"/>
<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 302
 NetworkRegistrationInZone
Description
Contains information about a device that registered in a given zone. If an
SS7 event on a GSM/GPRS network triggers the rule, then the GT Address
field will contain a value. If a Diameter event on an LTE network triggers
the rule, then the Host Name field will contain a value. Any client-side
program that processes the push notification must be able to handle these
two different fields.

Network type GSM/GPRS LTE

Protocol SS7 Diameter

Push API notification field gtAddress hostName

Rule Name
Network Registration in a Zone

Event Type
NETWORK_REGISTER_IN_ZONE

Source

<xs:complexType name="NetworkRegistrationInZoneInfoType">
<xs:annotation>
<xs:documentation>
Detailed information about SIM registration in a given zone
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string"/>
<xs:element name="accountName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="ratePlanName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="gtAddress" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="zoneName" type="xs:string"/>
<xs:element name="eventDate" type="xs:dateTime" minOccurs="1"/>
<xs:element name="hostName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
</xs:sequence>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 303
 NoConnection
Description
Contains information about a device with no connections within the given
period.

Rule Name
No connection

Event Type
SESSION_NO_CONNECTION

Source

<xs:complexType name="NoConnectionInfoType">
<xs:annotation>
<xs:documentation>
The information about a SIM has no connections within latest given
hours.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string" minOccurs="1"/>
<xs:element name="accountName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="ratePlanName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="evaluatingTime" type="xs:dateTime" minOccurs="1"/>
<xs:element name="noConnectionThreshold" type="xs:long" minOccurs="1"/>
</xs:sequence>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 304
 OrderCallback
Description
Contains detailed information about the SIM order.

Rule Name
Not applicable

Event Type
ORDER_CALLBACK_RESPONSE

Source

<xs:complexType name="OrderResponseType">
<xs:annotation>
<xs:documentation>
The detail information about the SIM Order
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:annotation>
<xs:documentation>
The push notification should contain orderId, orderStatus, acctID,
price and quantity.
</xs:documentation>
</xs:annotation>
<xs:element name="contactName" type="xs:string" minOccurs="0"/>
<xs:element name="contactPhone" type="xs:string" minOccurs="0"/>
<xs:element name="contactFax" type="xs:string" minOccurs="0"/>
<xs:element name="email" type="xs:string" minOccurs="0"/>
<xs:element name="orderId" type="xs:long" minOccurs="0"/>
<xs:element name="orderStatus" type="xs:string" minOccurs="0"/>
<xs:element name="orderDate" type="xs:dateTime" minOccurs="0"/>
<xs:element name="acctName" type="xs:string" minOccurs="0"/>
<xs:element name="po" type="xs:string" minOccurs="0"/>
<xs:element name="implementationDate" type="xs:dateTime" minOccurs="0"/>
<xs:element name="expedited" type="xs:string" minOccurs="0"/>
<xs:element name="acctId" type="xs:long" minOccurs="0"/>
<xs:element name="price" type="xs:decimal" minOccurs="0"/>
<xs:element name="quantity" type="xs:int" minOccurs="0"/>
<xs:element name="orderTotal" type="xs:string" minOccurs="0"/>
<xs:element name="desc" type="xs:string" minOccurs="0"/>
<xs:element name="opn" type="xs:string" minOccurs="0"/>
<xs:element name="operatorAcctId" type="xs:string" minOccurs="0"/>
<xs:element name="ratePlan" type="xs:string" minOccurs="0"/>
<xs:element name="communicationPlan" type="xs:string" minOccurs="0"/>
<xs:element name="shipStatus" type="xs:string" minOccurs="0"/>
<xs:element name="shipAddr1" type="xs:string" minOccurs="0"/>
<xs:element name="shipAddr2" type="xs:string" minOccurs="0"/>
<xs:element name="city" type="xs:string" minOccurs="0"/>
<xs:element name="stateRegion" type="xs:string" minOccurs="0"/>
<xs:element name="country" type="xs:string" minOccurs="0"/>
<xs:element name="postalCode" type="xs:string" minOccurs="0"/>
<xs:element name="methodAndShippingCompany" type="xs:string"
minOccurs="0"/>
<xs:element name="custAcctNo" type="xs:string" minOccurs="0"/>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 305
 <xs:element name="notes" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 306
 Past24HDataUsage
Description
Contains the ICCID and data usage for a device whose usage has exceeded a
specified amount within the past 24 hours.

Rule Name
Recent Data Usage (24 hours)

Event Type
PAST24H_DATA_USAGE_EXCEEDED

Source

<xs:complexType name="Past24HDataUsageInfoType">
<xs:annotation>
<xs:documentation>
The information about SIM Past 24 hours Data Usage
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string"/>
<xs:element name="dataUsage" type="xs:string"/>
<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 307
 Past24HVoiceUsage
Description
Contains the ICCID and voice usage (both MO and MT) for a device whose
usage has exceeded a specified amount within the past 24 hours.

Rule Name
Recent Voice Usage (24 hours)

Event Type
PAST24H_VOICE_USAGE

Source

<xs:complexType name="Past24HVoiceUsageInfoType">
<xs:annotation>
<xs:documentation>
The information about SIM Past 24 hours Voice Usage
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string"/>
<xs:element name="dailyVoiceMoUsage" type="xs:string"/>
<xs:element name="dailyVoiceMtUsage" type="xs:string"/>
<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 308
 PremiumServiceOrderType
Description
Contains the information about operator-created Marketplace package
offerings. Control Center sends a notification when an enterprise user
orders an operator-created package from Marketplace.

Rule Name
Not applicable

Event Type
MARKETPLACE_THIRDPARTY_ORDER_RESPONSE

Source

<xs:complexType name="PremiumServiceOrderType">
<xs:annotation>
<xs:documentation>
It contains information about third-party provided Marketplace
orders.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:annotation>
<xs:documentation>
The push notification should contain information for all
Marketplace order push notifications for a third-party
package lifecycle, which includes Activation, Cancellation,
and Trial End notification.
</xs:documentation>
</xs:annotation>
<xs:element name="alertType" type="xs:string">
<xs:annotation>
<xs:documentation>
"NEW" : Order Created Alert
"CANCEL" : Order Cancelled Alert
"TRIALEND" : Order Trial period end Alert
"UNKNOWN" : Unknown
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="orderId" type="xs:long" minOccurs="0"/>
<xs:element name="acctId" type="xs:long" minOccurs="0"/>
<xs:element name="operatorId" type="xs:long" minOccurs="0"/>
<xs:element name="operatorAcctId" type="xs:long" minOccurs="0"/>
<xs:element name="orderStatus" type="xs:string">
<xs:annotation>
<xs:documentation>
"A" : Active
"C" : Cancelled
"P" : Processing
"T" : In Trial
"U" : Unknown state
</xs:documentation>
</xs:annotation>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 309
 </xs:element>
<xs:element name="acctName" type="xs:string" minOccurs="0"/>
<xs:element name="operatorName" type="xs:string" minOccurs="0"/>
<xs:element name="packageId" type="xs:long" minOccurs="0"/>
<xs:element name="packageName" type="xs:string" minOccurs="0"/>
<xs:element name="serviceType" type="xs:string" minOccurs="0"/>
<xs:element name="orderedBy" type="xs:string" minOccurs="0"/>
<xs:element name="acctPrimaryContactName" type="xs:string"
minOccurs="0"/>
<xs:element name="acctPrimaryContactEmail" type="xs:string"
minOccurs="0"/>
<xs:element name="quantity" type="xs:long" />
<xs:element name="orderDate" type="xs:dateTime">
<xs:annotation>
<xs:documentation>
Date and time when the Marketplace order was created for
the account.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="cancelledDate" type="xs:dateTime">
<xs:annotation>
<xs:documentation>
Date and time when the Marketplace order was cancelled for
the account.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="trialEnabled" type="xs:boolean" minOccurs="1"
maxOccurs="1"/>
<xs:element name="trialStartDate" type="xs:dateTime">
<xs:annotation>
<xs:documentation>
Date and time when the Marketplace order free trial starts
for the account.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="trialEndDate" type="xs:dateTime">
<xs:annotation>
<xs:documentation>
Date and time when the Marketplace order free trial ends
for the account.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="billStartDate" type="xs:dateTime">
<xs:annotation>
<xs:documentation>
Date and time of Account Billing start date.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="billEndDate" type="xs:dateTime">
<xs:annotation>
<xs:documentation>
Date and time of Account Billing end date.
</xs:documentation>
</xs:annotation>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 310
 </xs:element>
<xs:element name="customFields" type="PrmSvcOrderCustomFieldsType"
minOccurs="0" maxOccurs="5"/>
<xs:element name="errorMsg" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 311
 RegistrationInZone
Description
Contains information about a device that registered in a given zone.

Rule Name
Registration in a Zone

Event Type
REGISTER_IN_ZONE

Source

<xs:complexType name="RegistrationInZoneInfoType">
<xs:annotation>
<xs:documentation>
The detail information about SIM registered in a given zone
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string"/>
<xs:element name="accountName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="ratePlanName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="gtAddress" type="xs:string"/>
<xs:element name="zoneName" type="xs:string"/>
<xs:element name="eventDate" type="xs:dateTime" minOccurs="1"/>
</xs:sequence>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 312
 SecureSimAlert
Description
Contains the ICCID of a device with a Secure SIM credential mismatch.

Rule Name
Secure SIM

Event Type
SECURE_SIM

Source

<xs:complexType name="SecureSimAlertInfoType">
<xs:annotation>
<xs:documentation>
The information about Secure SIM credential mismatch.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string"/>
<xs:element name="dateAdded" type="xs:dateTime"/>
<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 313
 Session
Description
Contains session information for a particular device.
If the IP address uses the IPv4 format, it appears in the ipAddress field. If
the IP address uses the IPv6 format, it appears in the ipv6Address field.

Rule Name
l Session End
l Session Start

Event Type
l SESSION_STOP
l SESSION_START

Source

<xs:complexType name="SessionInfoType">
<xs:annotation>
<xs:documentation>
The detail information about SIM session.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string"/>
<xs:element name="ipAddress" type="xs:string"/>
<xs:element name="ipv6Address" type="xs:string" minOccurs="0"/>
<xs:element name="dateSessionStarted" type="xs:dateTime" minOccurs="1">
<xs:annotation>
<xs:documentation>
Date when the session started
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="dateSessionEnded" type="xs:dateTime" nillable="true"
minOccurs="1">
<xs:annotation>
<xs:documentation>
Date when the session ended (if applicable)
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 314
 SimDataLimit
Description
Contains information about a device on a prepaid rate plan that comes
close to using its included usage.

Rule Name
SIM Data Limit

Event Type
DATA_LIMIT

Source

<xs:complexType name="SimDataLimitInfoType">
<xs:annotation>
<xs:documentation>
The information about a SIM on a prepaid plan comes close to using
its included usage.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string" minOccurs="1" maxOccurs="1"/>
<xs:element name="accountName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="ratePlanName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="totalIncludedUsage" type="xs:decimal" minOccurs="0"
maxOccurs="1"/>
<xs:element name="totalActualUsage" type="xs:decimal" minOccurs="0"
maxOccurs="1"/>
</xs:sequence>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 315
 SimExpiration
Description
Contains information about a device on a prepaid rate plan that comes
close to the rate plan expiration date.

Rule Name
SIM Expiration

Event Type
EXPIRATION

Source

<xs:complexType name="SimExpirationInfoType">
<xs:annotation>
<xs:documentation>
The information about a SIM on a prepaid plan comes close to its
expiration date.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string" minOccurs="1" maxOccurs="1"/>
<xs:element name="accountName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="ratePlanName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="expirationDate" type="xs:date" minOccurs="0"
maxOccurs="1"/>
</xs:sequence>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 316
 SimFieldChange
Description
Contains information about a device with a change to a custom field.

Rule Name
SIM Custom Field Change

Event Type
SIM_CUSTOM_FIELD_CHANGE

Source

<xs:complexType name="SimFieldChangeType">
<xs:annotation>
<xs:documentation>
The detail information about a change in a SIM field
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string" minOccurs="1"/>
<xs:element name="oldValue" type="xs:string" minOccurs="1"/>
<xs:element name="newValue" type="xs:string" minOccurs="1"/>
<xs:element name="fieldName" type="xs:string" minOccurs="1"/>
<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 317
 SimImeiChange
Description
Contains the current and previous IMEI values for a device.

Rule Name
IMEI Change

Event Type
IMEI_CHANGE

Source

<xs:complexType name="SimImeiChangeInfoType">
<xs:annotation>
<xs:documentation>
The detail information about SIM Imei Change
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string" minOccurs="1"/>
<xs:element name="previousImei" type="xs:string" minOccurs="1"/>
<xs:element name="currentImei" type="xs:string" minOccurs="1"/>
<xs:element name="dateChanged" type="xs:dateTime" minOccurs="1"/>
<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 318
 SimPlanComplete
Description
Contains the rate plan name and expiration date for a device on a prepaid
rate plan whose term has just expired.

Rule Name
SIM Plan Completion

Event Type
PREPAID_PLAN_COMPLETION

Source

<xs:complexType name="SimPlanCompleteInfoType">
<xs:annotation>
<xs:documentation>
The information about Sim's prepaid plan end.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string" minOccurs="1" maxOccurs="1"/>
<xs:element name="accountName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="ratePlanName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="expirationDate" type="xs:date" minOccurs="0"
maxOccurs="1"/>
</xs:sequence>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 319
 SimRatePlanChange
Description
Contains the names of the old and new rate plans for a device whose rate
plan has just changed.

Rule Name
SIM Rate Plan Change

Event Type
SIM_RATEPLAN_CHANGE

Source

<xs:complexType name="SimRatePlanChangeInfoType">
<xs:annotation>
<xs:documentation>
The detail information about SIM Rate Plan Change
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string" minOccurs="1"/>
<xs:element name="oldRatePlanName" type="xs:string" minOccurs="1"/>
<xs:element name="newRatePlanName" type="xs:string" minOccurs="1"/>
<xs:element name="dateChanged" type="xs:dateTime" minOccurs="1"/>
<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 320
 SimStateChange
Description
For a device whose SIM state has changed, contains the prior and current
SIM state values.

Rule Name
SIM State Change

Event Type
SIM_STATE_CHANGE

Source

<xs:complexType name="SimStateChangeInfoType">
<xs:annotation>
<xs:documentation>
The detail information about SIM State Change
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string" minOccurs="1"/>
<xs:element name="previousState" type="xs:string" minOccurs="1"/>
<xs:element name="currentState" type="xs:string" minOccurs="1"/>
<xs:element name="dateChanged" type="xs:dateTime" minOccurs="1"/>
<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 321
 SmsMoReceived
Description
Contains information about a message sent by a device to a specific short
code. The SMPP data coding values are:
l 0 — Default Alphabet
l 1 — IRA/IA5 (CCITT T.50)/ASCII (ANSI X3.4)
l 3 — Latin 1 (ISO-8859-1)
l 4 — Octet unspecified (8-bit binary); message content is encoded
with Base64
l 8 — UCS2 (ISO/IEC-10646)

Rule Name
SMS-MO Received

Event Type
SMS_MO_RECEIVED

Source

<xs:complexType name="SmsMoReceivedInfoType">
<xs:annotation>
<xs:documentation>
The information about SMS MO received event. When the smppDataCoding
is 4, message content is encoded with Base64.
SMPP data coding:
0 Default Alphabet
1 IRA/IA5 (CCITT T.50)/ASCII (ANSI X3.4)
3 Latin 1 (ISO-8859-1)
4 Octet unspecified (8-bit binary)
8 UCS2 (ISO/IEC-10646)
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string" minOccurs="1" maxOccurs="1"/>
<xs:element name="accountName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="customerName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="msisdn" type="xs:string" minOccurs="1" maxOccurs="1"/>
<xs:element name="messageContent" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="smppDataCoding" type="xs:int" minOccurs="0"
maxOccurs="1"/>
<xs:element name="shortCode" type="xs:string" minOccurs="1"
maxOccurs="1"/>
<xs:element name="receivedTime" type="xs:dateTime" minOccurs="1"
maxOccurs="1"/>
</xs:sequence>
</xs:complexType>

The timestamp format is: yyyy-MM-ddTHH:mm:ss.SSSZ. For example:

2017-03-10T00:40:02.846Z

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 322
 SmsUsage
Description
Contains SMS usage information for a device.

Rule Name
Recent SMS Usage

Event Type
SMS_USAGE

Source

<xs:complexType name="SmsUsageInfoType">
<xs:annotation>
<xs:documentation>
The information about SMS Usage.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string" minOccurs="1" maxOccurs="1"/>
<xs:element name="accountName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="ratePlanName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="alertType" type="xs:string" minOccurs="1"
maxOccurs="1"/>
<xs:element name="totalDailySmsUsage" type="xs:decimal" minOccurs="0"
maxOccurs="1"/>
<xs:element name="totalCtdSmsUsage" type="xs:decimal" minOccurs="1"
maxOccurs="1"/>
</xs:sequence>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 323
 TooFewDailyConnection
Description
Contains information about the number of daily sessions for a device that
has connected less often than expected.

Rule Name
Number of Session Connections (24 hours)

Event Type
PAST24H_SESSION_USAGE_LESSTHAN

Source

<xs:complexType name="TooFewDailyConnectionInfoType">
<xs:annotation>
<xs:documentation>
The information about a SIM has fewer connections than expected in
trailing 24 hours.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string" minOccurs="1"/>
<xs:element name="accountName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="ratePlanName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="currentSessionUsage" type="xs:long" minOccurs="1"/>
<xs:element name="sessionUsageThreshold" type="xs:long" minOccurs="1"/>
</xs:sequence>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 324
 TooManyCtdConnection
Description
Contains information about a device with more connections than expected
in the current billing cycle.

Rule Name
Too Many Connections (Cycle to Date)

Event Type
CTD_SESSION_USAGE_EXCEEDED

Source

<xs:complexType name="TooManyCtdConnectionInfoType">
<xs:annotation>
<xs:documentation>
The information about a SIM has more connections than expected in the
current billing cycle.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string" minOccurs="1"/>
<xs:element name="accountName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="ratePlanName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="currentSessionUsage" type="xs:long" minOccurs="1"/>
<xs:element name="sessionUsageThreshold" type="xs:long" minOccurs="1"/>
</xs:sequence>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 325
 TooManyDailyConnection
Description
Contains information about the number of daily sessions for a device that
has connected more often than expected.

Rule Name
Number of Session Connections (24 hours)

Event Type
PAST24H_SESSION_USAGE_EXCEEDED

Source

<xs:complexType name="TooManyDailyConnectionInfoType">
<xs:annotation>
<xs:documentation>
The information about a SIM has more connections than expected in
trailing 24 hours.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="iccid" type="xs:string" minOccurs="1"/>
<xs:element name="accountName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="ratePlanName" type="xs:string" minOccurs="0"
maxOccurs="1"/>
<xs:element name="currentSessionUsage" type="xs:long" minOccurs="1"/>
<xs:element name="sessionUsageThreshold" type="xs:long" minOccurs="1"/>
</xs:sequence>
</xs:complexType>

© 2020 Cisco Systems, Inc. Cisco Confidential. All rights reserved. API User Guide 326