Hospital MRF Validator API

Beta. Structural preflight of a hospital price file against the CMS v3.0.0 schema and CSV templates. Product page and free test form.

Endpoint

Paid	`POST https://www.spreadrun.com/api/v1/hospital-mrf-validator`, API key required, $0.25 per completed validation
Demo	`POST https://www.spreadrun.com/api/demo/hospital-mrf-validator`, no key, 2 MB, 100 records, 10 runs per day
Body	The raw file bytes. Any Content-Type; the format is detected from the content.

Request

Send the file itself as the request body: CMS v3.0.0 JSON, tall CSV or wide CSV, in UTF-8, optionally gzip-compressed. There is no URL mode in this version.

Query parameter	Default	Meaning
`mode`	`sample`	`sample` checks metadata, structure and records. `preflight` checks metadata and structure only. Records are not read, so a file that has records gets a SAMPLE_LIMIT warning.
`maxRecords`	`100`	Standard-charge records to inspect, 1 to 1000. Same price at any value.
`filename`	none	Optional. Used only to report whether the name follows the CMS naming pattern (`source.cmsFilenamePattern`).

Rejected with HTTP 400 and not charged: an empty body, a corrupt or incomplete gzip upload, or invalid parameters. Over 4.4 MB: HTTP 413. A file that is not a valid price file (a PDF, HTML, broken JSON) is not an input error: it gets a completed FAIL report with UNSUPPORTED_FORMAT or PARSER_ERROR, and that run is charged.

What gets inspected

Up to 4.4 MB of upload, expanded to at most 16 MB if gzip. Within that, the validator reads metadata and template structure, then the first maxRecords standard-charge records. Real hospital files are often far larger, so most reports on full-size files cover a sample: file.recordsInspected and file.truncatedByLimit say exactly what was read, and a SAMPLE_LIMIT warning turns a clean result into WARN rather than PASS. For full-file validation use CMS's free Hospital Price Transparency Validator.

Report

Field	Meaning
`status`	`FAIL` if any error, `WARN` if only warnings (for example a sample limit), otherwise `PASS`.
`validationMode`	`sample` or `preflight`.
`source`	Upload facts: `format` (json or csv), `encoding`, `compressed`, `cmsFilenamePattern`.
`file`	`bytesRead`, `decompressedBytes`, `recordsInspected`, `truncatedByLimit`, `sha256` of the upload.
`checks`	`parseable`, `requiredMetadataPresent`, `requiredStructurePresent` (true, false or null when undetermined). `reachable` is null for uploads.
`coverage`	Records inspected and the share that have a description, code information and standard charges.
`issues`	Up to 100 findings with `severity` (ERROR or WARNING), `code`, `location` and `message`. Values from your file are never echoed.
`issueCounts`, `issuesOmitted`	Totals per severity, and findings beyond the 100 listed.
`summary.safeForDownstreamIngestion`	true for PASS, false for FAIL, null for WARN.
`limitations`	What the validator does not determine.

Finding codes

Schema findings are named SCHEMA_ plus the JSON Schema rule that failed.

Code	Meaning
`SCHEMA_REQUIRED`	A field the CMS v3.0.0 schema requires is missing (for example count, median_amount or methodology).
`SCHEMA_TYPE`	A value has the wrong type for the CMS schema (for example text where a number belongs).
`SCHEMA_ENUM`	A value is not in the list CMS allows (for example a billing code type or methodology).
`SCHEMA_FORMAT`	A value is not in the required format (for example last_updated_on is not a valid date).
`SCHEMA_EXCLUSIVEMINIMUM`	A charge or amount is zero or negative.
`SCHEMA_MINLENGTH`	A required text field is empty.
`SCHEMA_MINITEMS`	A required list is empty (for example type_2_npi).
`SCHEMA_PATTERN`	A value does not match the CMS pattern (for example the count of allowed amounts).
`SCHEMA_ANYOF`	None of the accepted alternatives is present (for example no dollar, percentage or algorithm charge).
`SCHEMA_CONST`	A value must match a fixed CMS text exactly (for example the attestation statement).
`SCHEMA_ADDITIONALPROPERTIES`	A field that the CMS schema does not define.
`VERSION`	The file declares a version other than CMS 3.0.0.
`MISSING_HEADER`	A column required by the CMS tall or wide CSV template is missing.
`DUPLICATE_HEADER`	The same CSV column appears twice.
`HEADER_PLACEHOLDER`	A CSV header still contains a template placeholder such as [payer_name].
`ROW_WIDTH`	A CSV row has a different number of cells than its header.
`DUPLICATE_KEY`	The same key appears twice in one JSON object.
`INVALID_NUMBER`	A numeric field is malformed, not finite, or not positive.
`EMPTY_FILE`	No standard-charge records were found.
`PARSER_ERROR`	The file could not be parsed as JSON or CSV.
`UNSUPPORTED_FORMAT`	Not a JSON or CSV price file in UTF-8 (for example a PDF, ZIP or HTML page).
`METADATA_UNSEEN`	Warning: required metadata was not reached inside the inspected part of the file.
`SAMPLE_LIMIT`	Warning: only part of the file was inspected; the rest is not validated.
`CHECK_LIMIT`	Warning: the file hit a complexity limit, so inspection stopped early.

Example response

A paid validation of the synthetic tall CSV sample with maxRecords=500. Generated by running the real endpoint code.

{
  "requestId": "7f3c2a1e-5b8d-4c6f-9e0a-1d2b3c4d5e6f",
  "api": "hospital-mrf-validator",
  "mode": "paid",
  "charged": true,
  "priceCents": 25,
  "balanceCents": 925,
  "report": {
    "schemaVersion": 1,
    "status": "PASS",
    "validationMode": "sample",
    "source": {
      "url": "upload",
      "finalUrl": null,
      "filename": "[upload]",
      "cmsFilenamePattern": null,
      "httpStatus": null,
      "contentType": null,
      "contentLength": 1659,
      "redirects": [],
      "compressed": false,
      "format": "csv",
      "encoding": "UTF-8"
    },
    "cmsProfile": {
      "requirementVersion": "3.0.0",
      "source": "CMS",
      "fullComplianceCertification": false
    },
    "file": {
      "bytesRead": 1659,
      "decompressedBytes": 1659,
      "truncatedByLimit": false,
      "sha256": "2e3e366444f5c172e042d73f539f5386faa64139b7475c064ac873e7d97a97e2",
      "hashScope": "full-upload",
      "recordsInspected": 1
    },
    "checks": {
      "reachable": null,
      "parseable": true,
      "requiredMetadataPresent": true,
      "requiredStructurePresent": true
    },
    "coverage": {
      "recordCount": 1,
      "requiredRecordFieldPresence": {
        "description": 1,
        "code_information": 1,
        "standard_charges": 1
      }
    },
    "issueCounts": {},
    "issues": [],
    "issuesOmitted": 0,
    "summary": {
      "safeForDownstreamIngestion": true,
      "notes": [
        "PASS applies only to the inspected structural profile. WARN requires review; uninspected content is unknown."
      ]
    },
    "limitations": [
      "Structural preflight only; not CMS certification, legal advice, pricing accuracy or completeness verification.",
      "Uninspected records and trailing syntax are not validated. No NPI registry, source-authenticity or annual freshness verification.",
      "Duplicate keys checked within parsed scope; duplicate business records and cross-record pricing relationships are not checked.",
      "Only CMS v3.0.0 JSON and comma-separated tall/wide CSV; UTF-8 only. ZIP and concatenated gzip unsupported."
    ]
  }
}

Errors

See the shared error table. Example input error (HTTP 400, not charged):

{
  "error": {
    "code": "input_error",
    "message": "maxRecords must be an integer from 1 to 1000.",
    "requestId": "7f3c2a1e-5b8d-4c6f-9e0a-1d2b3c4d5e6f",
    "charged": false
  }
}

Code samples

# JSON file
curl -X POST "https://www.spreadrun.com/api/v1/hospital-mrf-validator?maxRecords=500" \
  -H "Authorization: Bearer $SPREADRUN_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @standardcharges.json

# Gzip upload, metadata and headers only
curl -X POST "https://www.spreadrun.com/api/v1/hospital-mrf-validator?mode=preflight" \
  -H "Authorization: Bearer $SPREADRUN_API_KEY" \
  --data-binary @standardcharges.csv.gz