Set Devices to Customer-Defined Service and State:

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. This API endpoint was enhanced with release 7.11 to be used with 4G and 5G devices as well as support Business Internet (5GBI).

Contents

See also:
Get Services and States

Uses and Requirements

You should be familiar with the M2M Service Provisioning Rules when working with device states.

You can specify a list of individual devices, or work with all the 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.

Best Practices

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.

Request Components

HTTP Request

PUT https://thingspace.verizon.com/api/m2m/v1/devices/actions/goToState

Resource Path and Query Parameters

None.

Header Parameters

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.

Request Body

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
  • Specify the devices in each request.
  • Do not include this parameter if you want to use the filter parameter to select devices by metadata values.
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.
  • If the devices do not have embedded SIMs, you must specify both the IMEI and the ICCID, in that order.
  • If the devices have embedded SIMs, you can specify IMEI and ICCID values, or just the ICCIDs and an associated device skuNumber
  • If the devices are eUICC devices, you can specify the EID and IMEI values, or the EIDs and an associated skuNumber
devices.ipAddress
optional		 string The IP address to assign to the device in the following format: 1-255.0-255.0-255.0-255
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 specifying individual devices. If you specify multiple parameters, they will be added 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. 
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 device type with an embedded SIM. Can be used with ICCID or EID device identifiers in lieu of an IMEI when activating devices. The SkuNumber will be used with all devices in the request, so all devices must be of the same type.
NOTE: Only devices with embedded SIMs and EUICC devices can be activated by SKU at this time.
devicesWithServiceAddress
only valid for 5G Business Internet device activation		 object An object that contains an array of device IDs as well as an IP address and Primary Place of Use for C-Band 5G Business Internet (FWA) plans with unlimited data plans. 
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 "R" for “restricted” or "U" for “unrestricted”.
  • U (unrestricted) = The device will have full access to the Internet.
  • R (restricted) = The device will have access to any content provided by Verizon Wireless but will be restricted from access to the Internet.
If left blank, the device will get the default value set for the account. Public network devices with dynamic IP addresses are always 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:
  • M = Mobile
  • H = Home
  • F = Fax
  • W = Work/Business
  • P = Pager
primaryPlaceOfUse.address.emailAddress
optional		 string An email address for the customer.

Example Request Body

Request to change the state of two devices:

{  
  "devices":[  
    {  
      "deviceIds":[  
        {  
          "kind":"imei",
          "id":"15-digit IMEI"
        },
        {  
          "kind":"iccid",
          "id":"20-digit ICCID"
        }
      ],
      "ipAddress" : "127.0.0.1"     },
    {  
      "deviceIds":[  
        {  
          "kind":"imei",
          "id":"15-digit IMEI"
        },
        {  
          "kind":"iccid",
          "id":"20-digit ICCID"
        }
      ],
      "ipAddress" : "10.0.0.1"     }
  ],
  "serviceName":"name of service",
  "stateName":"state of device",
  "servicePlan":"87641",
  "mdnZipCode":"94203",
  "groupName":"4G West",
  "publicIpRestriction":"U",
  "primaryPlaceOfUse":{
    "customerName":{
      "title":"President",
      "firstName":"Zaffod",
      "lastName":"Beeblebrox"
    },
    "address":{
      "addressLine1":"1600 Pennsylvania Ave NW",
      "city":"Washington",
      "state":"DC",
      "zip":"20500",
      "country":"USA"
    }
  }
}

Note: filter can be used in place of devices:

{
   "filter":{
      "accountName":"0000123456-00001",
      "groupName":"name of group",
      "servicePlan":"service plan name",
      "customFields":[
         {
            "key":"CustomField1",
            "value":"1"
         }
      ]
   },

Request to change the state of a Business Internet device:

{
   "filter":{
      "accountName":"0000123456-00001",
      "groupName":"name of group",
      "servicePlan":"service plan name",
      "customFields":[
         {
            "key":"CustomField1",
            "value":"1"
         }
      ]
   },
   "stateName":"new activate",
   "serviceName":"name of service",
   "servicePlan":"service plan name",
   "mdnZipCode":"94203",
   "publicIpRestriction":"U",
   "skuNumber":"stock keeping unit number",
   "customFields":[
      {
         "key":"CustomField1",
         "value":"1"
      }
   ],
   "devicesWithServiceAddress":[
      {
         "deviceIds":[
            {
               "id":"14-character MEID",
               "kind":"meid"
            }
         ],
         "ipAddress" : "10.0.0.1",
          "primaryPlaceOfUse":{
            "address":{
               "addressLine1":"60 Sylvan Rd.",
               "city":"Waltham",
               "state":"MA",
               "country":"USA",
               "zip":"02421",
               "zip4":"+4 zipcode digits",
               "phone":"10-digit phone number",
               "phoneType":"H",
               "emailAddress":"xxxx@yyyy.com"
            },
            "customerName":{
               "firstName":"Verizon",
               "lastName":"Wireless",
               "middleName":"Great",
               "title":"Mr",
               "suffix":"Jr"
            }
         }
      }
   ],
   "groupName":"name of the group"
}

Success Responses

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.

Example Success Response

{
  "requestId": "595f5c44-c31c-4552-8670-020a1545a84d"
}

Response Parameters

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.
  • ICCID - decimal, up to 20 digits
  • IMEI - decimal, up to 16 digits
  • MDN - decimal, 10 digit phone number
  • MSISDN - decimal, 11 digits (1+ 10-digit phone number)
deviceResponse object Callback response object.
deviceResponse.goToStateResponse object 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.
  • ICCID - decimal, up to 20 digits
  • IMEI - decimal, up to 16 digits
  • MDN - decimal, 10 digit phone number
  • MSISDN - decimal, 11 digits (1+ 10-digit phone number)
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.stateName string The name of a customer-defined state to push the devices to. The example "new active" could be used for devices that have been activated for the first time.
deviceResponse.goToStateResponse.smsrOid string For eUICC devices, the Object ID of the SM-SR system.
deviceResponse.goToStateResponse.subscriptionTypeCode string Valid values include the following:
  • GPX - Garage Swap with Prepaid External Subscriber
  • GPV - Garage Swap with Postpaid Verizon Subscriber
deviceResponse.goToStateResponse.subscriptionTypeDesc string A description of the the subscriptionTypeCode.
deviceResponse.goToStateResponse.stageStateChangeReasonCode string State change reason codes. Valid values include the following:
  • OTE - On Demand Trial End
  • SUB - Ended Subscription
  • EXT - Expired Trial
  • APT - Activated Post Paid WiFi Service
  • APP - Activated Prepaid WiFi Service
deviceResponse.goToStateResponse.stageStateChangeReasonDesc string A description of the stageStateChangeReasonCode.
status string

Indicates the status fo the action. Valid values include:

  • Success
  • Failed
callbackCount integer Total number of callback requests.
maxCallbackThreshold string Maximum number of callbacks allowed.

Example Success Response


{
  "username" : "user",
  "password" : "user",
  "requestId" : "595f5c44-c31c-4552-8670-020a1545a84d",
  "deviceIds" : [ {
    "id" : "16-digit IMEI",
    "kind" : "imei"
  } ],
  "deviceResponse" : {
    "goToStateResponse" : {
      "deviceIds" : [ {
        "id" : "10-digit MDN",
        "kind" : "mdn"
      }, {
        "id" : "15-digit IMSI",
        "kind" : "imsi"
      }, {
        "id" : "11-digit MSISDN",
        "kind" : "msisdn"
      }, {
        "id" : "15-digit IMEI",
        "kind" : "imei"
      }, {
        "id" : "20-digit ICCID",
        "kind" : "iccid"
      }, {
        "id" : "32-digit EID",
        "kind" : "eid"
      } ],
      "ipAddress" : "10.0.0.1",
      "servicePlan" : "service plan name",
      "accountName" : "0000123456-00001",
      "serviceName" : "service name",
      "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
}

Failure Responses

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.

Try It Out!