# Transactions Total Count V1 — Developer Guide

> **Reference:** [Total Count (V1) Endpoint Documentation](https://papidocs.hs1api.com/publicapi/api-financial-management/transactions-(v1))


The total count endpoint returns the number of transaction records matching a given set of filter criteria. Use this endpoint when you need to know how many records exist before deciding whether to paginate a bulk fetch, or to display a record count in a UI without retrieving the full data set.

> **Relationship to bulk GET:** This endpoint uses the same filter syntax as [GET /v1/transactions](/publicapi/endpoints/transactions-v1). Applying the same filter to both endpoints will give you the count and the records for the same set of data.


## GET — Transaction Total Count

Returns the total count of transaction records matching the filter.

> **⚠️ Rate Limited:** This endpoint is rate limited. See the [rate limiting guide](https://papidocs.hs1api.com/publicapi/api-consumer-guide#rate-limiting) for details.


### Parameters

| Parameter | In | Required | Type | Description |
|  --- | --- | --- | --- | --- |
| `Organization-ID` | header | Yes | string | The organization ID |
| `filter` | query | Yes | string | Filter criteria using the same syntax as `GET /v1/transactions` (see filter keys below) |


### Filter Keys

| Filter Key | Operators | Example |
|  --- | --- | --- |
| `id` | `->` | `?filter=id->[123,124]` |
| `ledgerType` | `==`, `!=` | `?filter=ledgerType==InsurancePayment` |
| `patient.id` | `==`, `->` | `?filter=patient.id==789` |
| `provider.id` | `==` | `?filter=provider.id==456` |
| `transactionDate` | `>`, `<`, `>=`, `<=` | `?filter=transactionDate>=2025-01-01` |
| `location.id` | `==`, `!=`, `->` | `?filter=location.id==123` or `?filter=location.id==ALL` |
| `lastModified` | `>`, `<`, `>=`, `<=` | `?filter=lastModified>=2025-01-01` |


> **Important:** A valid filter is required on every request. If no date-limiting filter is provided, one will be automatically applied using `transactionDate >= <1 year ago>` (or the organization's creation date if more recent). To control the range explicitly, include a `transactionDate` or `lastModified` filter.


### Example Requests

Count all transactions for a patient:

```
GET /api/v1/transactions/totalcount?filter=patient.id==12000006542062
```

Count insurance payments for a location in a date range:

```
GET /api/v1/transactions/totalcount?filter=ledgerType==InsurancePayment,location.id==123,transactionDate>=2025-01-01,transactionDate<=2025-03-31
```

Count all transactions modified since a date across all locations:

```
GET /api/v1/transactions/totalcount?filter=lastModified>=2025-01-01,location.id==ALL
```

## Response Structure

A successful `200` response returns:

| Field | Type | Description |
|  --- | --- | --- |
| `data` | object | Contains the count result (see below) |
| `warnings` | array | Non-fatal warnings |
| `errors` | array | Field-level or structural errors |


### `data` Object

| Field | Type | Description |
|  --- | --- | --- |
| `total` | integer | The number of transaction records matching the filter criteria |


#### Example Response

```json
{
  "data": {
    "total": 342
  },
  "warnings": [],
  "errors": []
}
```

## Errors & Warnings Reference

details
summary
strong
HTTP Status Code Errors
— click to expand
#### `400` — Bad Request

The request filter is invalid or cannot be processed.

#### `401` — Unauthorized

|  |  |
|  --- | --- |
| **Message** | Authentication is required and has failed or has not been provided. |
| **Why** | Missing, expired, or malformed Bearer token. |
| **Fix** | Provide a valid Bearer token in the `Authorization` header. |


#### `403` — Forbidden

|  |  |
|  --- | --- |
| **Message** | The request is understood, but it has been refused or access is not allowed. |
| **Why** | The caller is not permitted to use this endpoint for this organization. |
| **Fix** | Confirm credentials and organization access with your integration administrator. |


#### `408` — Request Timeout

|  |  |
|  --- | --- |
| **Message** | The server timed out while processing the request. |
| **Why** | High server load or an overly broad filter. |
| **Fix** | Narrow filter criteria and retry. |


#### `429` — Too Many Requests

|  |  |
|  --- | --- |
| **Message** | Rate limit exceeded. |
| **Why** | Too many requests in a short period. |
| **Fix** | Implement exponential backoff. See the [rate limiting guide](https://papidocs.hs1api.com/publicapi/api-consumer-guide#rate-limiting). |


#### `500` — Internal Server Error

|  |  |
|  --- | --- |
| **Message** | An unexpected error occurred. |
| **Fix** | Retry. If the issue persists, contact support. |


details
summary
strong
Field-Level Validation Errors
— click to collapse
### `filter`

**Error:** Missing or invalid filter.

|  |  |
|  --- | --- |
| **Why** | The `filter` parameter was omitted, left empty, or used an unsupported key or operator. |
| **Fix** | Provide at least one valid filter key and value, e.g. `?filter=lastModified>=2025-01-01`. |