Retrieve Device Information

Retrieve Information about Devices:
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.

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

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 will return all devices that the session user account has access to. A request with just an accountName will return all devices in that account. A request with an accountName and any combination of other parameters will include only those devices that match all criteria.

Parameter Name Data Type Description
deviceId
optional		 deviceId object An identifier for a single device.
deviceId.kind,
deviceId.id
required for deviceId		 string The type and value of the device identifier.
  • ESN - decimal, 11 digits
  • ICCID - decimal, up to 20 digits
  • IMEI - decimal, up to 15 digits
  • MDN - decimal, 10 digits
  • MEID - hexadecimal, 14 hex digits
  • MSISDN - decimal, 11 digits
accountName
optional		 string The billing account for which a list of devices will be returned. If you don’t specify an accountName, the list will include all devices to which you have access.
An account name is usually numeric, and must include any leading zeros.
filter
optional		 filter object Find devices by partial identifier.
filter.deviceIdentifierFilters
required for filter		 array Specify the kind of the device identifier, the type of match, and the string that you want to match.
filter.deviceIdentifierFilters.type
required for deviceIdentifierFilters		 string The type of match that you’re looking for. Valid types of matches are:
  • contains - The string appears anywhere in the identifer
  • startswith - The identifer must start with the specified string
  • endswith - The identifier must end with the specified string
filter.deviceIdentifierFilters.kind
required for deviceIdentifierFilters		 string The type of the device identifier to match. Valid types of identifiers are:
  • EID
  • ESN
  • ICCID
  • IMEI
  • MDN
  • MEID
  • MSISDN
contains
required for filter
 string The string to match against device identifiers. The string can be as short as one character, but more characters will narrow down the number of results and make it easier to find the device that you’re looking for.
groupName
optional		 string Only include devices that are in this device group.
servicePlan
optional		 string Only include devices that have this service plan.
currentState
optional		 string The name of a device state, to only include devices in that state.
customFields
optional		 list of customField objects Custom field names and values, if you want to only include devices that have matching values.
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. The value is not case-sensitive, but other than that it must match exactly with the value set for a device. Wildcards and partial matches are not supported.
largestDeviceIdSeen
optional		 long or string (Output buffering parameter) Only return information about devices that have an ID greater than this value. (These reference IDs are different from other device IDs, such as MEIDs, IMEIs, or ICCIDs.) Device IDs are returned as an extended attribute for each device.
  • For the first request, set this element to zero to retrieve the devices with the smallest IDs.
  • Check the hasMoreData value in the response.
  • If it’s “false” then you have received the complete list of devices.
  • If hasMoreData is “true,” send another request, putting the largest returned DeviceId value into this field. Continue sending requests with the largest DeviceId from the latest response until hasMoreData is “false.” This ensures that all devices are retrieved exactly once, with no gaps or overlaps in devices returned by multiple calls to this endpoint.
maxNumberOfDevices
optional		 integer The maximum number of devices to be included in each response. The default value is 500, maximum value is 2000.
earliest
optional		 string Only include devices that were added after this date and time.
latest
optional		 string Only include devices that were added before this date and time.

Example Request Body

Request information for a single device

You can only specify one device by deviceId. To get information on multiple devices, you must either send multiple requests or match the devices by filter, groupName, servicePlan, currentState, etc.

{
   "deviceId": {
      "id": "89148000000800139708",
      "kind": "iccid"
   }
}

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": "0786890242-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 will be an empty array.

Parameter Name Data Type Description
accountName string The billing account that the device is associated with.
billingCycleEndDate string The date that the device’s current billing cycle ends.
carrierInformations The carrier information associated with the device.
carrierInformations.carrierName string The name of the carrier.
carrierInformations.servicePlan string The service plan that the device is assigned to.
NOTE: Service plan changes made through other tools are synchronized with the M2M Platform once per day, so you may need to wait up to 24 hours before those changes are returned by the API.
carrierInformations.state string The current state of the device, which will be one of these values:
  • pre-active
  • active
  • deactive
  • suspend
  • pending resume
  • pending MDN change
  • pending PRL Update
  • pending preactive
  • pending activation
  • pending deactivation
  • pending suspend
  • pending service plan change
  • pending ESN / MEID change
  • pending account update
connected boolean True if the device is connected; false if it is not.
createdAt dateTime The date and time that the device was added to the system.
customFields The custom fields and values that have been set for the device.
customFields.key string The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5.
customFields.value string The value of the custom field.
deviceIds All identifiers for the device.
deviceIds.kind string The type of the device identifier. Valid types of identifiers are:
  • ESN (decimal)
  • EID
  • ICCID (up to 20 digits)
  • IMEI (up to 15 digits)
  • MDN
  • MEID (hexadecimal)
  • MSISDN
deviceIds.id string The value of the device identifier.
groupNames string The device group that the device belongs to.
ipAddress string The IP address of the device.
lastActivationBy string The user who last activated the device.
lastActivationDate string The date and time that the device was last activated.
lastConnectionDate string The most recent connection date and time.
extendedAttributes Any extended attributes for the device, as Key and Value pairs. The pairs listed below are returned as part of the response for a single device, but are not included if the request was for information about multiple devices.
extendedAttributes.key string PromoCodes
extendedAttributes.value string A comma-separated list of the names of any promotional codes active for the device.
A value of “Data=Machine to Machine 60KB” would indicate that a promotional code is associated with the device that allows for 60KB of complementary data traffic. Here are some example values:
  • Data=Machine to Machine 60KB
  • SMS=Machine to Machine 15 SMS
  • Voice=Machine to Machine 5 MOU
extendedAttributes.key string PromotionStartDate
extendedAttributes.value string The date that the promotion started, such as
4/3/2015 12:00:00 AM
extendedAttributes.key string PromotionScheduledEndDate
extendedAttributes.value string The date that the promotion is scheduled to end, such as
10/31/2016 12:00:00 AM
extendedAttributes.key string Additional extendedAttributes containing lead-related information for devices provisioned under VPP partner accounts:
LeadId
CustomerName
CustomerAddressLine1
CustomerAddressLine2
CustomerAddressCity
CustomerAddressState
CustomerAddressZipCode
ServiceZipCode
extendedAttributes.value string The values for the VPP partner account for the current device.
extendedAttributes.key string SkuNumber
extendedAttributes.value string The SKU for the current device. This value object is not returned for null values.
extendedAttributes.key string CostCenterCode
extendedAttributes.value string The cost center code for the current device.
extendedAttributes.key string PreIMEI
extendedAttributes.value string The IMEI of the device prior to the most recent SIM OTA activation. This value object is not returned for null values.
extendedAttributes.key string PreSKU
extendedAttributes.value string The SKU of the device prior to the most recent SIM OTA activation. This value object is not returned for null values.
extendedAttributes.key string SIMOTADate
extendedAttributes.value string The date and time of the most recent SIM OTA activation. The SIMOTADate key and value objects are not returned for null values.
extendedAttributes.key string deviceId
extendedAttributes.value string A unique internal value for this device. This value is only present in the response when the request included largestDeviceIdSeen.
extendedAttributes.key string smsrOid
extendedAttributes.value string For eUICC devices, the Object ID of the SMSR system.
extendedAttributes.key string profileStatus
extendedAttributes.value string For eUICC devices, the current status of the local profile. Nil for all other devices.
extendedAttributes.key string accountNumber
extendedAttributes.value string The billing account number that the device is associated with. It is usually the same as the AccountName.
hasMoreData boolean False for a status 200 response.
True for a status 202 response, indicating that there is more data to be retrieved. Send another request, adjusting the largestDeviceIdSeen value or the earliest value in the request based on thedeviceId or createdAt value for the last device in the current response.

Example Success Response

{
   "devices": [
    {
      "accountName": "0245078689-00001",
      "billingCycleEndDate": "2016-02-09T19:00:00-05:00",
      "carrierInformations": [
        {
          "carrierName": "Verizon Wireless",
          "servicePlan": "Tablet5GB",
          "state": "active"
        }
      ],
      "connected": false,
      "createdAt": "2015-12-17T13:53:21-05:00",
      "customFields": [
        {
          "key": "CustomField1",
          "value": ""
        },
        {
          "key": "CustomField2",
          "value": ""
        },
        {
          "key": "CustomField3",
          "value": ""
        },
        {
          "key": "CustomField4",
          "value": "Galactic Heavy Industries"
        },
        {
          "key": "CustomField5",
          "value": ""
        }
      ],
      "deviceIds": [
        {
          "id": "5086303377",
          "kind": "mdn"
        },
        {
          "id": "311880082140479",
          "kind": "imsi"
        },
        {
          "id": "990083420535573",
          "kind": "imei"
        },
        {
          "id": "89148000800800784259",
          "kind": "iccId"
        },
        {
          "id": "15096383371",
          "kind": "msisdn"
        },
        {
          "id": "5086308842",
          "kind": "min"
        }
      ],
      "extendedAttributes": [
        {
          "key": "PromoCodes",
          "value": ""
        },
        {
          "key": "PromotionStartDate",
          "value": ""
        },
        {
          "key": "PromotionScheduledEndDate",
          "value": ""
        },
        {
          "key": "LeadId",
          "value": ""
        },
        {
          "key": "CustomerName",
          "value": ""
        },
        {
          "key": "CustomerAddressLine1",
          "value": ""
        },
        {
          "key": "CustomerAddressLine2",
          "value": ""
        },
        {
          "key": "CustomerAddressCity",
          "value": ""
        },
        {
          "key": "CustomerAddressState",
          "value": ""
        },
        {
          "key": "CustomerAddressZipCode",
          "value": ""
        },
        {
          "key": "ServiceZipCode",
          "value": ""
        },
        {
          "key": "SkuNumber"
        },
        {
          "key": "CostCenterCode",
          "value": ""
        },
        {
          "key": "PreIMEI"
        },
        {
          "key": "PreSKU"
        },
        {
          "key": "smsrOid",
          "value": ""
        },
        {
          "key": "ProfileStatus",
          "value": ""
        },
        {
          "key": "AccountNumber",
          "value": "0245078689-00001"
        }
      ],
      "groupNames": [
        "NCW Devices"
      ],
      "ipAddress": "100.127.22.52",
      "lastActivationBy": "Zaffod Beeblebrox",
      "lastActivationDate": "2015-12-17T13:56:13-05:00",
      "lastConnectionDate": "2015-12-17T14:12:36-05:00"
    }
  ],
  "hasMoreData":false
}

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!