Customers
SMS Usage
Returns the SMS usage for the current calendar month across all customers of the organization, sorted by usage descending.
GET /api/customers/sms-usage
Query Parameters
organizationId(required): The ID of the organization.envelope(optional):itemsanswers the list form described below.
Response
{
"total": 47,
"smsTotalCurrentMonth": 47,
"customers": [
{
"publicId": "6bfec6f6-245a-47ce-843b-157d97d56f88",
"name": "Customer A GmbH",
"status": "active",
"smsUsageCurrentMonth": 32
},
{
"publicId": "9a1c3d2e-8f4b-42a1-b7c9-3e5f12d84a90",
"name": "StartUp XY",
"status": "active",
"smsUsageCurrentMonth": 15
},
{
"publicId": "2d7e5f1a-6c3b-4d9e-a2f8-1b4c7e9d3a56",
"name": "Inactive Corp",
"status": "inactive",
"smsUsageCurrentMonth": 0
}
]
}Fields
| Field | Type | Description |
|---|---|---|
total | number | Deprecated, removed on 2027-01-18: use smsTotalCurrentMonth. Same value. |
smsTotalCurrentMonth | number | Sum of smsUsageCurrentMonth across all returned customers. |
customers[].publicId | string | Customer UUID. |
customers[].name | string | Customer display name. |
customers[].status | string | Customer status: active, inactive, marked_for_cancellation, or cancelled. |
customers[].smsUsageCurrentMonth | number | Number of SMS sent for this customer in the current month. Resets at the start of each calendar month. |
List form (?envelope=items)
With ?envelope=items the endpoint answers the standard list form. It becomes the default on 2027-01-18; the form above is deprecated.
{
"items": [
{ "publicId": "6bfec6f6-245a-47ce-843b-157d97d56f88", "name": "Customer A GmbH", "status": "active", "smsUsageCurrentMonth": 32 }
],
"total": 1,
"page": 1,
"perPage": 1,
"smsTotalCurrentMonth": 32
}Here total is the number of customers, not the SMS sum; the sum is smsTotalCurrentMonth. All customers come in one page.
Notes
- The usage counter
smsUsageCurrentMonthresets at the beginning of each calendar month. - Customers with zero usage are included in the response.
- Results are ordered by
smsUsageCurrentMonthdescending (highest usage first). - For the complete SMS quota and overage details of the entire organization, see the billing overview.
Common Errors
400Organization ID required401Unauthorized403Forbidden