Studies
Upload a fee schedule, find peer hospitals, and run a rate benchmarking study from your assistant.
These tools run the fee schedule benchmark end to end. They write to your account (a rate table, a study), where the other tools only read public data. The assistant is walked through them by study_next_step and by the next_step on every result.
study_next_step
What to call next for a study, or the whole recipe when no study is named.
| Parameter | Type | Default | What it does |
|---|---|---|---|
study_id | string | none | The study id, as returned by the create tool or the list tool of that study kind. |
Returns next_step with the tool to call, the arguments it needs, why, and which steps are done. Every study tool's result carries the same next_step, so this is only needed to start, or to pick a study up again later.
create_upload
A 15-minute link to put one file into your account's storage.
| Parameter | Type | Default | What it does |
|---|---|---|---|
filename | string | required | The name of the file to upload, with its extension (.xlsx, .xls or .csv). |
Returns upload_id (pass it to the next tools), put_url (a write-only link to one blob), curl (the command a local assistant runs) and upload_page (the page a browser-based assistant sends you to). Nothing is read until inspect_upload.
inspect_upload
The sheets, columns and sample rows of an uploaded file, with a proposed column mapping.
| Parameter | Type | Default | What it does |
|---|---|---|---|
upload_id | string | required | The id create_upload returned for the file. |
Each sheet lists columns (col, header, looks_like code / number / text) and five sample rows. suggested_mapping is the mapping save_rate_table takes when the code column was found: the header row, the code column, one rate column per payer named from its header, and the volume column when there is one. It is a proposal; confirm it with the user when a file is unusual.
save_rate_table
Publish the uploaded (or typed-in) rates as a rate-table version for an owner.
| Parameter | Type | Default | What it does |
|---|---|---|---|
label | string | none | A label for this rate-table version, such as the fee schedule year. |
mapping | list of object | none | Which columns hold the code, the rates (one per payer) and the volume, per sheet: the suggested_mapping from inspect_upload, confirmed with the user. |
owner | string | required | The provider the rates belong to: a provider id or name in your account. A new name becomes a custom provider. |
rows | list of object | none | The rates typed in directly: code, payer, rate and optional units per row, instead of a file. |
upload_id | string | none | The id create_upload returned for the file. |
Give upload_id with mapping, or rows (code, payer, rate, optional units, at most 2,000) for a small table. owner is a provider in the account, matched by id or name, created as a custom provider when new. The result names the owner_id to use for the study, the version, the row count and the payers found. At most 50,000 rows.
find_peer_hospitals
Similar hospitals near an anchor hospital, each with the reason it was picked.
| Parameter | Type | Default | What it does |
|---|---|---|---|
hospital_id | string | required | One hospital id (UUID), as returned by find_hospitals. |
n | integer | 10 | How many peer hospitals to pick, at most 20. |
The anchor is a hospital_id from find_hospitals: the client's own hospital when it publishes a price file, else the nearest one like it. The rule prefers the same kind of facility and a bed count within half to double the anchor's, the same metro first, then widens from 25 to 150 miles, and skips hospitals that publish the same price file. n is at most 20. Each row has distance_miles, beds, why and page_url.
create_benchmark_study
A new rate benchmarking study for an owner.
| Parameter | Type | Default | What it does |
|---|---|---|---|
name | string | required | The study name. |
owner | string | required | The provider the rates belong to: a provider id or name in your account. A new name becomes a custom provider. |
The study starts empty. The result is the study summary (study_id, owner, panel size, what is set, app_url) and the next_step.
configure_benchmark_study
Set the study's hospital panel, its volume source and its code selection, in one call or several.
| Parameter | Type | Default | What it does |
|---|---|---|---|
code_method | string | none | How the codes to compare are chosen: top_n, top_pct or manual. |
code_value | number | none | The N for top_n, or the percent of revenue for top_pct. |
codes | list of string | none | CPT, HCPCS or MS-DRG codes to look up. |
hospital_ids | list of string | none | Up to 25 hospital ids (UUIDs), as returned in the hospital_id field of earlier rows. |
state | string | none | Two-letter US state, for example FL. A state on its own is not enough: add codes, apc, q or hospital_ids. |
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
units_by_code | object | none | Annual units per code, when utilization_source is uploaded. |
utilization_source | string | none | Where annual volumes come from: cms_state, rate_table or uploaded. |
hospital_ids are 1 to 20 directory hospitals (from find_peer_hospitals or find_hospitals). utilization_source is cms_state (CMS state-average volumes for state, defaulting to the panel's state), rate_table (the table's own volume column) or uploaded (units_by_code). code_method is top_n (default 20 codes by estimated revenue), top_pct (the codes covering code_value percent of revenue, default 80) or manual with codes.
run_benchmark
Compute the comparison and save it on the study.
| Parameter | Type | Default | What it does |
|---|---|---|---|
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
Returns summary (total annual impact, codes compared, codes below the benchmark, codes below Medicare, when it was computed) and the top 20 rows by impact. Each row: code, description, your_rate, benchmark_avg, benchmark_median, benchmark_min, benchmark_max, delta_pct, units, impact, medicare, medicare_delta_pct. A free account gets the summary and 5 rows.
get_benchmark_results
Page through a run study's rows.
| Parameter | Type | Default | What it does |
|---|---|---|---|
limit | integer | 50 | Most rows to return. Each tool has its own cap. On a free plan, paid data returns 8 rows whatever you ask for. |
offset | integer | 0 | Rows to skip, for paging. |
sort | string | impact | Column to sort by. |
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
sort is impact (default, biggest first), delta_pct (most below the benchmark first) or code. limit is at most 200. A free account gets the first 5 rows.
export_benchmark
A short download link to the study as a file.
| Parameter | Type | Default | What it does |
|---|---|---|---|
format | string | xlsx | Benchmark: xlsx, csv, sources or pdf. Strategic pricing: pdf, xlsx, proposal-csv, benchmarks-csv or mdc-crosswalk-csv. |
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
format is xlsx (the workbook: Comparison, Sources and Utilization sheets), csv, sources (one row per panel hospital with its transparency page and price-file links) or pdf (the report). The result has a short /d/... url and the filename; the PDF uses your firm's branding. Needs the Rate Benchmarking service on the account. The result's say reminds the assistant to save beside the original file, never over it.
list_benchmark_studies
The account's rate benchmarking studies, newest first.
| Parameter | Type | Default | What it does |
|---|
Each row: study_id, name, owner_label, hospitals, has_results, total_impact and app_url.
Components
One tool per part of the study page and its PDF; see Every component, one tool each. On a free account the figures return 5 rows with the dollar and delta figures hidden.
rb_sections
Every component of a study, one tool each, in reading order.
| Parameter | Type | Default | What it does |
|---|---|---|---|
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
Each row has tool, shows (where the app or PDF draws it) and summary. Call a row's tool with the study_id. A setup call: it does not count toward the daily limit.
rb_panel
The saved hospital panel with its source links.
| Parameter | Type | Default | What it does |
|---|---|---|---|
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
Per hospital: city, ZIP, beds, published rows, transparency page, price file and how the file was read.
rb_hospital_mapping
A hospital's AI column mapping.
| Parameter | Type | Default | What it does |
|---|---|---|---|
hospital_id | string | required | One hospital id (UUID), as returned by find_hospitals. |
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
For a hospital whose price file the AI mapper read: which file column became which field, per sheet. Free in full.
rb_code_preview
Setup step 2: the rate table, CMS coverage and the codes the selection picks.
| Parameter | Type | Default | What it does |
|---|---|---|---|
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
A setup call: it does not count toward the daily limit.
rb_summary
The results header: total impact, code counts, panel size and the code-selection recap.
| Parameter | Type | Default | What it does |
|---|---|---|---|
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
rb_provenance
The status pills: when it was computed and where each input came from.
| Parameter | Type | Default | What it does |
|---|---|---|---|
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
Free in full.
rb_comparison
The comparison table with the app's filter bar.
| Parameter | Type | Default | What it does |
|---|---|---|---|
below_medicare_only | boolean | false | |
delta_band | below | below15 | above | none | |
descending | boolean | none | |
impact_only | boolean | false | |
limit | integer | 50 | Most rows to return. Each tool has its own cap. On a free plan, paid data returns 8 rows whatever you ask for. |
offset | integer | 0 | Rows to skip, for paging. |
priced_only | boolean | false | Hide lines that have no price. On by default. |
q | string | none | Search the service description, up to 200 characters. |
sort | string | impact | Column to sort by. |
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
q (text), delta_band and the priced_only, impact_only and below_medicare_only toggles narrow the rows; sort, offset and limit page them (limit up to 50). Exports always carry every row.
rb_hospital_rates
The per-hospital columns: each panel hospital's own rate per code.
| Parameter | Type | Default | What it does |
|---|---|---|---|
codes | list of string | none | CPT, HCPCS or MS-DRG codes to look up. |
limit | integer | 50 | Most rows to return. Each tool has its own cap. On a free plan, paid data returns 8 rows whatever you ask for. |
offset | integer | 0 | Rows to skip, for paging. |
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
codes limits it to some codes. Marks which figures are CMS estimated amounts.
rb_report_executive_summary
The PDF's Executive Summary section, as printed.
| Parameter | Type | Default | What it does |
|---|---|---|---|
limit | integer | 50 | Most rows to return. Each tool has its own cap. On a free plan, paid data returns 8 rows whatever you ask for. |
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
rb_report_methodology
The PDF's Scope & Methodology section, as printed.
| Parameter | Type | Default | What it does |
|---|---|---|---|
limit | integer | 50 | Most rows to return. Each tool has its own cap. On a free plan, paid data returns 8 rows whatever you ask for. |
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
rb_report_market_position
The PDF's Market Position vs Benchmark section, as printed.
| Parameter | Type | Default | What it does |
|---|---|---|---|
limit | integer | 50 | Most rows to return. Each tool has its own cap. On a free plan, paid data returns 8 rows whatever you ask for. |
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
rb_report_service_lines
The PDF's Revenue Opportunity by Service Line section, as printed.
| Parameter | Type | Default | What it does |
|---|---|---|---|
limit | integer | 50 | Most rows to return. Each tool has its own cap. On a free plan, paid data returns 8 rows whatever you ask for. |
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
rb_report_code_level
The PDF's Code-Level Analysis section, as printed.
| Parameter | Type | Default | What it does |
|---|---|---|---|
limit | integer | 50 | Most rows to return. Each tool has its own cap. On a free plan, paid data returns 8 rows whatever you ask for. |
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
rb_report_above_market
The PDF's Codes Priced Above Market section, as printed.
| Parameter | Type | Default | What it does |
|---|---|---|---|
limit | integer | 50 | Most rows to return. Each tool has its own cap. On a free plan, paid data returns 8 rows whatever you ask for. |
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
rb_report_opportunity_summary
The PDF's Potential Revenue Opportunity Summary section, as printed.
| Parameter | Type | Default | What it does |
|---|---|---|---|
limit | integer | 50 | Most rows to return. Each tool has its own cap. On a free plan, paid data returns 8 rows whatever you ask for. |
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
rb_report_appendix_codes
The PDF's Appendix A, Code-Level Detail section, as printed.
| Parameter | Type | Default | What it does |
|---|---|---|---|
limit | integer | 50 | Most rows to return. Each tool has its own cap. On a free plan, paid data returns 8 rows whatever you ask for. |
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
rb_report_appendix_panel
The PDF's Appendix B, the hospital panel and source files section, as printed.
| Parameter | Type | Default | What it does |
|---|---|---|---|
limit | integer | 50 | Most rows to return. Each tool has its own cap. On a free plan, paid data returns 8 rows whatever you ask for. |
study_id | string | required | The study id, as returned by the create tool or the list tool of that study kind. |
Example requests
- Benchmark the attached fee schedule for Sunrise Medical Group against hospitals like Tampa General.
- Which of our codes are furthest below the market?
- Give me the Excel workbook for the Sunrise study.
- I updated the rates file; run the study again.