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.

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v1/devices/usage/actions/unbilledusage/list

Resource Path and Query Parameters

None.

Header Parameters

The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token, and must set the content-type to JSON.

Parameter Name Data Type Description
Authorization
required		 string HTTP Authorization bearer token.
VZ-M2M-Token
required		 string A valid session token returned by POST /session/login.
Content-Type
required		 string Must be application/json.

Request Body

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 date-time Start date for the usage to be retrieved.
    endDate date-time End date for the usage to be retrieved.

Example Request

{
  "accountName": "0000123456-00001",   
  "dateRange": {
    "startDate": "2023-07-01T00:00:00Z",
    "endDate": "2023-07-02T00:00:00Z"
  }
}

Success Responses

Status 200

{
   "requestId": "be36accb-0a9a-4367-93ab-0af6c4ed256a"
}

Response 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

Status 400

All error messages are returned in this format:

{
      "errorCode": "error code string",
      "errorMessage": "error message string"
    }

Callback Example

{
  "requestId": "be36accb-0a9a-4367-93ab-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"
          },
          "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"
          },
          "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 The start date for the usage.
            endDate string The end date for the usage
        devices array An array of devices responding to the request.
            deviceId object The ID 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".
            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 long Total usage recorded in the units defined in unitOfMeasure.
status string

Indicates the status of the callback. Valid values are:

  • SUCCESS
  • FAILED
callbackCount integer The number of callbacks for this request.
maxCallbackThreshold integer The maximum number of callbacks allowed for this request.