# Patient Insurance Plans V1 — Developer Guide

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


This guide covers the **read** operations published for Patient Insurance Plans V1: bulk list, get by id, and total count. For parameter details and schema definitions, use the official reference above.

## GET — Bulk Patient Insurance Plans

This endpoint returns patient insurance plan records for your organization based on filter criteria.

### Recommended Filters

Narrow your query with one or more filters. Supported filter keys:

| Filter | Supported operators |
|  --- | --- |
| `id` | `==`, `->` |
| `patient.id` | `==`, `->` |
| `lastModified` | `>`, `<`, `>=`, `<=` |


Combine filters with commas, for example: `filter=patient.id==123,lastModified>2025-01-01T00:00:00.000Z`.

> See the endpoint reference for the full up-to-date list of supported parameters and operator descriptions.


### Important Notes

> **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 for more information.


> **⚠️ Not recommended:** Do **not** rely on offset-style pagination with the `page` parameter for large data sets. It can be slow and unreliable at scale.


> **✅ Recommended:** Use **`lastId`** cursor pagination (see below).


## Paginating with `lastId`

`lastId` uses the plan record’s `id` as a cursor. Pass the **largest** id from the previous page as `lastId` for the next request (as described in the OpenAPI `lastId` parameter).

### Step 1 — Initial request

Send the first request without `lastId`:

```
GET /api/v1/patientinsuranceplans?pageSize=500&filter=lastModified>2025-02-16T00:00:00.000Z,patient.id==123456
```

### Step 2 — Subsequent requests

Use the `id` of the **last** object in the `data` array as `lastId`:

```
GET /api/v1/patientinsuranceplans?lastId=1000000020703&pageSize=500&filter=lastModified>2025-02-16T00:00:00.000Z,patient.id==123456
```

### Step 3 — Repeat

Continue until `data` is empty or you have retrieved all records you need.

## GET — Patient Insurance Plan by ID

```
GET /api/v1/patientinsuranceplans/{patientInsurancePlanId}
```

Returns a single plan when it exists for your organization. Use the official reference for `responseFields` and response shape.

## GET — Total Count

```
GET /api/v1/patientinsuranceplans/totalcount
```

Uses the **same filter syntax and filter keys** as the bulk GET for this resource. For how `pagination.total` behaves on bulk GET responses (including when it may be `0` or omitted), see **[Bulk GET — Total Count Behavior](/publicapi/bulk-get-total-count)**.

## Streaming API

For real-time creates and updates to patient insurance plans, use the **Streaming API** instead of polling bulk GET on a fixed schedule. Setup is covered in **[Creating and Setting Up Webhooks for the StreamAPI](/publicapi/streamapi-webhooks-setup)**.

## Response Structure

A successful `200` on bulk GET returns a **`PatientInsurancePlanBulkResponseWrapperV1`** object:

| Field | Type | Description |
|  --- | --- | --- |
| `data` | array | Array of `PatientInsurancePlanV1` objects |
| `warnings` | array | Non-fatal warnings (operation still succeeded) |
| `errors` | array | Field-level or structural errors |
| `meta` | object | Pagination metadata — see `meta.pagination` |


### `meta.pagination`

| Field | Type | Description |
|  --- | --- | --- |
| `lastId` | integer | Id of the last record returned; pass as `lastId` on the next request when using cursor pagination. |


### `PatientInsurancePlanV1` (summary)

Each element of `data` is one patient insurance plan. Common fields include:

| Field | Description |
|  --- | --- |
| `id` | Unique identifier for the plan record |
| `patient` | Linked model reference to the patient |
| `subscriberInsurancePlan` | Linked model reference to the subscriber insurance plan |
| `startDate`, `endDate` | Coverage dates |
| `relationshipToSubscriber` | e.g. `SELF`, `SPOUSE`, `CHILD`, `OTHER` |
| `eligible`, `note`, `eligibilityCheckType` | Eligibility and notes |
| `responsibilities` | Array of responsibility rows (dates, `paymentResponsibilityOrder`) |
| Benefit usage fields | Such as `previous_benefitYear`, `current_benefitYear`, and related deductible / benefit usage fields |


> For the authoritative field list and formats, use the **`PatientInsurancePlanV1`** schema in the official API reference.


## Errors & Warnings Reference

details
summary
strong
HTTP status code errors
— click to expand
These apply to the Patient Insurance Plans V1 **read** endpoints (bulk GET, GET by id, total count).

#### `400` — Bad Request

The query parameters are invalid or cannot be processed. Check `filter` syntax, `page` / `pageSize` / `lastId`, and `responseFields` against the official documentation.

#### `401` — Unauthorized

|  |  |
|  --- | --- |
| **Message** | Authentication is required and has failed or has not been provided. |
| **Why** | No valid token was sent, the token is expired, or the token is malformed. |
| **Fix** | Send a valid Bearer token in the `Authorization` header. See the [API Consumer Guide](https://papidocs.hs1api.com/publicapi/api-consumer-guide) for authentication. |


#### `403` — Forbidden

|  |  |
|  --- | --- |
| **Message** | The request is understood, but it has been refused or access is not allowed. |
| **Why** | The caller is not allowed to perform this operation for the organization or resource. |
| **Fix** | Confirm your integration credentials and that the organization has enabled the capabilities needed for this API. See the [API Consumer Guide](https://papidocs.hs1api.com/publicapi/api-consumer-guide). |


#### `404` — Not Found

|  |  |
|  --- | --- |
| **Message** | The requested resource is either missing or does not exist. |
| **Why** | On GET by id: no plan exists for the given `patientInsurancePlanId` in your organization, or the id is not valid (for example `0` or non-numeric). |
| **Fix** | Confirm the id and organization context. |


#### `408` — Request Timeout

|  |  |
|  --- | --- |
| **Message** | The server timed out while processing the request. |
| **Why** | The server took too long to respond, often due to a heavy query or load. |
| **Fix** | Retry with a narrower `filter` or smaller `pageSize`. |


#### `429` — Too Many Requests

|  |  |
|  --- | --- |
| **Message** | Rate limit exceeded. |
| **Why** | Too many requests in a short period for this endpoint. |
| **Fix** | Back off and retry; reduce polling frequency. See [Rate limiting](https://papidocs.hs1api.com/publicapi/api-consumer-guide#rate-limiting) in the API Consumer Guide. |


#### `500` — Internal Server Error

|  |  |
|  --- | --- |
| **Message** | An unexpected error occurred. |
| **Why** | An unhandled server-side error. |
| **Fix** | Retry; if it persists, contact support with request details and a timestamp. |


details
summary
strong
Query and read-path validation
— click to expand
Invalid **filter** expressions, unsupported filter keys or operators, or bad **responseFields** values can produce `400` responses with details in the `errors` array. Align filters with the supported keys listed in this guide and in the official OpenAPI description for `GET /v1/patientinsuranceplans`.