Edit Device Details

Description

Modifies device attributes such as SIM status, rate plan, communication plan, and custom fields for a specified device.

Resource URL

PUT rws/api/v{apiVersion}/devices/{iccid}

Request Parameters

Request Parameters and Descriptions
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. If you choose a future date, it cannot be more than 180 days in the future.
At least one of the following parameters is required
status	The device SIM status. For a list of valid values, see SIM Status Values.
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.
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. Users can edit this parameter in the API, but not in the web interface.
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. Users can edit this parameter in the API, but not in the web interface.
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. Users can edit this parameter in the API, but not in the web interface.
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. Users can edit this parameter in the API, but not in the web interface.
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.
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 and Description
Return Value	Description
iccid	A unique identifier for the device Control Center updated.

Request Example

Make sure to use your own user credentials. See Authentication for information about creating an authorization header.

json

Copy{curl -X PUT --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: Basic <YOUR-ENCRYPTED-CREDENTIALS>" -d "{
   \"status\": \"DEACTIVATED\"
}" "https://rws-jpotest.jasper.com/rws/api/v1/devices/9088217871987000001"

json

Copy{curl -X PUT --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: Basic <YOUR-ENCRYPTED-CREDENTIALS>" -d "{
   \"ipv6Address\": \"2003:2002:1001:114a::\",
   \"apn\": \"awt-v6-s1\",
   \"pdpId\": \"2098\"
}" "https://rws-jpotest.jasper.com/rws/api/v1/devices/9088217871987000001"

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.

json

Copy{ 
   "iccid": "9088217871987000001" 
}

Code Samples

Make sure to use the Control Center sandbox URL and your own user credentials.

ruby

javascript

python

Copy#!/usr/bin/ruby -w
require 'rest-client'
require 'json'
  
url = 'https://<your-base-URL>/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))

Copyvar request = require('request');
var body = [];
var auth = "Basic " + new Buffer("username:password").toString("base64");
request({
   method: 'PUT',
   url: 'https://<your-base-URL>/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);
     }
   }
)

Copy#!/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 Codes, HTTP Codes, and Descriptions
Error Code	HTTP Code	Error Message
10000001	401	Invalid credentials. Description: 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.
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. Description: 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.
10000517	400	The ipv4Address/ipv6Address is already in use, please assign a different one.
10030000	400	Cannot activate a SIM which is already activated.
20000001	404	Resource not found - Invalid ICCID.
30000001	500	Unknown server error.