# Patient Procedure Transactions V1 — Developer Guide

> **Reference:** [Patient Procedure Transactions (V1) Endpoint Documentation](https://papidocs.hs1api.com/publicapi/api-financial-management/patient-procedure-transactions-(v1))


Patient procedure transactions represent procedure charges posted to the patient ledger. This is a **read-only** endpoint — procedure transactions are created and managed through the clinical and scheduling workflows, not directly through the financial API.

`ledgerType` values available on this endpoint:

| Value | Description |
|  --- | --- |
| `PatientProcedureLedger` | A standard procedure charge posted to the patient ledger |


## GET — Bulk List Patient Procedure Transactions

Returns a paginated list of patient procedure transaction entries filtered by the provided criteria.

> **⚠️ 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 (see filter keys below) |
| `responseFields` | query | No | string | Comma-delimited list of fields to include, or `ALL` |
| `page` | query | No | string | Page number for pagination |
| `pageSize` | query | No | string | Number of records per page |
| `lastId` | query | No | string | Largest transaction ID from the previous page, used for efficient date-filter pagination |


### Filter Keys

| Filter Key | Operators | Example |
|  --- | --- | --- |
| `id` | `->` | `?filter=id->[123,124]` |
| `ledgerType` | `==`, `!=` | `?filter=ledgerType==PatientProcedureLedger` |
| `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). Use `lastId` (not `page`) when paginating over date-filtered results for best performance.


### Example Requests

Fetch all procedure charges for a specific patient:

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

Fetch procedure charges for a location within a date range:

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

Fetch procedures modified since a date across all locations:

```
GET /api/v1/transactions/procedures?filter=lastModified>=2025-01-01,location.id==ALL&pageSize=100&lastId=5000
```

## GET — Patient Procedure Transaction by ID

Returns a single patient procedure transaction by its ID.

### Parameters

| Parameter | In | Required | Type | Description |
|  --- | --- | --- | --- | --- |
| `transactionId` | path | Yes | integer | The ID of the procedure transaction |
| `Organization-ID` | header | Yes | string | The organization ID |
| `responseFields` | query | No | string | Comma-delimited list of fields to include, or `ALL` |


### Example Request

```
GET /api/v1/transactions/procedures/100000042301
```

## Response Structure

A successful `200` response returns the following top-level structure:

| Field | Type | Description |
|  --- | --- | --- |
| `data` | object | The procedure transaction object (see below) |
| `warnings` | array | Non-fatal warnings (operation still succeeded) |
| `errors` | array | Field-level or structural errors |


For bulk responses, `data` is an array and the response also includes:

| Field | Type | Description |
|  --- | --- | --- |
| `meta.pagination` | object | Pagination metadata (`page`, `pageSize`, `total`) |


### `data` Object — Patient Procedure Transaction Fields

| Field | Type | Read-Only | Description |
|  --- | --- | --- | --- |
| `id` | integer | Yes | Unique transaction ID |
| `type` | string | Yes | Always `"Transaction"` |
| `ledgerType` | string | Yes | `PatientProcedureLedger` |
| `amount` | number | Yes | Procedure charge amount |
| `ownership` | string | Yes | `PATIENT` or `GUARANTOR` |
| `transactionDate` | string (date) | Yes | Date of the procedure (`YYYY-MM-DD`) |
| `entryDate` | string (date-time) | Yes | Creation timestamp |
| `lastModified` | string (date-time) | Yes | Last modification timestamp |
| `isAutomaticallyPosted` | boolean | Yes | System-posted flag |
| `isActive` | boolean | Yes | Active/cancelled status |
| `isPartialPayment` | boolean | Yes | Whether this is a partial payment |
| `note` | string | Yes | Notes on the procedure charge |
| `metBasic` | number | Yes | Deductible met — basic |
| `metPreventive` | number | Yes | Deductible met — preventive |
| `metMajor` | number | Yes | Deductible met — major |
| `metOrtho` | number | Yes | Deductible met — ortho |
| `previousTransaction` | object | Yes | Ref to replaced record |
| `replacedByTransaction` | object | Yes | Ref to replacement record |
| `patient` | object | Yes | `{ id }` |
| `location` | object | Yes | `{ id }` |
| `provider` | object | Yes | `{ id }` |
| `organizationLedgerType` | object | Yes | `{ id }` |
| `patientProcedure` | object | Yes | `{ id }` — linked clinical procedure record |
| `insuranceClaim` | object | Yes | `{ id }` — linked insurance claim, if applicable |
| `transactionTags` | object | Yes | `{ orderIndex: { id } }` |
| `distributions` | array | Yes | `[{ chargeId, appliedAmount, isActive }]` — applied payment/adjustment allocations |


## Streaming

Patient procedure transactions are streamable via the [Streaming API](https://papidocs.hs1api.com/publicapi/api-consumer-guide#streaming). Events are published under the `TransactionV1` domain type, shared with all other transaction sub-types.

### Routing Key Format

```
organizationId.locationId.TransactionV1.operationType
```

### Example Routing Keys

Listen for all transaction events (all sub-types) across all locations:

```
66d22762060811049b50d085.*.TransactionV1.*
```

### Operations Emitted

| Operation | When |
|  --- | --- |
| `CREATE` | When a procedure charge is posted to the ledger |
| `DELETE` | When a procedure charge is deleted |


> **Filtering by `ledgerType`:** All transaction sub-types share the `TransactionV1` domain. Filter on `ledgerType == PatientProcedureLedger` in the event payload to identify procedure charge events specifically.


## Errors & Warnings Reference

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

The request filter or parameters are invalid or cannot be processed. A filter is required on every bulk GET request.

#### `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 read procedure transactions for this organization. |
| **Fix** | Confirm credentials and organization access with your integration administrator. |


#### `404` — Not Found

|  |  |
|  --- | --- |
| **Message** | The requested resource is either missing or does not exist. |
| **Why** | No procedure transaction exists for the given ID within your organization. |
| **Fix** | Confirm the `transactionId` is correct and belongs to your organization. |


#### `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 with the request details and timestamp. |


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`. |