# Location Production Net Schedule V1 — Developer Guide

> **Reference:** [LocationProductionNetSchedule (V1) Endpoint Documentation](https://papidocs.hs1api.com/publicapi/api-reports-and-analytics/locationproductionnetschedule-(v1))


## GET — Production Net Schedule Report

This endpoint returns a list of scheduled production amounts for a location over a date range. Each record represents a single scheduled appointment's net production amount and its scheduled date/time. It is suited for reporting use cases — for example, calculating expected production for a provider or location over the coming week.

> **Looking to retrieve this report asynchronously?** Use the [Async Endpoints V1](/publicapi/endpoints/async-v1) guide — the `/beta/locationproductionnetschedule` endpoint streams results to the Streaming API.


### Parameters

| Parameter | In | Required | Type | Description |
|  --- | --- | --- | --- | --- |
| `Organization-ID` | header | Yes | string | Your organization identifier |
| `filter` | query | Yes | string | Filter expression. `fromDate` is required. See [Required Filters](#required-filters) and [Optional Filters](#optional-filters) below |
| `responseFields` | query | No | string | URL-encoded comma-delimited list of fields to return. Use `ALL` for all fields. Valid values: `ALL`, `date`, `scheduledAmount` |


### Required Filters

The following filter **must** be included on every request:

| Filter Key | Supported Operators | Description |
|  --- | --- | --- |
| `fromDate` | `==` | Start date for the report window (format: `YYYY-MM-DD`, e.g. `2025-01-14`) |


### Optional Filters

| Filter Key | Supported Operators | Description |
|  --- | --- | --- |
| `location.id` | `==`, `!=`, `->` | Filter by location ID, exclude a location, or pass a list of IDs. Use `ALL` or `*` for all locations |
| `provider.id` | `==`, `->` | Filter by a single provider ID or a list of provider IDs. Mutually exclusive with `patient.id` and `appointment.id` |
| `patient.id` | `==`, `->` | Filter by a single patient ID or a list of patient IDs. Mutually exclusive with `provider.id` and `appointment.id` |
| `appointment.id` | `==`, `->` | Filter by a single appointment ID or a list of appointment IDs. Mutually exclusive with `provider.id` and `patient.id` |
| `range` | `==` | Number of days to include in the report window. Valid range: `1`–`31`. Defaults to single day if omitted |
| `timezone` | `==` | Timezone for date calculations (e.g. `America/New_York`). Defaults to the location or organization timezone |
| `isPrimaryWriteOff` | `==` | **Deprecated** — do not use in new implementations. Passing this filter will return a warning and the filter will be ignored |


> **Note:** `provider.id`, `patient.id`, and `appointment.id` are mutually exclusive — only one may be used per request. Passing more than one will return a `400` validation error.


> **Upcoming Breaking Change:** `location.id` (as a list of IDs or `["ALL"]`) will become a **required** filter. For a transitional period, omitting `location.id` defaults to all locations. Update your integrations to explicitly pass `location.id` to avoid breakage when this change is enforced.


### Important Notes

> **Note:** If you receive a `403 Forbidden` response from this endpoint, please contact [Public API support](https://papidocs.hs1api.com/publicapi/api-consumer-guide#support).


### Example Requests

Fetch production net schedule for a date range at a location:

```
GET /api/v1/locationproductionnetschedule?filter=fromDate==2025-01-14,range==7,location.id->[123,124]
```

Fetch for all locations:

```
GET /api/v1/locationproductionnetschedule?filter=fromDate==2025-01-14,range==7,location.id==ALL
```

Fetch for a specific provider:

```
GET /api/v1/locationproductionnetschedule?filter=fromDate==2025-01-14,range==7,provider.id==789
```

Fetch for a specific patient:

```
GET /api/v1/locationproductionnetschedule?filter=fromDate==2025-01-14,patient.id==456
```

Fetch for a specific appointment:

```
GET /api/v1/locationproductionnetschedule?filter=fromDate==2025-01-14,appointment.id==345
```

With a specific timezone and limited response fields:

```
GET /api/v1/locationproductionnetschedule?filter=fromDate==2025-01-14,range==7,location.id==123,timezone==America/Chicago&responseFields=date,scheduledAmount
```

## Response Structure

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

| Field | Type | Description |
|  --- | --- | --- |
| `data` | array | Array of production net schedule objects (see below) |
| `warnings` | array | Non-fatal warnings (operation still succeeded) |
| `errors` | array | Field-level or structural errors |


### `data` Array Items

Each item in `data` represents one scheduled appointment's net production amount.

| Field | Type | Description |
|  --- | --- | --- |
| `date` | string | The scheduled date and time of the appointment (ISO 8601 datetime, e.g. `2022-02-26T00:00:00.000Z`) |
| `scheduledAmount` | integer | The net scheduled production amount for the appointment, in cents (e.g. `10000` = $100.00) |


### Deprecated Filter Warning

If `isPrimaryWriteOff` is included in the `filter` parameter, the filter is silently dropped and a warning is added to the `warnings` array:

| Field | Value |
|  --- | --- |
| `title` | `"Deprecated filter"` |
| `description` | `"Filter isPrimaryWriteOff is deprecated."` |
| `source` | `"isPrimaryWriteOff"` |


## Errors & Warnings Reference

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

#### `400` — Bad Request

The request query parameters are invalid or cannot be processed. See the [Field-Level Validation Errors](#field-level-validation-errors) section below for specific causes.

#### `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 `ascend:read` scope, or access to this endpoint has not been enabled for your organization. |
| **Fix** | Ensure your token includes the `ascend:read` scope. If the scope is correct, contact [Public API support](https://papidocs.hs1api.com/publicapi/api-consumer-guide#support). |


#### `404` — Not Found

|  |  |
|  --- | --- |
| **Message** | The requested resource is either missing or does not exist. |
| **Why** | No scheduled production data exists for the given filter criteria within your organization. |
| **Fix** | Confirm your filter values (location, provider, patient, or appointment IDs) are correct and belong 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 large date range, complex query, or high server load. |
| **Fix** | Retry the request. If the issue persists, reduce the `range` value, narrow your filters, or contact support with the request details and timestamp. |


#### `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. See the [rate limiting guide](https://papidocs.hs1api.com/publicapi/api-consumer-guide#rate-limiting). |


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


details
summary
strong
Field-Level Validation Errors
— click to collapse
These errors are returned in the `errors` array of the response body alongside a `400` status code.

### `fromDate`

**Error:** `fromDate` and `location.id` are required.

|  |  |
|  --- | --- |
| **Why** | The `fromDate` filter was omitted entirely, or the `filter` parameter was empty. `fromDate` is the only required filter. |
| **Fix** | Include `fromDate==<YYYY-MM-DD>` in your `filter` query parameter, e.g. `filter=fromDate==2025-01-14`. |


**Error:** Invalid date format for `fromDate`.

|  |  |
|  --- | --- |
| **Why** | The value provided for `fromDate` is not a valid date string in `YYYY-MM-DD` format. |
| **Fix** | Provide a valid date in `YYYY-MM-DD` format, e.g. `fromDate==2025-01-14`. |


### `location.id`

**Error:** Invalid ID for `location.id`.

|  |  |
|  --- | --- |
| **Why** | The value provided for `location.id` is not a valid integer, `ALL`, or `*`. |
| **Fix** | Provide a valid integer location ID (e.g. `location.id==123`), a list (e.g. `location.id->[123,124]`), or use `location.id==ALL` to target all locations. |


### `provider.id` / `patient.id` / `appointment.id`

**Error:** Only one filter should be picked from the list: appointment, provider, patient.

|  |  |
|  --- | --- |
| **Why** | More than one of `provider.id`, `patient.id`, or `appointment.id` was included in the same request. These filters are mutually exclusive. |
| **Fix** | Use only one of `provider.id`, `patient.id`, or `appointment.id` per request. |


### `range`

**Error:** Invalid value for `range`.

|  |  |
|  --- | --- |
| **Why** | The value provided for `range` is not an integer between `1` and `31`. |
| **Fix** | Provide an integer value between `1` and `31` inclusive, e.g. `range==7`. |


### `timezone`

**Error:** Invalid value for `timezone`.

|  |  |
|  --- | --- |
| **Why** | The timezone string provided is not a valid IANA timezone identifier. |
| **Fix** | Use a valid IANA timezone string such as `America/New_York`, `America/Chicago`, or `America/Los_Angeles`. |