# Retrieve the Global Device List `POST /v2/devices/actions/list` Retrieves a list of all the devices on an account. ## Header Parameters The request header must set the content-type to JSON, contain a current ThingSpace authorization token and a current VZ-M2M session token. For more details on how to get these tokens, visit [Getting Started](https://thingspace.verizon.com/documentation/api-documentation.html#/http/session-management/guides/getting-started). | Parameter Name | Data Type | Description | | ------------------------------ | --------- | ---------------------------------------------------------------- | | **Authorization** *(required)* | string | HTTP Authorization bearer token: `Authorization: Bearer {token}` | | **VZ-M2M-Token** *(required)* | string | A valid session token: `VZ-M2M-Token: {M2Mtoken}` | | **Content-Type** *(required)* | string | Must be application/json `Content-Type: application/json` | ## HTTP Request [POST https://thingspace.verizon.com/api/m2m/v2/devices/actions/list](/docs/standard-apis/connectivity-management/api-endpoints/embedded-sim-including-consumer-esim/consumer-esim-for-iot-solutions/retrieve-the-global-device-list-esim/retrievegloballist) ## Request Parameters | Parameter | Data Type | Description | | ---------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **accountName** *(required)* | string | The name of the account. This is numeric and is in the format **0000123456-00001**. Leading zeros must be included. | | **provisioningStatusFilter** | string | Filter by provisioning status. Values include: **DEACTIVATED**, **ACTIVATED**, **DEACTIVE**, **ACTIVE**, **SUSPEND**, **PENDING_ACTIVATION**, **PENDING_DEACTIVATION**, **PRE_ACTIVE**, **ACTIVATION_READY** or **TEST_READY**. | | **profileStatusFilter** | string | Filter by profile status. Values include: **DISABLE**, **ENABLE**, **DOWNLOAD_DISABLE**, **DOWNLOAD_ENABLE**, **NOT_DOWNLOADED**, **UNKNOWN** or **DELETE**. | | **carrierNameFilter** | string | The carrier providing cellular network access. The default is **Verizon Wireless**. | | **deviceFilter** | array | An array of device identifiers to filter on. Each identifier will contain: `id`, `kind` | | **id** | string | The numeric ID of the device. | | **kind** | string | The the type of device ID represented by the ID value. This could be: **imei** (International Mobile Equipment Identifier), **iccid** (Integrated Circuit Card Identifier), **mdn** (Mobile Device Number, which is the 10-digit phone number) or **eid** (Electronic ID). | ## Request Body Example request: ```json { "accountName":"0000123456-00001", "provisioningStatusFilter":"ACTIVE", "profileStatusFilter":"UNKNOWN", "carrierNameFilter":"Verizon Wireless", "deviceFilter":[ { "id":"15-digit IMEI", "kind":"imei" }, { "id":"32-digit EID", "kind":"eid" } ] } ``` ## Success Response **Status 200** A successful response shows a system generated request ID to track the request. Example Response: ```json { "requestId": "d1f08526-5443-4054-9a29-4456490ea9f8" } ``` ## Callback Response These endpoints send responses asynchronously. In order to read the results a callback is required. To learn more about callbacks, please visit [About Callback Services](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/guides/working-with-verizon-wireless/about-callback-services). Example callback response: ```json { "requestId":"0cb74b9a-ef2f-4e16-a108-4b3a37417832", "deviceResponse":{ "getDeviceListWithProfiles":{ "complete":true, "total":1, "results":[ { "accountName":"0000123456-00001", "profiles":[ { "carrierInformation":{ "carrierName":"VerizonWireless", "servicePlan":"Name of the service plan" }, "billingCycleEndDate":"2021-08-31T11:59:59.0000000Z", "connected":false, "createdAt":"2021-08-23T22:14:54.7700000Z", "profileIdentifiers":[ { "kind":"iccid", "identifier":"20-digit ICCID" }, { "kind":"imsi", "identifier":"15-digit IMEI" }, { "kind":"mdn", "identifier":"10-digit MDN" }, { "kind":"msisdn", "identifier":"1 + 10-digit MDN" } ], "extendedAttributes":[ { "key":"PrimaryPlaceOfUseFirstName", "value":"First name" }, { "key":"PrimaryPlaceOfUseLastName", "value":"Surname" }, { "key":"PrimaryPlaceOfUseSuffix", "value":"Jr." }, { "key":"PrimaryPlaceOfUseAddressLine1", "value":"line 1 of address" }, { "key":"PrimaryPlaceOfUseAddressLine2", "value":"line 2 of address" }, { "key":"PrimaryPlaceOfUseCity", "value":"city of address" }, { "key":"PrimaryPlaceOfUseState", "value":"state of address" }, { "key":"PrimaryPlaceOfUseCountry", "value":"country of address" }, { "key":"PrimaryPlaceOfUseZipCode", "value":"5 digit zip code of address" }, { "key":"PrimaryPlaceOfUseZipCode4", "value":"+4 digit of zip code" }, { "key":"PrimaryPlaceOfUseCBRPhone", "value":"10-digit phone number" }, { "key":"PrimaryPlaceOfUseEmailAddress", "value":"abc@gmail.com" } ], "groupNames":[ "Default: 0000123456-00001" ], "lastActivationBy":"user name", "lastActivationDate":"2021-08-23T22:14:56.0000000Z", "lastConnectionDate":"", "provisioningStatus":"active", "profileStatus":"unknown" } ], "extendedAttribute":[ { "key":"AccountNumber", "value":"0000123456-00001" }, { "key":"LeadId", "value":"LEAD" }, { "key":"CustomerAddressLine1", "value":"line 1 of address" }, { "key":"CustomerAddressLine2", "value":"line 2 of address" }, { "key":"CustomerAddressCity", "value":"city of address" }, { "key":"CustomerAddressState", "value":"state of address" }, { "key":"ServiceZipCode", "value":"5 digit zip code" }, { "key":"DeviceId", "value":"user assigned ID" } ], "deviceIdentifiers":[ { "id":"15-digit IMEI", "kind":"imei" }, { "id":"32-digit EID", "kind":"eid" } ] } ] } } } ``` ## Callback Parameters | Parameter | Data Type | Description | | ----------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------- | | **requestId** | string | The `requestId` being viewed. This is a system generated value from the request above. | | **deviceResponse** | object | Contains the `getDeviceListWithProfiles`. | | **getDeviceListWithProfiles** | array | Shows if the request is complete, how many records matched the request and the results of the request. | | **accountName** | string | The numeric name of the account being queried. | | **profiles** | array | The profile information of the account and the devices matching the request. | | **carrierInformation** | array | The carrier name and service plan name for the profile. | | **carrierName** | string | The name of the carrier providing cellular network access. | | **servicePlan** | string | The service plan subscribed to. This drives billing rates for usage. | | **billingCycleEndDate** | string ($date-time) | The timestamp used for the end of a billing period. | | **connected** | boolean | **True** - Device is connected. **False** - Device is not connected. | | **createdAt** | string ($date-time) | The timestamp of the record's creation. | | **profileIdentifiers** | array | The ID information for the device(s) in the profile. Each will contain: `identifier`, `kind` | | **identifier** | string | The numeric ID of the device. | | **kind** | string | The type of device ID represented by the ID value. This could be: **imei**, **iccid**, **mdn** or **eid**. | | **extendedAttributes** | array | This is the primary name, address, phone number and email address of the account holder. | | **groupNames** | array | Contains the names of the groups the profile is associated with. | | **lastActivationBy** | string | The user name that made the most recent change. | | **lastActivationDate** | string ($date-time) | The timestamp of the most recent change. | | **provisioningStatus** | string | Status of provisioning. Will be one of the following: **Active**, **Pending**, **Disable** or **Unknown**. | | **extendedAttribute** | array | Alternate contact information for the account holder as well as a user defined name for the device (optional). | | **deviceIdentifiers** | array | An array of device identifiers being matched by the request. Each device identifier will contain: `id`, `kind` | | **id** | string | The numeric ID of the device. | | **kind** | string | The type of device ID represented by the ID value. This could be: **imei**, **iccid**, **mdn** or **eid**. | ## Failure Responses All error responses will be in the following format ```json { "errorCode": "The 3-digit HTML error code", "errorMessage": "string" } ```