Specialized APIsAutomotive OEMAPI Reference
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.
| 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
{
"accountName": "0000123456-00001",
"dateRange": {
"startDate": "2024-08-01T00:00:00Z",
"endDate": "2024-08-29T00:00:00Z"
}
}Success Responses
Status 200
{
"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:
{
"errorCode": "error code string",
"errorMessage": "error message string"
}Callback Example
{
"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. |