POST /devices/actions/list

Returns information about a single device or information about all devices that match the given parameters. Returned information includes device provisioning state, service plan, MDN, MIN, and IP address.

Contents

Uses and Requirements

If you request information for more than one device, each response includes up to 2000 devices, sorted by device ID or chronologically by the date the devices were added.

• To get devices sorted by device ID (recommended), include the largestDeviceIdSeen parameter in the request. If the request matches more than 2000 devices (hasMoreData = true), you can send additional requests, adjusting the largestDeviceIdSeen value each time to start where the previous request finished.
• To get devices sorted by the date they were added to the account, do not include the largestDeviceIdSeen parameter in the request. If the request matches more than 2000 devices (hasMoreData = true), you can send additional requests, adjusting the earliest timestamp in each request to start where the previous request finished.

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v1/devices/actions/list

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.

Request Body

In the request body you can either specify one device in the deviceId parameter, or you can use the other parameters to request a list of devices that match the parameter values. A request with no parameters returns all devices that the session user account has access to. A request with just an accountName returns all devices in that account. A request with an accountName and any combination of other parameters includes only those devices that match all criteria.

Example Request Body

Request information for a single device

{
   "deviceId": {
      "id": "20-digit ICCID",
      "kind": "iccid"
   }
}

Request information for multiple devices

{
   "deviceList":[
      {
         "id":"10-digit MDN",
         "kind":"mdn"
      },
      {
         "id":"20-digit ICCID",
         "kind":"iccId"
      },
      {
         "id":"15-digit IMEI",
         "kind":"imei"
      },
      {
         "id":"20-digit ICCID",
         "kind":"iccId"
      },
      {
         "id":"32-digit EID",
         "kind":"eid"
      }
   ]
} 

Request information for all devices that contain a specified string in their ICCIDs

{
  "accountName": "0786890242-00001",
  "filter": {
    "deviceIdentifierFilters": [
      {
        "kind": "iccid",
        "contains": "4259"
      }
    ]
  }
}

Request information for all devices in a device group that have a specified service plan, and sort the devices in the response by device ID

{
  "groupName": "southwest",
  "accountName": "0000123456-00001",
  "servicePlan": "m2m4G",
  "largestDeviceIdSeen": 0
}

Success Responses

Status 200 or 202

An array of objects for each device that matched the request, sorted by the date and time when each device was added to the account (the createdAt value). If no devices match the request, the response is an empty array.

Example Success Response

{
   "hasMoreData":false,
   "devices":[
      {
         "accountName":"0000123456-00001",
         "billingCycleEndDate":"2020-05-09T20:00:00-04:00",
         "carrierInformations":[
            {
               "carrierName":"Verizon Wireless",
               "servicePlan":"m2m4G",
               "state":"active"
            }
         ],
         "connected":false,
         "createdAt":"2019-08-07T10:42:15-04:00",
         "deviceIds":[
            {
               "id":"10-digit MDN",
               "kind":"mdn"
            },
            {
               "id":"15-digit IMEI",
               "kind":"imei"
            },
            {
               "id":"15-digit IMEI",
               "kind":"imei"
            },
            {
               "id":"20-digit ICCID",
               "kind":"iccId"
            },
            {
               "id":"1+10-digit MSISDN",
               "kind":"msisdn"
            },
            {
               "id":"10-digit MDN",
               "kind":"mdn"
            }
         ],
         "extendedAttributes":[
            {
               "key":"PrimaryPlaceOfUseTitle"
            },
            {
               "key":"PrimaryPlaceOfUseFirstName",
               "value":"John"
            },
            {
               "key":"PrimaryPlaceOfUseMiddleName",
               "value":""
            },
            {
               "key":"PrimaryPlaceOfUseLastName",
               "value":"Doe"
            },
            {
               "key":"PrimaryPlaceOfUseSuffix"
            },
            {
               "key":"PrimaryPlaceOfUseAddressLine1"
            },
            {
               "key":"PrimaryPlaceOfUseAddressLine2"
            },
            {
               "key":"PrimaryPlaceOfUseCity"
            },
            {
               "key":"PrimaryPlaceOfUseState"
            },
            {
               "key":"PrimaryPlaceOfUseCountry"
            },
            {
               "key":"PrimaryPlaceOfUseZipCode"
            },
            {
               "key":"PrimaryPlaceOfUseZipCode4"
            },
            {
               "key":"PrimaryPlaceOfUseCBRPhone"
            },
            {
               "key":"PrimaryPlaceOfUseCBRPhoneType"
            },
            {
               "key":"PrimaryPlaceOfUseEmailAddress"
            },
            {
               "key":"AccountNumber",
               "value":"0000123456-00001"
            },
            {
               "key":"SmsrOid"
            },
            {
               "key":"ProfileStatus"
            },
            {
               "key":"PromoCodes",
               "value":""
            },
            {
               "key":"PromotionStartDate",
               "value":""
            },
            {
               "key":"PromotionScheduledEndDate",
               "value":""
            },
            {
               "key":"LeadId"
            },
            {
               "key":"CustomerName"
            },
            {
               "key":"CustomerAddressLine1"
            },
            {
               "key":"CustomerAddressLine2"
            },
            {
               "key":"CustomerAddressCity"
            },
            {
               "key":"CustomerAddressState"
            },
            {
               "key":"CustomerAddressZipCode"
            },
            {
               "key":"ServiceZipCode",
               "value":"07920"
            },
            {
               "key":"SkuNumber",
               "value":"4GTESTDEVICE"
            },
            {
               "key":"CostCenterCode",
               "value":""
            },
            {
               "key":"PreIMEI",
               "value":"15-digit IMEI"
            },
            {
               "key":"PreSKU",
               "value":"4GTESTDEVICE"
            },
            {
               "key":"SIMOTADate",
               "value":"2021-05-31T00:00:00Z"
            },
            {
               "key":"RoamingStatus",
               "value":"Roaming"
            },
            {
               "key":"LastRoamingStatusUpdate",
               "value":"2021-06-01T19:20:05Z"
            },
            {
               "key":"RoamingCountry",
               "value":"India"
            },
           {
               "key":"ServiceName1",
               "value":"Name of the service"
            },            
            {
               "key":"StateName1",
               "value":"Name of the service Inservice"
            },                        
            {            
               "key":"ServiceStateStartDate1",
               "value":"2021-05-24T19:20:05Z"
            },
            {
               "key":"SubscriptionTypeCode1",
               "value":"GPX"
            },
            {
               "key":"SubscriptionTypeDesc1",
               "value":"Swap with Pre-Paid Subscriber"
            },            
            {
               "key":"StageStateChangeReasonCode1",
               "value":""
            },                        
            {            
               "key":"StageStateChangeReasonDesc1",
               "value":""
            }
         ],
"groupNames":[
            "southwest"
         ],
         "ipAddress":"0.0.0.0",
         "lastActivationBy":"Joe Q Public",
         "lastActivationDate":"2019-08-07T10:42:34-04:00",
         "lastConnectionDate":"2020-03-12T04:23:37-04:00"
      }
   ]
}

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!