Reference: LocationProductionNetSchedule (V1) Endpoint Documentation
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 guide — the
/beta/locationproductionnetscheduleendpoint streams results to the Streaming API.
| 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 and 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 |
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) |
| 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, andappointment.idare mutually exclusive — only one may be used per request. Passing more than one will return a400validation error.
Upcoming Breaking Change:
location.id(as a list of IDs or["ALL"]) will become a required filter. For a transitional period, omittinglocation.iddefaults to all locations. Update your integrations to explicitly passlocation.idto avoid breakage when this change is enforced.
Note: If you receive a
403 Forbiddenresponse from this endpoint, please contact Public API support.
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==ALLFetch for a specific provider:
GET /api/v1/locationproductionnetschedule?filter=fromDate==2025-01-14,range==7,provider.id==789Fetch for a specific patient:
GET /api/v1/locationproductionnetschedule?filter=fromDate==2025-01-14,patient.id==456Fetch for a specific appointment:
GET /api/v1/locationproductionnetschedule?filter=fromDate==2025-01-14,appointment.id==345With 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,scheduledAmountA 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 |
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) |
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" |
HTTP Status Code Errors — click to expand
These apply to all LocationProductionNetSchedule V1 endpoints.
The request query parameters are invalid or cannot be processed. See the Field-Level Validation Errors section below for specific causes.
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
Field-Level Validation Errors — click to collapse
These errors are returned in the errors array of the response body alongside a 400 status code.
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. |
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. |
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. |
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. |
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. |