Getting Started

For API development purposes, Control Center maintains a sandbox environment in DevNet that's completely separate from the production environment. If you decide to develop in the sandbox environment, you must submit an access request in DevNet.

DevNet will create an Advantage account containing virtual devices with historical data. These devices will continue to generate new data over time. Your user account gives you access to Control Center’s APIs but not the web interface. No other users will have access to your devices.

Making a Reservation

You must have a DevNet account in order to use the Control Center sandbox. A sandbox reservation provides access to the sandbox for 30 days, regardless of the duration setting. You can begin the reservation immediately or set a future start time, based on your needs. Follow these instructions to make a reservation:

1. Navigate to the Control Center sandbox. DevNet prompts you to log in if you haven't already.
2. On the sandbox page, click the RESERVE button in the upper right corner.
3. In the RESERVE pop-up, set the start date in the Schedule settings. Be aware that your Control Center account will remain active for 30 days from the start date, regardless of the duration specified in the reservation. Click the Reserve button to proceed.
4. (Optional) If you choose a future date for the reservation, you can check on the reservation status at any time by clicking the RESERVATIONS link at the top of the sandbox page.

Base URL

The Control Center REST API is securely available over HTTPS. The base URL for all functions in the sandbox is:

Copyhttps://rws-jpotest.jasper.com/rws/api/

If you use the APIs in a production environment, you can find your base URL in the Knowledge Base (APIs > REST APIs > Getting Started > Base URL).

User Access

The Control Center sandbox supports one user role: AccountAdmin. This account administrator has the authority to view and edit device information, such as SIM state, rate plan, and communication plan, and customers. Users with this role can also view rate plan usage, view and send SMS messages to a device, and manage customers.

When you request access to the sandbox, you receive credentials (user name and API key) for an Account Admin user. DevNet generates a random user name and adds the "Admin" suffix.

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=

For example, a Search Devices request with an authorization header might look like this:

Copycurl -X GET --header "Accept: application/json" --header "Authorization: Basic ZHB0cmlhbFVzZXIxOmQ3MDNmNTJiLTEyMDAtNDMxOC1hZTBkLTBmNjA5MmIyZTZhYg==" "https://rws-jpotest.jasper.com/rws/api/v1/devices?accountId=100020620&modifiedSince=2016-04-18T17%3A31%3A34%2B00%3A00&pageSize=50&pageNumber=1"

If you're using Curl, you can use the user parameter followed by your username and API key (--user <your-username>:<your-API-key>) instead of an authorization header. Curl automatically encrypts your credentials and generates the appropriate HTTP authorization header. For example:

Copycurl -X GET --header "Accept: application/json" --user <your-username>:<your-API-key>" "https://rws-jpotest.jasper.com/rws/api/v1/devices?accountId=100020620&modifiedSince=2016-04-18T17%3A31%3A34%2B00%3A00&pageSize=50&pageNumber=1"

Partial Response Use Case #1: One field

Syntax: fields=field1

Example: Get Device Details
https://rws-jpotest.jasper.com/rws/api/v1/devices/8988216716970004975?fields=status

Sample Response:

Copy{
   "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://rws-jpotest.jasper.com/rws/api/v1/devices/8988216716970004975?fields=
iccid,status,ratePlan

Sample Response:

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

Partial Response Use Case #3: Subfields

Syntax: fields=field1/subfield1,field1/subfield2

Example: Get Customer Details
https://rws-jpotest.jasper.com/rws/api/v1/customers/16716970?fields=
name,
billingAddress/addressLine1,
billingAddress/postalCode

Sample Response:

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

Partial Response Use Case #4: Subfields in an array

Syntax: fields=field1/subfield1,field1/subfield2

Example: Get Device Usage in a Zone
https://rws-jpotest.jasper.com/rws/api/v1/devices/89302720396916972826/usageInZone?fields=
iccid, cycleStartDate, cycleEndDate,
deviceCycleUsageInZones/ratePlan,
deviceCycleUsageInZones/ratePlanVersion,
deviceCycleUsageInZones/zone,
deviceCycleUsageInZones/dataUsage,
deviceCycleUsageInZones/dataUsageUnit

Sample Response:

Copy{
   "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"
      } 
   ]
}

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://rws-jpotest.jasper.com/rws/api/v1/customers/16716970?fields=
name,
contacts/name,
contacts/email,
billingAddress/*

Sample Response:

Copy{
   "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"
   }
}

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:

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

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).

The REST APIs use the following date and time formats for requests and responses.

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:

Copy{
   "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.

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.

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:

To maintain effective API performance for all Control Center users, Cisco recommends the following best practices for any client-side code that calls the Control Center APIs:

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:

• Removing or renaming an API, request parameter, response field, or enum value
• Changing the visible behavior of existing APIs

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:

• The API receives a backward-incompatible change AND
• 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.