Skip to main content

Billable Usage Retrieval

Updated

This article provides documentation for the endpoint, which allows you to programmatically fetch billable usage data for your organization.

Important: Authentication Requirements

To access this endpoint, you must use an Organization Level API Key.

  • Workspace-level API keys will be rejected with a 401 Unauthorized error.
  • The API key should be passed in the X-API-KEY request header.

Endpoint Details

Fetch Billable Usage

Retrieves a list of billable line items for a specific month and year.

Query Parameters

Parameter Type Required Description
month Long Yes The numeric month (e.g., 1 for January, 12 for December).
year Long Yes The four-digit year (e.g., 2026).

Response Object Details

The endpoint returns a JSON array of BillableLineItem objects.

BillableLineItem Object Structure

Field Type Description
id String Unique identifier for the line item.
type String The specific category/type of usage (see "Line Item Types" below).
rate Double The unit price or flat rate for this item.
description String A human-readable description of the charge.
flatRate Boolean true if the item is a fixed fee, false if it is calculated by quantity.
qty Double The total quantity consumed (summed across all workspaces).
total Double The calculated total cost for this line item.
workspaceUsage Array A breakdown of usage per workspace (see below).

WorkspaceQty Object Structure (Inside workspaceUsage)

Field Type Description
workspaceId Long The ID of the workspace associated with this usage.
description String Description of the workspace-specific usage.
qty Double The quantity of usage contributed by this workspace.


Line Item Types

The type field in the response will correspond to one of the following values:

SaaS & Services:

  • Adjustment: Manual billing adjustments.
  • DataBoost: General DataBoost usage.
  • DataBoostVerify: DataBoost Verification services.
  • DataBoostScore: DataBoost Scoring services.
  • KnownLitigator: Known Litigator Scrubbing.
  • NumberUtility: General Number Utility services.
  • DoNotCallApi: DNC API lookups.
  • Transactions: Standard transaction fees.
  • AegisTransactions: Aegis One transaction fees.
  • AegisLiteTransactions: Aegis Lite transaction fees.
  • AegisCoreTransactions: Aegis Core transaction fees.
  • AegisEtlTransactions: Aegis ETL Task transaction fees.
  • PlatformFee: Monthly platform service fee.
  • SupportFee: Monthly support fee.
  • FedDNCFee: Federal DNC access fee.
  • StateDNCFee: State DNC access fee.
  • ActiveProspectFee: Active Prospect integration fee.
  • VeriskFee: Verisk data fee.
  • RndFee: Reassigned Number Database fee.
  • CampaignFee: Campaign-related fees.
  • CorePoolFee: Core Pool management fee.
  • ByopPoolFee: BYOP (Bring Your Own Provider) Pool fee.
  • ProtectNumber: UC Protect service fee.
  • SmsLongCodeFee: SMS 10DLC Campaign fee.
  • SmsShortCodeFee: SMS Short Code fee.
  • SmsTollFreeFee: SMS Toll Free fee.

Network & Regulatory:

  • Calls: Inbound Callbacks.
  • Messages: SMS Usage.
  • MessageCarrierFees: SMS Carrier Pass-Thru fees.
  • InterstateVoIP: Telco Interstate VoIP charges.
  • IntrastateVoIP: Telco Intrastate VoIP charges.
  • TaxesAndFees: General taxes and fees.
  • FUSF: Federal Universal Service Fund charges.
  • TRS: Telecommunications Relay Service/Regulatory fees.


Sample Response

[
  {
    "id": "item_123",
    "type": "AegisTransactions",
    "rate": 0.005,
    "description": "Aegis One - Transactions",
    "flatRate": false,
    "qty": 1000.0,
    "total": 5.0,
    "workspaceUsage": [
      {
        "workspaceId": 101,
        "description": "Marketing Workspace",
        "qty": 1000.0
      }
    ]
  },
  {
    "id": "item_456",
    "type": "PlatformFee",
    "rate": 50.0,
    "description": "Platform Service Fee",
    "flatRate": true,
    "qty": 1.0,
    "total": 50.0,
    "workspaceUsage": []
  }
]


 

Related articles