PUT /devices/actions/goToState
Changes the provisioning state of one or more devices to a specified customer-defined service and state.
NOTE: This API method requires special account configuration, and it must be enabled for your organization before you can use it. You can contact Customer Support or your Verizon Sales Representative to learn about enabling this API method for your organization.
See also:
Get Services and States
You should be familiar with the M2M Service Provisioning Rules when working with device states.
You can specify a list of individual 4G devices, or work with all 4G devices in an account or device group.
ThingSpace sends an asynchronous goToState callback message for each device in the request when the request has been completed, or if there was a problem and the change failed.
All devices in the request are assumed to be in the same state as the first device in the request. If any of the other devices are not in the same state as the first device, an error will be returned in the callback for that device.
In addition to receiving goToState callback messages, you can use POST /devices/actions/list
to check the status of the device and POST /devices/history/actions/list
to see details of completed goToState requests.
PUT https://thingspace.verizon.com/api/m2m/v1/devices/actions/goToState
None.
The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token, and must set the content-type to JSON.
Parameter Name | Data Type | Description |
---|---|---|
Authorization required |
string | HTTP Authorization bearer token. |
VZ-M2M-Token required |
string | A valid session token returned by POST /session/login. |
Content-Type required |
string | Must be application/json . |
The request body identifies the devices that you want to push to a customer-defined state. You can either specify individual devices in the devices
parameter, or you can use the filter
parameters to work with devices that match the filter parameter values.
Parameter Name | Data Type | Description |
---|---|---|
devices optional |
array of deviceIds objects | Up to 10,000 devices that you want to push to a different state, specified by device identifier. NOTES
|
devices.deviceIds required for devices |
object | The type and value of the device identifiers for a single device. |
devices.deviceIds.kind devices.deviceIds.id required for deviceIds |
strings | The type (kind) and value (id) of the device identifier.
|
filter optional |
list of filter parameters | Parameter names and values that you want to use to select the devices to push to a new state, instead of specifyng individual devices. If you specify multiple parameters, they will be ANDed together so that only devices that match all of them will be changed. |
filter.accountName | string | The name of a billing account if you have access to multiple accounts and want to include devices in only one account. (An account name is usually numeric, and must include any leading zeros.) |
filter.groupName | string | The name of a device group, to only include devices in that group. |
filter.servicePlan | string | The name of a service plan, to only include devices with that service plan. |
filter.customFields | list of customfield objects | Custom field names and values, if you want to only include devices that have matching values. |
filter.customFields.key required for customFields filter |
string | The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5. |
filter.customFields.value required for customFields filter |
string | The value of the custom field. |
serviceName required |
string | The name of a customer-defined service to push the devices to. |
stateName required |
string | The name of a customer-defined stage state to push the devices to. |
servicePlan required |
string | The service plan code that you want to assign to all specified devices in the new state. Set this parameter to one of the code values returned by GET /plans/{accountname}. NOTE: Any devices in the request that are not supported by the service plan will not activate. For example, if the service plan is only for 4G devices, any 3G devices included in the goToState request will fail. |
CarrierIpPoolName optional |
string | The pool from which your device IP addresses will be derived if the service or state change requires new IP addresses. If you do not include this element, the default pool will be used. |
mdnZipCode required |
string | The Zip code of the location where the line of service will primarily be used, or a Zip code that you have been told to use with these devices. For accounts that are configured for geographic numbering, this is the ZIP code from which the MDN will be derived. |
groupName optional |
string | The name of a device group that the devices should be added to. (They will be in the default device group if you don’t specify one.) |
skuNumber optional |
string (20 characters max) | The Stock Keeping Unit (SKU) number of a 4G device type with an embedded SIM. Can be used with ICCID or EID device identifiers in lieu of an IMEI when activating 4G devices. The SkuNumber will be used with all devices in the request, so all devices must be of the same type. NOTE: Only 4G devices with embedded SIMs and EUICC devices can be activated by SKU at this time. |
customFields optional |
list of customField objects | The names and values of any custom fields that you want to set for the devices. |
customFields.key required for customFields |
string | The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5. |
customFields.value required for customFields |
string | The value of the custom field. |
publicIpRestriction optional |
string | For devices with static IP addresses on the public network, this specifies whether the devices have general access to the Internet. Valid values are “restricted” or “unrestricted”.
|
primaryPlaceOfUse optional |
object | The customer name and the address of the device’s primary place of use. Leave these fields empty to use the account profile address as the primary place of use. These values will be applied to all devices in the request. If the account is enabled for non-geographic MDNs and the device supports it, the primaryPlaceOfUse address will also be used to derive the MDN for the device. The Primary Place of Use location may affect taxation or have other legal implications. You may want to speak with legal and/or financial advisers before entering values for these fields. NOTE: Primary Place of Use may be required for some state changes. |
primaryPlaceOfUse.customerName required for primaryPlaceOfUse |
object | The customer name to be used for line usage taxation. |
primaryPlaceOfUse.customerName.title optional for customerName |
string | An optional title for the customer, such as “Mr.” or “Dr.” |
primaryPlaceOfUse.customerName.firstName required for customerName |
string | The customer’s first name. Valid values are any string of up to 20 alphanumeric characters, space, dash, exclamation point, and pound sign. |
primaryPlaceOfUse.customerName.middleName optional for customerName |
string | The customer’s middle name. |
primaryPlaceOfUse.customerName.lastName required for customerName |
string | The customer’s last name. Valid values are any string of up to 25 alphanumeric characters, space, dash, exclamation point, and pound sign. |
primaryPlaceOfUse.customerName.suffix optional |
string | An optional suffix for the customer name, such as “Jr.” or “III.” |
primaryPlaceOfUse.address required for primaryPlaceOfUse |
object | The customer address for the line’s primary place of use, for line usage taxation. |
primaryPlaceOfUse.address.addresLine1 required for address |
string | The street address for the line’s primary place of use. This must be a physical address for taxation; it cannot be a P.O. box. |
primaryPlaceOfUse.address.addressLine2 optional for address |
string | Optional additional street address information. |
primaryPlaceOfUse.address.city required for address |
string | The city for the line’s primary place of use. |
primaryPlaceOfUse.address.state required for address |
string | The state for the line’s primary place of use. If a state name is provided, it will be converted to the standard 2-digit state code. |
primaryPlaceOfUse.address.zip required for address |
string | The five digit Zip code for the line’s primary place of use. If Zip code is passed in Zip-Zip4 format, the Zip code will be kept and the Zip4 code will be stored in the Zip4. |
primaryPlaceOfUse.address.zip4 optional |
string | The four digit Zip code in the Zip-Zip4 format. |
primaryPlaceOfUse.address.country required for address |
string | Either “US” or “USA” for the country of the line’s primary place of use. |
primaryPlaceOfUse.address.phone optional |
string | A phone number where the customer can be reached. |
primaryPlaceOfUse.address.phoneType optional |
string | A single letter to indicate the customer phone type:
|
primaryPlaceOfUse.address.emailAddress optional |
string | An email address for the customer. |
Request to change the state of two 4G devices:
{
"devices":[
{
"deviceIds":[
{
"kind":"imei",
"id":"990013907835573"
},
{
"kind":"iccid",
"id":"89141390780800784259"
}
]
},
{
"deviceIds":[
{
"kind":"imei",
"id":"990013907884259"
},
{
"kind":"iccid",
"id":"89141390780800735573"
}
]
}
],
"serviceName":"My Service",
"stateName":"My State",
"servicePlan":"87641",
"mdnZipCode":"94203",
"groupName":"4G West",
"publicIpRestriction":"unrestricted",
"primaryPlaceOfUse":{
"customerName":{
"title":"President",
"firstName":"Zaffod",
"lastName":"Beeblebrox"
},
"address":{
"addressLine1":"1600 Pennsylvania Ave NW",
"city":"Washington",
"state":"DC",
"zip":"20500",
"country":"USA"
}
}
}
Status 200
Parameter Name | Data Type | Description |
---|---|---|
requestId | string | A unique string that associates the request with the results that are sent via a callback service. The ThingSpace Platform will send a separate callback message for each device that matched the request criteria, indicating whether the operation succeeded for that device and containing any requested information. All of the callback messages will have the same requestId. |
{
"requestId": "595f5c44-c31c-4552-8670-020a1545a84d"
}
Parameter | Data Type | Description |
---|---|---|
username | string | The username for authentication. |
password | string | The password for authentication. |
requestId | string | The unique ID of the asynchronous request. |
deviceIds | object | The type and value of the device identifiers for a single device. |
deviceIds.kind deviceIds.id |
strings | The type (kind) and value (id) of the device identifier.
|
deviceResponse | responseObject | Callback response object. |
deviceResponse.goToStateResponse | responseObject | Callback response object. |
deviceResponse.goToStateResponse.deviceIds | object | The type and value of the device identifiers for a single device. |
deviceResponse.goToStateResponse.deviceIds.kind deviceResponse.goToStateResponse.deviceIds.id |
strings | The type (kind) and value (id) of the device identifier.
|
deviceResponse.goToStateResponse.ipAddress | string | Ip address |
deviceResponse.goToStateResponse.servicePlan | string | The service plan code assigned to devices in the new state. |
deviceResponse.goToStateResponse.accountName | string | The name of a billing account. (An account name is usually numeric, and must include any leading zeros.) |
deviceResponse.goToStateResponse.serviceName | string | The name of a customer-defined service to push the devices to. |
deviceResponse.goToStateResponse.smsrOid | string | For eUICC devices, the Object ID of the SMSR system. |
deviceResponse.goToStateResponse.subscriptionTypeCode | string | Valid values include the following:
|
deviceResponse.goToStateResponse.subscriptionTypeDesc | string | A description of the the subscriptionTypeCode. |
deviceResponse.goToStateResponse.stageStateChangeReasonCode | string | State change reason codes. Valid values include the following:
|
deviceResponse.goToStateResponse.stageStateChangeReasonDesc | string | A description of the stageStateChangeReasonCode. |
status | string | Indicates the status fo the action. Valid values include:
|
callbackCount | integer | Total number of callback requests. |
maxCallbackThreshold | string | Maximum number of callbacks allowed. |
{
"username" : "user",
"password" : "user",
"requestId" : "24da9f9a-d110-4a54-86b4-93fb76aab83c",
"deviceIds" : [ {
"id" : "A1000000444461",
"kind" : "MEID"
} ],
"deviceResponse" : {
"goToStateResponse" : {
"deviceIds" : [ {
"id" : "5225859659",
"kind" : "mdn"
}, {
"id" : "311480993482697",
"kind" : "imsi"
}, {
"id" : "15225859659",
"kind" : "msisdn"
}, {
"id" : "357844066109992",
"kind" : "imei"
}, {
"id" : "89148000003235128183",
"kind" : "iccid"
}, {
"id" : "15937958569063256287412365873621",
"kind" : "eid"
} ],
"ipAddress" : "206.130.128.131",
"servicePlan" : "test",
"accountName" : "0786890242-00001",
"serviceName" : "sample",
"stateName" : "new active",
"smsrOid" : "1.3.6.1.4.1.31746.1.500.200.101.5",
"subscriptionTypeCode" : "GPX",
"subscriptionTypeDesc" : "Garage Swap with Pre-Paid External Subscriber",
"stageStateChangeReasonCode" : "",
"stageStateChangeReasonDesc" : ""
}
},
"status" : "Success",
"callbackCount" : 1,
"maxCallbackThreshold" : 4
}
Status 400
All error messages are returned in this format:
{
"errorCode": "error code string",
"errorMessage": "error message string"
}
Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions.