# Public API – Financial Management Operations related to patients, appointments, providers and so on. Version: 185.0.9 ## Servers Sandbox ``` https://test.hs1api.com/ascend-gateway/api ``` Prod ``` https://prod.hs1api.com/ascend-gateway/api ``` ## Security ### bearerAuth Type: http Scheme: bearer Bearer Format: JWT ### oAuthSandbox OAuth 2.0 client credentials (Sandbox) Type: oauth2 ## Download OpenAPI description [Public API – Financial Management](https://papidocs.hs1api.com/_bundle/PublicAPI/api-financial-management.yaml) ## Agingbalances (V1) Agingbalances endpoints ### Returns AgingBalanceV1 for patient. - [GET /v1/agingbalances](https://papidocs.hs1api.com/publicapi/api-financial-management/agingbalances-(v1)/getagingbalancesv1.md) ### Returns AgingBalanceV1 for patient. This endpoint requires either patient.id or page filters be present in the request, see "filter" details below for more info on how to use them properly. - [GET /v1/agingbalances/report](https://papidocs.hs1api.com/publicapi/api-financial-management/agingbalances-(v1)/getagingbalancesreportv1.md): Returns AgingBalanceReportV1: rolled-up bucket totals for the location (or for the requested guarantor patients), plus patientReports with one AgingReceivableV1 per guarantor row. Filter requirement: Provide either filter=patient.id->[...] (with location.id) or filter=page==n (with location.id) for the paginated location report—not both. See the filter parameter for operators and notes on meta.pagination. Note: If responseFields is supplied, it is validated against an internal allowlist but the report JSON is not filtered by those names (the payload shape is always the full AgingBalanceReportV1). Rate limiting: Documented on this operation (not on AgingBalanceReportV1 / AgingReceivableV1 schemas). Subject to standard Public API rate limits; on HTTP 429 use Retry-After and Rate-Limiting-Remaining as documented for the API. Overview: https://portal.hs1api.com/guide MCP (first successful call): use a real location.id from GET /v1/locations, e.g. filter=location.id==12345678901234,page==1 (paginated location report). location.id alone is not sufficient. MCP (when page==1 fails): A 400 validation response whose message is "No more data was found" has been observed when the paginated location report has no guarantor rows to return (for example an empty or sparse dataset). That is distinct from “invalid filter syntax.” In those cases, call again with filter=location.id==…,patient.id->[guarantorPatientId,…] (guarantor patient IDs, up to 50) instead of relying on page alone, or confirm the organization has aging balances for that location. ## PatientStatements (V1) PatientStatements endpoints ### Returns a list of patientStatementsV1 based on filter criteria - [GET /v1/patientstatements](https://papidocs.hs1api.com/publicapi/api-financial-management/patientstatements-(v1)/getpatientstatementsv1.md): Query shape: Prefer a narrow filter—combine scoping filters with lastModified or date bounds where supported. A very wide date range with no other scoping can 408 (timeout) on large tenants; retry with a smaller window or use cursor pagination (lastId with lastModified—see parameter descriptions). Empty results: 200 with data: [] means no patientStatementsV1 matched; it does not indicate invalid filter values. responseFields: Use only names allowed on this operation (see the responseFields parameter). Use ALL or the documented flat field list. Pagination: The page query parameter is deprecated where lastId is supported; lastModified / lastId style pagination is preferred. ### Returns a PatientStatementV1 by PatientStatement ID. - [GET /v1/patientstatements/{patientstatementId}](https://papidocs.hs1api.com/publicapi/api-financial-management/patientstatements-(v1)/getpatientstatementsbypatientstatementidv1.md): Returns the PatientStatementV1 identified by the path parameter. 404 when the resource is missing or not accessible in the organization context. ## PatientPaymentPlans (V1) PatientPaymentPlans endpoints ### Returns a list of payment plans entries based on filter criteria - [GET /v1/patientpaymentplans](https://papidocs.hs1api.com/publicapi/api-financial-management/patientpaymentplans-(v1)/getpatientpaymentplansv1.md): Query shape: Prefer a narrow filter—combine scoping filters with lastModified or date bounds where supported. A very wide date range with no other scoping can 408 (timeout) on large tenants; retry with a smaller window or use cursor pagination (lastId with lastModified—see parameter descriptions). Empty results: 200 with data: [] means no payment plans entries matched; it does not indicate invalid filter values. responseFields: Use only names allowed on this operation (see the responseFields parameter). Use ALL or the documented flat field list. Pagination: The page query parameter is deprecated where lastId is supported; lastModified / lastId style pagination is preferred. ### Returns a payment plan by ID. - [GET /v1/patientpaymentplans/{patientPaymentPlanId}](https://papidocs.hs1api.com/publicapi/api-financial-management/patientpaymentplans-(v1)/getpatientpaymentplansbypatientpaymentplanidv1.md): Returns the payment plan identified by the path parameter. 404 when the resource is missing or not accessible in the organization context. ## FeeSchedules (V1) FeeSchedules endpoints ### Returns a list of FeeSchedules based on filter criteria - [GET /v1/feeschedules](https://papidocs.hs1api.com/publicapi/api-financial-management/feeschedules-(v1)/getfeeschedulesv1.md): Query shape: Prefer a narrow filter—combine scoping filters with lastModified or date bounds where supported. A very wide date range with no other scoping can 408 (timeout) on large tenants; retry with a smaller window or use cursor pagination (lastId with lastModified—see parameter descriptions). Empty results: 200 with data: [] means no FeeSchedules matched; it does not indicate invalid filter values. responseFields: Use only names allowed on this operation (see the responseFields parameter). Use ALL or the documented flat field list. Pagination: The page query parameter is deprecated where lastId is supported; lastModified / lastId style pagination is preferred. ### Returns created FeeSchedule - [POST /v1/feeschedules](https://papidocs.hs1api.com/publicapi/api-financial-management/feeschedules-(v1)/postfeeschedulesv1.md): Creates a resource from the request body. Validation errors return 400; a successful create returns 201 with the created resource in data. ### Returns FeeSchedule by ID. - [GET /v1/feeschedules/{feeScheduleId}](https://papidocs.hs1api.com/publicapi/api-financial-management/feeschedules-(v1)/getfeeschedulesbyfeescheduleidv1.md): Returns the FeeSchedule identified by the path parameter. 404 when the resource is missing or not accessible in the organization context. ### Returns updated FeeSchedule - [PUT /v1/feeschedules/{feeScheduleId}](https://papidocs.hs1api.com/publicapi/api-financial-management/feeschedules-(v1)/putfeeschedulesbyfeescheduleidv1.md): Updates the resource identified by the path parameter. Validation errors return 400; 404 when the resource is missing. ### Delete specific FeeSchedule by ID - [DELETE /v1/feeschedules/{feeScheduleId}](https://papidocs.hs1api.com/publicapi/api-financial-management/feeschedules-(v1)/deletefeeschedulesbyfeescheduleidv1.md): Deletes the resource identified by the path parameter. 404 when the resource is missing or already deleted. ## FeeScheduleAssociations (V1) FeeScheduleAssociations endpoints ### Returns FeeScheduleAssociations based on id of FeeSchedule - [GET /v1/feescheduleassociations](https://papidocs.hs1api.com/publicapi/api-financial-management/feescheduleassociations-(v1)/getfeescheduleassociationsv1.md): Query shape: Use the documented query parameters to scope the request. Unscoped queries can 408 (timeout) on large tenants. Empty results: 200 with data: [] means no resources matched; it does not indicate invalid filter values. ## FeeScheduleRanges (V1) FeeScheduleRanges endpoints ### Returns a list of FeeScheduleRanges based on filter criteria - [GET /v1/feescheduleranges](https://papidocs.hs1api.com/publicapi/api-financial-management/feescheduleranges-(v1)/getfeeschedulerangesv1.md): Query shape: Prefer a narrow filter—combine scoping filters with lastModified or date bounds where supported. A very wide date range with no other scoping can 408 (timeout) on large tenants; retry with a smaller window or use cursor pagination (lastId with lastModified—see parameter descriptions). Empty results: 200 with data: [] means no FeeScheduleRanges matched; it does not indicate invalid filter values. responseFields: Use only names allowed on this operation (see the responseFields parameter). Use ALL or the documented flat field list. Pagination: The page query parameter is deprecated where lastId is supported; lastModified / lastId style pagination is preferred. ### Returns created FeeScheduleRange - [POST /v1/feescheduleranges](https://papidocs.hs1api.com/publicapi/api-financial-management/feescheduleranges-(v1)/postfeeschedulerangesv1.md): Creates a resource from the request body. Validation errors return 400; a successful create returns 201 with the created resource in data. ### Returns FeeScheduleRange by ID. - [GET /v1/feescheduleranges/{feeScheduleRangeId}](https://papidocs.hs1api.com/publicapi/api-financial-management/feescheduleranges-(v1)/getfeeschedulerangesbyfeeschedulerangeidv1.md): Returns the FeeScheduleRange identified by the path parameter. 404 when the resource is missing or not accessible in the organization context. ### Returns updated FeeScheduleRange - [PUT /v1/feescheduleranges/{feeScheduleRangeId}](https://papidocs.hs1api.com/publicapi/api-financial-management/feescheduleranges-(v1)/putfeeschedulerangesbyfeeschedulerangeidv1.md): Updates the resource identified by the path parameter. Validation errors return 400; 404 when the resource is missing. ### Delete specific FeeScheduleRange by ID - [DELETE /v1/feescheduleranges/{feeScheduleRangeId}](https://papidocs.hs1api.com/publicapi/api-financial-management/feescheduleranges-(v1)/deletefeeschedulerangesbyfeeschedulerangeidv1.md): Deletes the resource identified by the path parameter. 404 when the resource is missing or already deleted. ## Adjustment Transactions (V1) Adjustment Transactions endpoints ### Returns a list of adjustment transaction entries based on filter criteria - [GET /v1/transactions/adjustments](https://papidocs.hs1api.com/publicapi/api-financial-management/adjustment-transactions-(v1)/gettransactionsadjustmentsv1.md): Query shape: Prefer a narrow filter—combine scoping filters with lastModified or date bounds where supported. A very wide date range with no other scoping can 408 (timeout) on large tenants; retry with a smaller window or use cursor pagination (lastId with lastModified—see parameter descriptions). Empty results: 200 with data: [] means no adjustment transaction entries matched; it does not indicate invalid filter values. responseFields: Use only names allowed on this operation (see the responseFields parameter). Use ALL or the documented flat field list. Pagination: The page query parameter is deprecated where lastId is supported; lastModified / lastId style pagination is preferred. ### Returns an adjustment transaction entry by entry ID. - [GET /v1/transactions/adjustments/{transactionId}](https://papidocs.hs1api.com/publicapi/api-financial-management/adjustment-transactions-(v1)/gettransactionsadjustmentsbytransactionidv1.md): Returns the adjustment transaction entry identified by the path parameter. 404 when the resource is missing or not accessible in the organization context. ## Patient Payment Transactions (V1) Patient Payment Transactions endpoints ### Returns a list of patient payment transaction entries based on filter criteria - [GET /v1/transactions/patientpayments](https://papidocs.hs1api.com/publicapi/api-financial-management/patient-payment-transactions-(v1)/gettransactionspatientpaymentsv1.md): Query shape: Prefer a narrow filter—combine scoping filters with lastModified or date bounds where supported. A very wide date range with no other scoping can 408 (timeout) on large tenants; retry with a smaller window or use cursor pagination (lastId with lastModified—see parameter descriptions). Empty results: 200 with data: [] means no patient payment transaction entries matched; it does not indicate invalid filter values. responseFields: Use only names allowed on this operation (see the responseFields parameter). Use ALL or the documented flat field list. Pagination: The page query parameter is deprecated where lastId is supported; lastModified / lastId style pagination is preferred. ### Returns a patient payment transaction entry by entry ID. - [GET /v1/transactions/patientpayments/{transactionId}](https://papidocs.hs1api.com/publicapi/api-financial-management/patient-payment-transactions-(v1)/gettransactionspatientpaymentsbytransactionidv1.md): Returns the patient payment transaction entry identified by the path parameter. 404 when the resource is missing or not accessible in the organization context. ## Patient Procedure Transactions (V1) Patient Procedure Transactions endpoints ### Returns a list of patient procedure transaction entries based on filter criteria - [GET /v1/transactions/procedures](https://papidocs.hs1api.com/publicapi/api-financial-management/patient-procedure-transactions-(v1)/gettransactionsproceduresv1.md): Query shape: Prefer a narrow filter—combine scoping filters with lastModified or date bounds where supported. A very wide date range with no other scoping can 408 (timeout) on large tenants; retry with a smaller window or use cursor pagination (lastId with lastModified—see parameter descriptions). Empty results: 200 with data: [] means no patient procedure transaction entries matched; it does not indicate invalid filter values. responseFields: Use only names allowed on this operation (see the responseFields parameter). Use ALL or the documented flat field list. Pagination: The page query parameter is deprecated where lastId is supported; lastModified / lastId style pagination is preferred. ### Returns a patient procedure transaction entry by entry ID. - [GET /v1/transactions/procedures/{transactionId}](https://papidocs.hs1api.com/publicapi/api-financial-management/patient-procedure-transactions-(v1)/gettransactionsproceduresbytransactionidv1.md): Returns the patient procedure transaction entry identified by the path parameter. 404 when the resource is missing or not accessible in the organization context. ## Insurance Payment Transactions (V1) Insurance Payment Transactions endpoints ### Returns a list of insurance payment transaction entries based on filter criteria - [GET /v1/transactions/insurancepayments](https://papidocs.hs1api.com/publicapi/api-financial-management/insurance-payment-transactions-(v1)/gettransactionsinsurancepaymentsv1.md): Query shape: Prefer a narrow filter—combine scoping filters with lastModified or date bounds where supported. A very wide date range with no other scoping can 408 (timeout) on large tenants; retry with a smaller window or use cursor pagination (lastId with lastModified—see parameter descriptions). Empty results: 200 with data: [] means no insurance payment transaction entries matched; it does not indicate invalid filter values. responseFields: Use only names allowed on this operation (see the responseFields parameter). Use ALL or the documented flat field list. Pagination: The page query parameter is deprecated where lastId is supported; lastModified / lastId style pagination is preferred. ### Returns a insurance payment transaction entry by entry ID. - [GET /v1/transactions/insurancepayments/{transactionId}](https://papidocs.hs1api.com/publicapi/api-financial-management/insurance-payment-transactions-(v1)/gettransactionsinsurancepaymentsbytransactionidv1.md): Returns the insurance payment transaction entry identified by the path parameter. 404 when the resource is missing or not accessible in the organization context.