# Create a Device Location Report ### `POST /locationreports` Requests the generation of an asynchronous location report for up to 10,000 devices. This request returns a transaction ID that can be used to check on the status of the report, retrieve the report or cancel the report. Reports are available for 30 days. Request a report of current device locations or request the previous locations from the cache. If the cached device location information is requested, the report will be ready immediately and the transaction ID from the response can be used to retrieve it. If current device location information is requested, it may take time for the report to be created. The transaction ID can also be used to get the report status and then to retrieve the report when it is ready. This method can only be used for IoT and Fixed Wireless Access (FWA) devices. **Polling or Callback Notifications** A device management system can be coded so that it receives callback messages when asynchronous reports are ready or it can poll to check the status of reports. **Location Accuracy** The requested accuracy may or may not be met due to device capability and other network restrictions. The report will have a QoS (Quality of Service) parameter to indicate if the requested accuracy was met (this a future enhancement). ## 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/loc/v1/locationreports](/docs/premium-apis/device-location/api-endpoints/devices-locations/createlocationreport) ## Request Parameters |Property Name|Data Type|Description| |-----|-----|-----| | **accountName** *(required)* | string | The numeric name of a billing account. Must include any leading zeros. | | **accuracyMode** *(optional)* | string | An integer (as a string) representing the requested accuracy of the returned location. Coarse location (**0**) is currently the only supported value. **0**: coarse accuracy, **1**: Reserved for future enhancements. | | **cacheMode** *(optional)* | string | An integer (as a string) indicating whether current or cached location information should be returned. **0**: Cached. (Default) Information from the last successful device location check is returned or an error message is returned if there is no cached information for a device. There is no billing charge for requesting cached location information. **1**: Cached or current. ThingSpace first looks for cached information for the device and returns that information if it exists. If there is no cached information, it finds the current location of the device and returns that information, plus stores it in the cache. **2**: Current. Returns the current location of the device, and stores that location information in the cache. | | **deviceList** *(required)* | array | Each object in the array must contain three elements that identify a device to locate: `id`: a device identifier value, `kind`: the type of the identifier. This is the International Mobile Equipment ID (**IMEI**) and `mdn`: the Mobile Device Number or 10-digit “phone number” of the device (*tip*: remove the 1 from the beginning of an **MSISDN** to derive the **MDN**). | ## Request Body The request body contains the `accountName` and a list of devices to locate, plus other options. Example Request Body: ```json { "accountName": "0000123456-00001", "accuracyMode": "0", "cacheMode": "1", "deviceList":[ { "id":"900000000000009", "kind":"imei", "mdn":"10-digit phone number" }, { "id":"900000000000019", "kind":"imei", "mdn":"10-digit phone number" }, ] } ``` ## Success Response **Status 200** Requests with `"cacheMode": "0"` return a 200 status and the report is available immediately. Requests with `"cacheMode": "1"` or `"2"` return a 200 status and the body of the response includes an estimate of how long it will take to create the report. Success responses return a transaction ID that can be used to retrieve the report, get the status of the report or cancel the report. Example Success Response: ```json { "txid": "2c90bd28-eeee-ffff-gggg-7e3bd4fbff33", "status": "QUEUED", "estimatedDuration": "12" } ``` ## Success Parameters |Property Name|Data Type|Description| |-----|-----|-----| | **txid** | string | Unique ID of the request. This is a 32 or 36-bit UUID. | | **status** | string | This will show **QUEUED** or **COMPLETED**, depending on what stage the report processing is at. | | **estimatedDuration** | string | Estimated number of minutes required to complete the report. | ## Failure Responses Error code 400 is returned for invalid parameters and unexpected errors. All error messages are returned in this format: ```json { "errorCode": "The 3-digit HTML error code", "errorMessage": "string" } ``` Error codes and messages are listed on the [Error Codes page](https://thingspace.verizon.com/documentation/api-documentation.html#/http/device-location/error-codes), along with explanations and suggestions for corrective actions.