A financial assistance file for hospital websites
A small JSON file a hospital posts on its own site. It states who gets free or discounted care, how to apply and where the full policy lives. Patients' AI assistants can read it directly.
This is a new format proposed by HospitalAid, version 0.1. It is not an adopted industry standard. Anyone can use it for free, and we welcome comments from hospitals and developers at [email protected].
Why post it
- Many policies are long PDFs. People and programs both find it hard to pull the income levels out of them.
- A file you write yourself is the most direct source there is. Assistants and sites like ours can quote your own numbers with your own date.
- Nonprofit hospitals already post the policy, a plain language summary and an application under IRS rule 501(r). This file points to those three and adds the key numbers.
Where it goes
Post the file at this address on your hospital's website.
https://<your-hospital-site>/.well-known/financial-assistance.json
The /.well-known/ folder is a common place for files that programs look for (RFC 8615). Names in that folder are meant to be registered with IANA. This name is not registered, so treat it as a proposed location for now. A health system can post one file per hospital site, or one file that lists every CCN the policy covers.
The fields
Only 5 fields are required (schema_version, hospital_name, ccns, policy_url, last_reviewed). Leave out any other field you do not know, or set it to null. Do not guess. Your written policy at policy_url is the final word.
| Field | Type | Required | Meaning |
|---|---|---|---|
schema_version | text | Yes | Version of this format. Use "0.1". |
hospital_name | text | Yes | The hospital name patients know. |
ccns | list of text | Yes | CMS Certification Numbers (six characters) of every hospital this policy covers. |
policy_name | text | No | Title of the written policy. |
effective_date | date | No | Date the current policy took effect (YYYY-MM-DD). |
last_reviewed | date | Yes | Date the hospital last checked this file against its written policy (YYYY-MM-DD). |
free_care_fpl_pct | number | No | Care is free when household income is at or below this percent of the federal poverty level. null if the policy has no free care level. |
discount_care_fpl_pct | number | No | Some discount is given when household income is at or below this percent of the federal poverty level. null if there is no income-based discount. |
discount_tiers | list of steps | No | Discount steps between the free care level and the discount level. |
covers_insured_patients | true or false | No | true if insured patients can get help with deductibles, copays or coinsurance. |
asset_test | true or false | No | true if the policy counts savings or property as well as income. |
residency_requirement | text | No | Who must live where to apply, in plain words. null if there is no residency rule. |
catastrophic_provision | text | No | Help for very large bills relative to income, in plain words. null if none. |
application_deadline_days | whole number | No | Days a patient has to apply, counted as the policy says. null if the policy sets no deadline. |
documents_required | list of text | No | Documents a patient sends with the application. |
languages | list of text | No | Languages the policy and application are offered in. |
policy_url | link | Yes | Link to the full written policy. |
application_url | link | No | Link to the application form. |
plain_language_summary_url | link | No | Link to the plain language summary. |
financial_counseling_phone | text | No | Phone number for financial counseling or billing help. |
financial_counseling_email | No | Email for financial counseling or billing help. | |
notes | text | No | Anything a patient should know that has no field. |
Each step in discount_tiers has these fields.
| Field | Meaning |
|---|---|
fpl_min | Lowest income in this step, as a percent of the poverty level. |
fpl_max | Highest income in this step. null if there is no upper limit. |
patient_pays | What the patient pays in this step, in plain words. |
Income levels are a percent of the federal poverty level, so a policy at 200% writes 200. The full rules are in the JSON Schema (draft 2020-12), at https://hospitalaid.org/standard/financial-assistance.schema.json.
An example
Example Community Hospital is made up. So are its CCN, phone number and links. You can download the example file and change it.
{
"schema_version": "0.1",
"hospital_name": "Example Community Hospital",
"ccns": [
"999999"
],
"policy_name": "Financial Assistance Policy",
"effective_date": "2026-07-01",
"last_reviewed": "2026-11-01",
"free_care_fpl_pct": 200,
"discount_care_fpl_pct": 400,
"discount_tiers": [
{
"fpl_min": 0,
"fpl_max": 200,
"patient_pays": "nothing"
},
{
"fpl_min": 201,
"fpl_max": 300,
"patient_pays": "25% of charges"
},
{
"fpl_min": 301,
"fpl_max": 400,
"patient_pays": "50% of charges"
}
],
"covers_insured_patients": true,
"asset_test": false,
"residency_requirement": null,
"catastrophic_provision": "Bills over 20% of yearly household income are reduced to 20% of income",
"application_deadline_days": 240,
"documents_required": [
"proof of income",
"photo ID"
],
"languages": [
"English",
"Spanish"
],
"policy_url": "https://www.example.org/financial-assistance/policy.pdf",
"application_url": "https://www.example.org/financial-assistance/application.pdf",
"plain_language_summary_url": "https://www.example.org/financial-assistance/summary.pdf",
"financial_counseling_phone": "(555) 555-0142",
"financial_counseling_email": "[email protected]",
"notes": "Payment plans with no interest are available for any bill."
} Publish it in three steps
- Copy the example and fill it in from your current written policy. Set last_reviewed to today.
- Check it with any JSON Schema validator against
https://hospitalaid.org/standard/financial-assistance.schema.json. - Ask your web team to post it at
/.well-known/financial-assistance.jsonon your main site, served as plain JSON. Update it whenever the policy changes.
Tell us when it is live
Email [email protected] with the link to your file. We read it, check it against your written policy and mark your page on HospitalAid verified, with the date and a link to your file as the source. There is no charge, and a hospital cannot pay to change what its page says.
See also how to claim your hospital's page and our open data.