# Appointment Histories V1 — Developer Guide

> **Reference:** [Appointment Histories (V1) Endpoint Documentation](https://papidocs.hs1api.com/publicapi/api-appointment-management/appointment-histories-(v1))


## GET — Bulk Appointment Histories

This endpoint retrieves appointment history records belonging to locations within your organization. It is a **read-only** endpoint — no POST, PUT, or DELETE operations are available.

### Recommended Filters

Always narrow your query with at least one filter. The following filter keys are supported:

| Filter | Supported Operators |
|  --- | --- |
| `appointment.id` | `==`, `->` |
| `lastModified` | `>`, `>=`, `<`, `<=` |


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


### Important Notes

> **⚠️ Default Date Filter:** If you do not provide a date-limiting filter (such as `lastModified`), one will be automatically applied to your query.


> **⚠️ No `lastId` Pagination:** Unlike some other endpoints, `/v1/appointmenthistories` does **not** support `lastId` cursor pagination. Use `page` and `pageSize` to paginate through results.


> **⚠️ Not Recommended:** Avoid paginating through large data sets without a filter. Always apply a `lastModified` or `appointment.id` filter to limit the result set before paginating.


## Paginating with `page` and `pageSize`

The `/v1/appointmenthistories` endpoint uses offset-based pagination via the `page` and `pageSize` query parameters.

### Step 1 — Initial Request

Send your first request without a `page` parameter (defaults to page 1):

```
GET /api/v1/appointmenthistories?pageSize=500&filter=lastModified>2025-02-16T00:00:00.000Z
```

### Step 2 — Subsequent Requests

Increment the `page` parameter to retrieve the next set of results:

```
GET /api/v1/appointmenthistories?page=2&pageSize=500&filter=lastModified>2025-02-16T00:00:00.000Z
```

### Step 3 — Repeat

Continue incrementing `page` until the response returns an empty `data` array.

> **Note:** `pagination.total` will **not** be present in the response when using the `page` parameter. Use the presence or absence of records in `data` to determine end-of-results. See [Bulk GET — Total Count Behavior](/publicapi/bulk-get-total-count) for more details.


## GET — By ID

Retrieve a single appointment history record by its unique ID:

```
GET /api/v1/appointmenthistories/{appointmentHistoryId}
```

The `appointmentHistoryId` path parameter must be a valid integer (minimum: `1`).

## Total Count

Use the total count endpoint to determine the number of appointment history records matching your filter criteria before paginating:

```
GET /api/v1/appointmenthistories/totalcount
```

> See [Bulk GET — Total Count Behavior](/publicapi/bulk-get-total-count) for details on how `pagination.total` behaves across different request types.


## Response Structure

### Bulk Response — `AppointmentHistoryBulkResponseWrapperV1`

A successful `200` response from the bulk GET returns an `AppointmentHistoryBulkResponseWrapperV1` object:

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


#### `meta.pagination` Object

| Field | Type | Description |
|  --- | --- | --- |
| `limit` | integer | The page size used for this request |
| `offset` | integer | The record offset applied to this request |
| `total` | integer | Present only when `page` and `lastId` are absent. Returns `0` — the total record count is not computed. |


### Single Record Response — `AppointmentHistoryResponseWrapperV1`

A successful `200` response from the GET by ID returns an `AppointmentHistoryResponseWrapperV1` object:

| Field | Type | Description |
|  --- | --- | --- |
| `data` | object | A single `AppointmentHistoryV1` object |
| `warnings` | array | Non-fatal warnings (operation still succeeded) |
| `errors` | array | Field-level or structural errors |


### `AppointmentHistoryV1` Object

All fields on this object are **read-only**.

| Field | Type | Description |
|  --- | --- | --- |
| `id` | integer | Unique appointment history record identifier |
| `type` | string | Resource type identifier |
| `lastModified` | string | Timestamp of the most recent update (ISO 8601) |
| `historyType` | string | The type of history event. Enum: `BROKEN`, `NOSHOW`, `RESCHEDULED`, `CANCELED` |
| `originalDateTime` | string | The original date and time of the appointment before the history event (ISO 8601) |
| `rescheduledDateTime` | string | The rescheduled date and time, if applicable (ISO 8601) |
| `insertDateTime` | string | The date and time the history record was created (ISO 8601) |
| `appointment` | object | Linked model reference to the associated appointment |
| `patient` | object | Linked model reference to the associated patient |


#### Linked Model Object (for `appointment` and `patient`)

| Field | Type | Description |
|  --- | --- | --- |
| `id` | integer | The unique identifier for the linked model |
| `type` | string | The type of the linked model (read-only) |
| `url` | string | The URL at which the linked model can be accessed (read-only) |


## Errors & Warnings Reference

details
summary
strong
HTTP Status Code Errors
— click to expand
These apply to all Appointment Histories V1 endpoints.

#### `400` — Bad Request

The request body or query parameters are invalid or cannot be processed.

#### `401` — Unauthorized

|  |  |
|  --- | --- |
| **Message** | Authentication is required and has failed or has not been provided. |
| **Why** | No valid auth token was sent, the token is expired, or the token is malformed. |
| **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 authenticated token does not have the required scope. Read operations require `model:read`. |
| **Fix** | Request a token that includes the `model:read` scope. |


#### `404` — Not Found

|  |  |
|  --- | --- |
| **Message** | The requested resource is either missing or does not exist. |
| **Why** | No appointment history record exists for the given `appointmentHistoryId` within your organization, or the ID is not a valid integer (e.g. `0` or non-numeric). |
| **Fix** | Confirm the appointment history ID is correct and belongs to your organization. |


#### `408` — Request Timeout

|  |  |
|  --- | --- |
| **Message** | The server timed out while processing the request. |
| **Why** | The server took too long to respond, often due to a complex query or high server load. |
| **Fix** | Retry the request. If the issue persists, simplify your query or contact support. |


#### `429` — Too Many Requests

|  |  |
|  --- | --- |
| **Message** | Rate limit exceeded. |
| **Why** | Your client has made too many requests in a short period of time. |
| **Fix** | Implement exponential backoff and retry logic. Reduce request frequency. |


#### `500` — Internal Server Error

|  |  |
|  --- | --- |
| **Message** | An unexpected error occurred. |
| **Why** | An unhandled server-side error occurred. |
| **Fix** | Retry the request. If the issue persists, contact support with the request details and timestamp. |