Retrieve detailed device-level usage

The detailed usage data is structured as a nested format, providing comprehensive records for all end customers (clients) associated with the MSP. Each client record includes:

A list of devices with detailed information.
Aggregated total usage by service for each customer, including metrics such as the amount of usage, price, and associated product features.

Response structure

Parameter	Description	Supported values
AccountName	The name of the account	<std::string>
BpAccountId	The unique identifier for the BpAccount	<int> Integer
Cid	CID, part of contract number	<int> Integer
ContractId	The unique identifier for the contract	<int> Integer
ContractNumber	The number of the contract	<std::string>
ContractStatus	The status of the contract	<std::string>
Created	Record created date	<datetime>
PgaCode	4-character numerical code for the product group	<std::string>
Pid	Product ID	<int> Integer
ProductName	The name of the product	<std::string>
RateClassId	Rate Class ID	<int> Integer
SfdcAccountId	Salesforce Account ID for the requesting MSP	<std::string>
TenantId	The unique identifier for the Tenant	<int> Integer
TimeFrame	The billing period in YYYYMM format	<int> Integer
Updated	Last update date	<datetime>
TotalByContracts	Total usage (aggregated) of services under each contract	TotalByContracts (has child objects of its own see the TotalByContracts child objects table below)
Clients	A list of clients with all devices recorded under invoice	Clients (has child objects of its own see the Clients child objects table below)

TotalByContracts child objects

Parameter	Description	Supported values
AccountName	The name of the account	<std::string>
BpAccountId	The unique identifier for the Bp account	<int> Integer
Cid	CID, part of contract number	<int> Integer
ContractId	The unique identifier for the contract	<int> Integer
ContractNumber	The number of the contract	<std::string>
InvoiceId	The unique identifier for the invoice	<int> Integer
SfdcAccountId	Salesforce Account ID for the requesting MSP	<std::string>

Clients child objects

Parameter	Description	Supported values
ClientId	Client ID	<std::string>
Devices	The list of all devices recorded under the invoice	<array>
Name	Client name	<std::string>
TotalByService	Total usage of services by client	<array>

Sample response

{
    "AccountName": "Best MSP",
    "BpAccountId": 12348,
    "Cid": "234578",
    "ContractId": 234578,
    "ContractNumber": "MSP-234578-01",
    "ContractStatus": "ACTIVE",
    "Created": "2021-01-04 20:02:13.470",
    "PgaCode": "0100",
    "Pid": "0118M-0000-0000-UK",
    "ProductName": "Cove Data Protection | Data Protection Plan | MSP",
    "RateClassId": "234567",
    "SfdcAccountId": "001H234578asdfIAS",
    "TenantId": "0100_678905",
    "TimeFrame": 202405,
    "Updated": "2023-12-31 22:09:37.204",
    "TotalByContracts": [
        {
            "AccountName": "Best MSP",
            "BpAccountId": "345678",
            "Cid": "234578",
            "ContractId": "234567",
            "ContractNumber": "MSP-234578-01",
            "InvoiceId": "123467",
            "SfdcAccountId": "001H234578asdfIAS"
        }
    ],
    "Clients": []
}

Possible errors

{
    "PSA Distributor Usage Detail Devices V1 ": "Failed",
    "SfdcAccountId": "001H234578asdfIAS",
    "Error": "Internal Error. Please contact support."
}

🚧
Internal Error: This error could mean you provided an invalid contract or invoice ID or combination of invoice ID and timeframe. Double-check your details. Otherwise, contact support.

{
    "message": "Unauthorized",
    "http_status_code": 401
}

🚧
The above error is 401 unauthorized: Check that you have entered your MSPID and API key correctly.