# Insurance Payment Transactions V1 — Developer Guide

> **Reference:** [Insurance Payment Transactions (V1) Endpoint Documentation](https://papidocs.hs1api.com/publicapi/api-financial-management/insurance-payment-transactions-(v1))


Insurance payment transactions record payments received from insurance carriers against a patient's insurance claim. Each stored payment is associated with claim and distribution data returned on **GET**.

Key behaviors (read model):

- `ledgerType` is `InsurancePayment` for primary insurance payment rows
- `ownership` is typically `PATIENT` on returned records
- `distributions` describe how the payment applies to procedure charges


> **Published OpenAPI:** The bundled Swagger specification for `/v1/transactions/insurancepayments` documents **GET** (bulk list and get-by-id) only. This guide matches that surface.


## GET — Bulk List Insurance Payment Transactions

Returns a paginated list of insurance payment 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` |
| `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` |


### Example Requests

Fetch all insurance payments for a patient:

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

Fetch insurance payments modified since a date:

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

## GET — Insurance Payment Transaction by ID

### Parameters

| Parameter | In | Required | Type | Description |
|  --- | --- | --- | --- | --- |
| `transactionId` | path | Yes | integer | The ID of the insurance payment 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/insurancepayments/100000042301
```

## Streaming

Insurance payment transactions are streamable via the [Streaming API](https://papidocs.hs1api.com/publicapi/api-consumer-guide#streaming). Events are published under the `TransactionV1` domain type.

### Routing Key Format

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

### Example Routing Keys

Listen for all insurance payment events across all locations:

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

Listen for stream `CREATE` events only at a specific location:

```
66d22762060811049b50d085.1000000000123.TransactionV1.CREATE
```

### Operations Emitted (stream)

| Stream operation | When |
|  --- | --- |
| `CREATE` | When a new insurance payment is recorded in the system |
| `CREATE` | When a correction (rebill) is applied — the replacement record typically emits `CREATE` |


> **No `UPDATE` or `DELETE` stream events for this sub-type (typical):** Insurance payment corrections usually emit `CREATE` for the new or revised record; the cancelled original does not emit `DELETE` in the common pattern described for payments.


> **Filtering by `ledgerType`:** All transaction sub-types share the `TransactionV1` domain. Filter on `ledgerType == InsurancePayment` in the event payload to identify insurance payment events.


## Response Structure

A successful **GET** returns `200` with:

| Field | Type | Description |
|  --- | --- | --- |
| `data` | object or array | The insurance payment transaction, or a page of transactions |
| `warnings` | array | Non-fatal warnings |
| `errors` | array | Field-level or request errors when applicable |


For bulk GET, `data` is an array and includes `meta.pagination`.

### `data` Object — Insurance Payment Fields

| Field | Type | Read-Only | Description |
|  --- | --- | --- | --- |
| `id` | integer | Yes | Unique transaction ID |
| `type` | string | Yes | Always `"Transaction"` |
| `ledgerType` | string | Yes | Always `InsurancePayment` |
| `ownership` | string | Yes | Always `PATIENT` |
| `amount` | number | No | Payment amount |
| `transactionDate` | string (date) | No | `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 | No | Partial payment flag |
| `metBasic` | number | No | Deductible met — basic |
| `metPreventive` | number | No | Deductible met — preventive |
| `metMajor` | number | No | Deductible met — major |
| `metOrtho` | number | No | Deductible met — ortho |
| `note` | string | No | Free-text note |
| `previousTransaction` | object | Yes | Ref to replaced record |
| `replacedByTransaction` | object | Yes | Ref to replacement record |
| `patient` | object | — | `{ id }` |
| `location` | object | — | `{ id }` |
| `organizationLedgerType` | object | — | `{ id }` |
| `insuranceClaim` | object | — | `{ id }` |
| `bulkInsurancePayment` | object | — | `{ id }` (if part of a bulk batch) |
| `patientPaymentBilling` | object | — | `{ checkNumber, bankNumber, referenceNumber }` |
| `transactionTags` | object | — | `{ orderIndex: { id } }` |
| `distributions` | array | — | `[{ chargeId, chargeLocationId, appliedAmount, isActive }]` |


## Errors & Warnings Reference

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

The request parameters or filter are invalid or cannot be processed.

#### `401` — Unauthorized

|  |  |
|  --- | --- |
| **Message** | Authentication is required and has failed or has not been provided. |
| **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 insurance payment 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. |
| **Fix** | Confirm the `transactionId` or filter IDs are correct and belong to your organization. |


#### `408` — Request Timeout

|  |  |
|  --- | --- |
| **Message** | The server timed out while processing the request. |
| **Fix** | Narrow filter criteria and retry. |


#### `429` — Too Many Requests

|  |  |
|  --- | --- |
| **Message** | Rate limit exceeded. |
| **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. |