# Insurance Claims V1 — Developer Guide

> **Reference:** [InsuranceClaims (V1) Endpoint Documentation](https://papidocs.hs1api.com/publicapi/api-insurance-management/insuranceclaims-(v1))


This guide covers **read** operations for Insurance Claims V1, with emphasis on retrieving insurance and patient estimate data at scale through the bulk GET endpoint.

## GET — Bulk Insurance Claims

```
GET /api/v1/insuranceclaims
```

Returns insurance claim records for your organization based on filter criteria. Use this endpoint — not repeated GET-by-ID calls — when synchronizing large claim volumes.

> **Rate limiting:** This endpoint is rate limited. See [Rate limiting](https://papidocs.hs1api.com/publicapi/api-consumer-guide#rate-limiting) in the API Consumer Guide.


> **✅ Recommended:** Use **`lastId`** cursor pagination with a **`lastModified`** (or other date) filter for incremental sync. See [Bulk GET — Total Count Behavior](/publicapi/bulk-get-total-count) for `pagination.total` behavior.


### Parameters

| Parameter | In | Required | Type | Description |
|  --- | --- | --- | --- | --- |
| `Organization-ID` | header | Yes | string | Organization context for the request |
| `filter` | query | No | string | Filter criteria (see filter keys below) |
| `responseFields` | query | No | string | Comma-delimited field list, or `ALL` |
| `pageSize` | query | No | string | Records per page |
| `lastId` | query | No | string | Largest claim ID from the previous page (cursor pagination) |
| `page` | query | No | string | Deprecated where `lastId` is supported |
| **`showEstimates`** | query | No | string | When `true`, includes per-procedure estimate fields on each claim in the response |


## Bulk estimate retrieval (`showEstimates`)

Insurance and patient estimate data lives on each claim's **`procedures`** array. Without `showEstimates`, bulk GET returns procedure references only (id, type, url). With **`showEstimates=true`**, each procedure includes the same estimate fields returned by GET by claim ID.

### Estimate fields on `procedures`

| Field | Description |
|  --- | --- |
| `writeOff` | Estimated write-off amount |
| `patientPortion` | Current estimated patient portion |
| `primaryInsurancePortion` | Current estimated primary insurance portion |
| `secondaryInsurancePortion` | Current estimated secondary insurance portion (when applicable) |
| `originalPatientPortion` | Original estimated patient portion at time of charge |
| `originalPrimaryInsurancePortion` | Original estimated primary insurance portion |
| `originalSecondaryInsurancePortion` | Original estimated secondary insurance portion (when applicable) |


> For authoritative types and formats, see the **`linkedEstimationModel`** / procedure schema in the official API reference.


### GET by ID vs bulk GET

| Operation | Estimate data |
|  --- | --- |
| `GET /api/v1/insuranceclaims/{claimId}` | Always included on `procedures` |
| `GET /api/v1/insuranceclaims` (bulk) | Included only when `showEstimates=true` |


Pass **`showEstimates=true`** on bulk GET to avoid one API call per claim when syncing estimates across a large organization.

### Example — single claim with estimates

```
GET /api/v1/insuranceclaims?filter=id==123456789&showEstimates=true
```

### Example — batch of claim IDs

```
GET /api/v1/insuranceclaims?filter=id->[123456789,123456790,123456791]&showEstimates=true
```

### Example — incremental sync by last modified

```
GET /api/v1/insuranceclaims?pageSize=500&filter=lastModified>=2025-01-01T00:00:00.000Z,location.id==ALL&showEstimates=true
```

Subsequent pages (use the largest `id` from the prior response as `lastId`):

```
GET /api/v1/insuranceclaims?lastId=1000000020703&pageSize=500&filter=lastModified>=2025-01-01T00:00:00.000Z,location.id==ALL&showEstimates=true
```

### Example response fragment

When `showEstimates=true`, each claim's procedures include estimate amounts:

```json
{
  "data": [
    {
      "id": "123456789",
      "procedures": [
        {
          "id": 1000000000086,
          "type": "PatientProcedureV1",
          "url": "https://example.com/api/v1/patientprocedures/1000000000086",
          "patientPortion": "25.00",
          "primaryInsurancePortion": "75.00",
          "writeOff": "0.00",
          "originalPatientPortion": "25.00",
          "originalPrimaryInsurancePortion": "75.00"
        }
      ]
    }
  ]
}
```

### Usage guidance

- **Omit `showEstimates`** (or use `showEstimates=false`) when you only need claim metadata — responses are faster and lighter.
- **Set `showEstimates=true`** when synchronizing estimate data; one bulk request can return many claims with estimates.
- **Scope filters** with `lastModified`, `location.id`, `patient.id`, or explicit `id` / `id->[...]` to avoid timeouts on large tenants.
- **Use `lastId` pagination** rather than offset `page` for large data sets.
- Bulk responses with `showEstimates=true` may be cached separately from requests without it (cache keys differ by parameter value).


## Recommended filters

| Filter | Supported operators |
|  --- | --- |
| `id` | `==`, `->` |
| `location.id` | `==`, `->` — use `ALL` or `*` for all locations |
| `patient.id` | `==`, `->` |
| `subscriber.id` | `==`, `->` |
| `renderingProvider.id` | `==`, `->` |
| `insuranceCarrier.id` | `==`, `->` |
| `carrierInsurancePlan.id` | `==`, `->` |
| `sentDate` | `>=`, `>`, `<=`, `<` |
| `lastModified` | `>=`, `>`, `<=`, `<` |


When filtering by `sentDate` or `lastModified`, results are returned in **descending** order (newest first).

Examples:

- `filter=patient.id==12345`
- `filter=id->[123456789,123456790]&showEstimates=true`
- `filter=lastModified>=2025-01-01T00:00:00.000Z,location.id==ALL&showEstimates=true`


## GET — Insurance Claim by ID

```
GET /api/v1/insuranceclaims/{claimId}
```

Returns a single claim. Per-procedure estimate fields are **always** present on `procedures` — no `showEstimates` parameter is required or supported on this operation.

Use GET by ID for ad hoc lookups; use bulk GET with `showEstimates=true` for high-volume estimate synchronization.

## GET — Total Count

```
GET /api/v1/insuranceclaims/totalcount
```

Uses the same filter syntax as bulk GET. The `showEstimates` parameter does not apply to total count. See **[Bulk GET — Total Count Behavior](/publicapi/bulk-get-total-count)**.

## StreamAPI Webhooks

For real-time claim creates and updates, use **StreamAPI webhooks (SNS)** instead of polling bulk GET. Setup is covered in **[Creating and Setting Up Webhooks for the StreamAPI](/publicapi/streamapi-webhooks-setup)**.

## Errors & Warnings Reference

HTTP status code errors
— click to expand
These apply to Insurance Claims V1 **read** endpoints (bulk GET, GET by id, total count).

#### `400` — Bad Request

Invalid query parameters — for example malformed `filter` syntax, invalid `showEstimates` value (must be `true` or `false`), or unsupported `responseFields`.

#### `401` — Unauthorized

Authentication failed or was not provided. Send a valid Bearer token in the `Authorization` header.

#### `403` — Forbidden

The caller is not allowed to perform this operation for the organization or resource.

#### `404` — Not Found

On GET by id: no claim exists for the given `claimId` in your organization.

#### `408` — Request Timeout

The query was too broad or the tenant is too large. Retry with a narrower filter, smaller `pageSize`, or a shorter date window.

#### `429` — Too Many Requests

Rate limit exceeded. Back off and reduce request frequency; prefer bulk GET with `showEstimates=true` over per-claim GET when syncing estimates.

#### `500` — Internal Server Error

Unexpected server error. Retry; contact support if it persists.