PBJ Staffing Data Pre-Submission QA API Reference

Beta. Structural checks of a nursing home's quarterly PBJ staffing XML file against the CMS PBJ data specifications v4.10.0, internal consistency checks, and flags for documented audit and rating risks. Product page and free test form.

Endpoint

Request

Send the file itself as the request body, up to 4.4 MB (HTTP 413 above that). Staffing XML compresses very well, so send the ZIP or a gzip for a large facility. Each XML file in a ZIP may be up to 50 MB uncompressed, the CMS limit, and a ZIP may hold up to 20 XML files; they are checked together and billed as one report.

Rejected with HTTP 400 and not charged: an empty body, a PDF, a file that is not well-formed XML, DOCTYPE or entity declarations, a root that is not nursingHomeData, an Employee Link (administration) file, a ZIP with no XML file or more than 20, a corrupt or encrypted ZIP, an invalid asOf. A PBJ file with problems is not an input error: it gets a completed FAIL report, and that run is charged.

Report

Rule IDs

CMS edits keep their CMS number, so a finding can be matched to the edit the CMS system would report. Fatal CMS edits are errors; CMS warnings, risk flags and consistency checks are warnings.

Source keys, as returned in every report:

• CMS Staffing Data Submission (PBJ) page: data specifications v4.10.0, Policy Manual v2.8 and FAQ
• CMS PBJ audit selection criteria, as reported by Skilled Nursing News (November 2018)
• CMS Nursing Home Five-Star Quality Rating System: Technical Users' Guide (September 2026) and cut point tables
• HHS OIG report A-09-24-02005 on RN hours reported in PBJ (June 2026)

Not checked

• Whether facilityId and employee IDs match what CMS has on file (CMS edits -3693 and -4016 need the PBJ system).
• Whether hours match payroll, invoices or contracts, which is what PBJ audits verify.
• Whether hours were worked onsite, and whether meal breaks were actually deducted (the file has no shift times).
• The CMS staffing rating itself. With a census you send, the report estimates hours per resident day and a star range; CMS uses its own MDS census, case mix and six quarters of turnover data.
• PBJ Administration Submission files (Employee Link).
• ZIP and XML file naming rules, and the 5 MB limit CMS applies to the upload ZIP.

Example responses

A paid check of the synthetic PBJ sample with asOf=2026-10-03 (report shortened to its summary fields), and the findings from a demo check of the sample with planted problems. Both generated by running the real endpoint code.

{
  "requestId": "7f3c2a1e-5b8d-4c6f-9e0a-1d2b3c4d5e6f",
  "api": "pbj-staffing-qa",
  "mode": "paid",
  "charged": true,
  "priceCents": 2500,
  "balanceCents": 7500,
  "report": {
    "schemaVersion": 1,
    "status": "PASS",
    "specVersion": "4.10.0",
    "fileSpecVersion": "4.10.0",
    "reportingQuarter": {
      "federalFiscalYear": 2026,
      "quarter": 4,
      "start": "2026-07-01",
      "end": "2026-09-30"
    },
    "processType": "merge",
    "counts": {
      "employees": 14,
      "staffHoursRecords": 14,
      "workDays": 789,
      "hourEntries": 789,
      "totalHours": 6917.5
    },
    "coverage": {
      "daysWithHours": 92,
      "daysWithRnHours": 92,
      "daysWithoutRnHours": 0
    },
    "findingCount": 0,
    "findingCounts": {
      "error": 0,
      "warning": 0
    },
    "ruleCounts": {},
    "findingsTruncated": false,
    "scope": "Structural checks against the CMS PBJ data specifications and documented risk patterns. A PASS does not mean CMS will accept the file or that it will survive a CMS audit, and this is not legal or compliance advice.",
    "submissionDeadline": {
      "date": "2026-11-14",
      "time": "11:59 PM Eastern Time",
      "asOf": "2026-10-03",
      "daysRemaining": 42,
      "passed": false,
      "note": "CMS accepts no submissions after the deadline."
    },
    "input": {
      "container": "xml",
      "xmlFiles": 1,
      "xmlBytes": 233073
    },
    "inputSha256": "a1da2506994af98f782f9ecc409b18a4dbdca9f7d7e3ba1e33b9668bab76873a",
    "asOf": "2026-10-03"
  }
}

[
  {
    "severity": "error",
    "ruleId": "CMS-1021",
    "path": "/nursingHomeData/header/@fileSpecVersion",
    "message": "This fileSpecVersion was retired on April 1, 2026. Files must use 4.10.0.",
    "source": "spec"
  },
  {
    "severity": "error",
    "ruleId": "CMS-3676",
    "path": "/nursingHomeData/staffingHours/staffHours[8]/workDays/workDay[67]/hourEntries/hourEntry/jobTitleCode",
    "message": "jobTitleCode must be one of the CMS job title codes 1 to 40.",
    "source": "spec"
  },
  {
    "severity": "error",
    "ruleId": "CMS-3676",
    "path": "/nursingHomeData/staffingHours/staffHours[9]/workDays/workDay[66]/hourEntries/hourEntry/payTypeCode",
    "message": "payTypeCode must be 1 (exempt), 2 (non-exempt) or 3 (contract).",
    "source": "spec"
  },
  {
    "severity": "error",
    "ruleId": "CMS-3677",
    "path": "/nursingHomeData/employees/employee[14]/hireDate",
    "message": "hireDate is empty. Remove the tag when there is no date.",
    "source": "spec"
  }
]

Errors

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

{
  "error": {
    "code": "input_error",
    "message": "The file is not well-formed XML (no element found: line 1, column 71).",
    "requestId": "7f3c2a1e-5b8d-4c6f-9e0a-1d2b3c4d5e6f",
    "charged": false
  }
}

Code samples

# The ZIP you upload to CMS (or the XML file), checked as of the planned upload date
curl -X POST "https://www.spreadrun.com/api/v1/pbj-staffing-qa?asOf=2026-11-10" \
  -H "Authorization: Bearer $SPREADRUN_API_KEY" \
  -H "Content-Type: application/zip" \
  --data-binary @pbj_2026_q4.zip