# Get Unbilled Usage ### `POST /api/m2m/v1/devices/usage/actions/unbilledusage/list` Use this endpoint to retrieve aggregated rated/unbilled usage up to the last 30 days for Server Name Indication (SNI) customers. ## 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/connectivity-management/guides/getting-started/introduction-to-the-connectivity-management-api). |Parameter Name|Data Type|Description| |-----|-----|-----| | **Authorization** *(required)* | string | HTTP Authorization request header containing a valid Bearer token: `Authorization: Bearer {token}` | | **VZ-M2M-Token** *(required)* | string | A valid session token returned by a Connectivity Management `POST /session/login` request. | | **Content-Type** *(required)* | string | Must be `application/json`. | ## HTTP Request ### `POST https://thingspace.verizon.com/api/m2m/v1/devices/usage/actions/unbilledusage/list` ## Request Parameters |Parameter Name|Data Type|Description| |-----|-----|-----| | **accountName** *(required)* | string | The name of a billing account. An account name is usually numeric, and must include any leading zeros. | | **dateRange** *(required)* | object | Defines the start date and end date for the usage. This must be within the last 30 days. | | **startDate** *(required)* | string ($date-time) | Start date for the usage to be retrieved. | | **endDate** *(required)* | string ($date-time) | End date for the usage to be retrieved. | ## Request Body Example Request ```json { "accountName": "0000123456-00001", "dateRange": { "startDate": "2024-08-01T00:00:00Z", "endDate": "2024-08-29T00:00:00Z" } } ``` ## Success Responses **Status 200** ```json { "requestId": "be36accb-eeee-ffff-gggg-0af6c4ed256a" } ``` ## Success Parameters |Parameter Name|Data Type|Description| |-----|-----|-----| | **requestId** | string | A unique string (UUID) that associates the request with the results that are sent via a callback message. | ## Failure Responses All error messages are returned in this format: ```json { "errorCode": "error code string", "errorMessage": "error message string" } ``` ## Callback Example ```json { "requestId": "be36accb-eeee-ffff-gggg-0af6c4ed256a", "deviceResponse": { "unbilledUsageResponse": { "accountName": "0000123456-00001", "timezone": "PST", "totalDevices": 9123, "currentDevices": 2000, "sentDevices": 4000, "remainingDevices": 3123, "dateRange": { "startDate": "2023-07-01", "endDate": "2023-07-02" }, "devices": [ { "deviceId": { "id": "32-digit EID value", "kind": "EID", "oemName" : "engagement name" }, "unitOfMeasure": "BYTES", "usageSegments": [ { "ratingGroup": "user-defined group name", "ratingGroupDetails": [ { "countryCode": "USA", "usage": 1731799 }, { "countryCode": "MEX", "usage": 1731799 } ] }, { "ratingGroup": "user-defined group name", "ratingGroupDetails": [ { "countryCode": "USA", "usage": 1825349 }, { "countryCode": "CAN", "usage": 1825349 } ] } ] }, { "deviceId": { "id": "32-digit EID value", "kind": "EID", "oemName" : "engagement name" }, "unitOfMeasure": "BYTES", "usageSegments": [] } ] } }, "status": "Success", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` ## Callback Parameters |Parameter Name|Data Type|Description| |-----|-----|-----| | **requestId** | string | The system generated ID of the callback request. | | **deviceResponse** | object | The response back from an active device. | | **unbilledUsageResponse** | object | The complete summary of billed usage in the account. | | **accountName** | string | The name of a billing account. An account name is usually numeric, and must include any leading zeros. | | **timezone** | string | Current value defaults to "**PST**", which is the Pacific time zone in the USA. | | **totalDevices** | integer | The total number of devices for the unbilled usage request. | | **currentDevices** | integer | The number of devices for the current response. | | **sentDevices** | integer | The number of devices before the current response. | | **remainingDevices** | integer | The number of devices left after the current response. | | **dateRange** | object | Defines the start date and end date range for the usage. This must be within the last 30 days. | | **startDate** | string ($date-time) | The start date for the usage. | | **endDate** | string ($date-time) | The end date for the usage. | | **devices** | array | An array of devices responding to the request. | | **deviceId** | object | The ID information of the device responding. | | **id** | string | The ID value for the type of ID. | | **kind** | string | The type of ID value. The only valid value is Electronic ID or "**EID**". | | **oemName** | string| The engagement name of the manufacturer. | | **unitOfMeasure** | string | Indicates the unit in which Usage is measured. | | **usageSegments** | array | An array that contains all of the usage information by `ratingGroup`. | | **ratingGroup** | object | The rating group for the `deviceId`. | | **ratingGroupDetails** | array | An array of usage details by country code. | | **countryCode** | string | 3-letter country code of where the usage occured. Conforms to ISO-3166. | | **usage** | integer (long) | Total usage recorded in the units defined in `unitOfMeasure`. | | **status** | string | Indicates the status of the callback. Valid values are: **SUCCESS** or **FAILED**. | | **callbackCount** | integer | The number of callbacks for this request. | | **maxCallbackThreshold** | integer | The maximum number of callbacks allowed for this request. |