API Reference

Use this endpoint to retrieve device details and related information.

Uses and Requirements

If you request information for more than one device, each response includes up to 500 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 500 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 500 devices (hasMoreData = true), you can send additional requests, adjusting the earliest timestamp in each request to start where the previous request finished.

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`.

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.

Parameter Name	Data Type	Description
deviceList (optional)	array	An array of deviceId objects to use when requesting information from multiple devices.
deviceId (optional)	object	An identifier for a single device, containing a `kind` and an `id`.
deviceId.kind, deviceId.id (required for deviceId)	string	The type and value of the device identifier: ESN - decimal, 11 digits EID - decimal, 32 digits ICCID - decimal, up to 20 digits IMEI - decimal, up to 16 digits MDN - decimal, a 10 digit phone number MSISDN - decimal, 11 digits
accountName (optional but recommended)	string	The billing account for which a list of devices is returned. If you don’t specify an `accountName`, the list includes all devices to which you have access. An account name is usually numeric, and must include any leading zeros. Coding the account number today prevents future code from breaking if you ever add a new sub-account.
filter (optional)	object	Filter the list of 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 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 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)	object	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 `IMEI`s, or `ICCID`s.) 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. This value can also be set "= 0" if indexing is not needed or if starting at the top of the list.
maxNumberOfDevices (optional)	integer	The maximum number of devices to be included in each response. The maximum value is 500.
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

{
   "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": "0000123456-00001",
  "filter": {
    "deviceIdentifierFilters": [
      {
        "kind": "iccid",
        "contains": "20-digit ICCID"
      }
    ]
  }
}

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": "service plan name",
  "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.

Parameter Name	Data Type	Description
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 the `deviceId` or `createdAt` value for the last device in the current response.
accountName	string	The billing account that the device is associated with.
billingCycleEndDate	string	The date that the device’s current billing cycle ends.
carrierInformations	array	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 are 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	string ($dateTime)	The date and time that the device was added to the system.
customFields	array	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	array	All identifiers for the device.
deviceIds.kind	string	The type of the device identifier. Valid types of identifiers are: ESN , EID , ICCID , IMEI , MDN , MSISDN .
deviceIds.id	string	The value of the device identifier.
extendedAttributes	array	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	Additional `extendedAttributes` containing place-of-use information: PrimaryPlaceofUseFirstName PrimaryPlaceofUseMiddleName PrimaryPlaceofUseLastName PrimaryPlaceofUseSuffix PrimaryPlaceofUseAddressLine1 PrimaryPlaceofUseAddressLine2 PrimaryPlaceOfUseCity PrimaryPlaceofUseState PrimaryPlaceOfUseCountry PrimaryPlaceofUseZipCode PrimaryPlaceOfUseZipCode4 PrimaryPlaceOfUseCBRPhone PrimaryPlaceOfUseCBRPhoneType PrimaryPlaceOfUseEmailAddress
extendedAttributes.value	string	The place of use value for teh key.
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.
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. Null for all other devices. eUICC profiles can be in the following states: DOWNLOAD_ENABLE: Profile was downloaded and enabled DOWNLOAD_DISABLE: Profile was downloaded successfully but not enabled (also known as Disabled) ENABLE: Profile was downloaded and enabled in two steps: a) first it was only downloaded but not enabled–status would be `DOWNLOAD_DISABLE`, b) second, it was enabled–status would be `ENABLE` DISABLE: Profile was downloaded but disabled because a profile `DISABLE` API call was explicitly made to disable a profile that was both downloaded and enabled DELETE: Profile was deleted from the device NOT DOWNLOADED: An operation profile does not exist; the device is still on bootstrap
extendedAttributes.key	string	PromotionStartDate
extendedAttributes.value	string($date-time)	The date that the promotion started, such as `2021-05-31T00:00:00Z`
extendedAttributes.key	string	PromotionScheduledEndDate
extendedAttributes.value	string	The date that the promotion is scheduled to end, such as `2021-06-31T00:00:00Z`
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 Stock Keeping Unit number for the current device. This value object is not returned for null values (no SKU).
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($date-time)	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	RoamingStatus
extendedAttributes.value	string	`True` if the device is currently roaming.
extendedAttributes.key	string	LastRoamingStatusUpdate
extendedAttributes.value	string($datetime)	The time and date that the last roaming status was updated.
extendedAttributes.key	string	RoamingCountry
extendedAttributes.value	string	The name of a country if `RoamingStatus=true`, or empty if `false`.
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	ServiceNameN
extendedAttributes.value	string	The name of the services and states active for a device in an account that has custom services and states. StateName1 belongs to ServiceName1 and StateName2 belongs to ServiceName2, etc.
extendedAttributes.key	string	StateNameN
extendedAttributes.value	string	The name of the services and states active for a device in an account that has custom services and states. StateName1 belongs to ServiceName1 and StateName2 belongs to ServiceName2, etc.
extendedAttributes.key	string	ServiceStateStartDateN
extendedAttributes.value	string($date-time)	Service start date, such as `2021-05-24T19:20:05Z`. ServiceStateStartDate1 belongs to ServiceName1 and StateName1 and ServiceStateStartDate2 belongs to ServiceName2 and StateName 2, etc.
extendedAttributes.key	string	subscriptionTypeCodeN
extendedAttributes.value	string	Valid values include the following: GPX - Garage Swap with Pre-Paid External Subscriber GPV - Garage Swap with Postpaid Verizon Subscriber
extendedAttributes.key	string	subscriptionTypeDescN
extendedAttributes.value	string	A description of the the `subscriptionTypeCode`.
extendedAttributes.key	string	stageStateChangeReasonCodeN
extendedAttributes.value	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
extendedAttributes.key	string	stageStateChangeReasonDescN
extendedAttributes.value	string	A description of the `stageStateChangeReasonCode`.
groupNames	string	The device group that the device belongs to.
ipAddress	string	The IPv4 address of the device.
lastActivationBy	string	The ID of the user who last activated the device.
lastActivationDate	string($datetime)	The date and time that the device was last activated.
lastConnectionDate	string($datetime)	The most recent connection date and time.

Example Success Response

{
   "hasMoreData":false,
   "devices":[
      {
         "accountName":"0000123456-00001",
         "billingCycleEndDate":"2020-05-09T20:00:00-04:00",
         "carrierInformations":[
            {
               "carrierName":"Verizon Wireless",
               "servicePlan":"service plan name",
               "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":"10.00.00.01",
         "lastActivationBy":"Joe Q Public",
         "lastActivationDate":"2019-08-07T10:42:34-04:00",
         "lastConnectionDate":"2020-03-12T04:23:37-04:00"
      }
   ]
}

Uses and RequirementsCopy Anchor Link

HTTP RequestCopy Anchor Link

Resource Path and Query ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Example Request BodyCopy Anchor Link

Request information for multiple devicesCopy Anchor Link

Success ResponsesCopy Anchor Link

Example Success ResponseCopy Anchor Link

On this page