# Retrieve the Global Device List #### `POST /v2/devices/actions/list` Retrieves a list of all devices on an account. **Bulk operation**: Supported (The callback would be one for each profile). Bulk operations have a limit of 10,000 requests. **eSIM profiles**: Both Verizon US and Global. ## 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/global-iot-orchestration/api-endpoints/retrieve-the-global-device-list/retrievetheglobaldevicelist) Request Parameters | Parameter | Data Type | Description | |-----|-----|-----| | **accountName** *(required)* | string | The name of the account. | | **provisioningStatusFilter** | string | Filter by provisioning status. Values include: **DEACTIVATED**, **ACTIVATED**, **DEACTIVE**, **ACTIVE**, **SUSPEND**, **PENDING_ACTIVATION**, **PENDING_DEACTIVATION**, **PRE_ACTIVE**, **ACTIVATION_READY**, **INVENTORY**, **PURGED**, **REPLACED**, **RETIRED**, **TEST_READY**, **UNKNOWN** | | **profileStatusFilter** | string | Filter by profile status. Values include: **DISABLE**, **ENABLE**, **DOWNLOAD_DISABLE**, **DOWNLOAD_ENABLE**, **NOT_DOWNLOADED**, **UNKNOWN**, **DELETE** | | **carrierName** | string | The carrier providing cellular network access. This is set to **Verizon Wireless** for US profiles, and removed for **Global** profiles. | | **devices** | array | An array of deviceIds. Each deviceId 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**, **iccid**, **mdn**, **eid**. | ## 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":"d1f08526-5443-4054-9a29-4456490ea9f8", "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 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 profile'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 the type of device ID represented by the ID value. This could be: **imei**, **iccid**, **mdn**, **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**, **Unknown**. | | ***extendedAttribute*** | string | Alternate contact information for the account holder. | | ***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 the type of device ID represented by the ID value. This could be: **imei**, **iccid**, **mdn**, **eid**.| ## Failure Responses All error responses will be in the following format ```json { "errorCode": "The 3-digit HTML error code", "errorMessage": "string" } ```