PBJ Staffing Data Pre-Submission QA
A bad PBJ quarter costs a nursing home a star. Check the staffing file before it goes to CMS and see what CMS will see: every problem with a rule ID and a plain explanation, an estimate of your staffing star rating, and the days left to the deadline.
What a bad quarter costs
- No accepted file by the deadline: a one-star staffing rating for the quarter. CMS accepts nothing after the deadline, and there are no exceptions.
- Four or more days with no RN hours while residents were in the building: a one-star staffing rating for the quarter.
- A failed or unanswered PBJ audit: a one-star staffing rating for three months. Grouping several agency staff under one ID fails an audit with no reconsideration.
- And a one-star staffing rating takes a full star off the overall Care Compare rating.
Sources: CMS Five-Star Technical Users' Guide (September 2026) and the CMS PBJ Policy Manual and FAQ, linked at the bottom of this page.
Where this fits. Uploading to CMS is free, and you still have to do it: CMS runs its own edits and posts a Final File Validation Report in iQIES, which the PBJ Policy Manual says can take up to 24 hours to arrive. SpreadRun works above that layer, before you upload. It explains every problem with a rule ID, a location and the CMS document it comes from. It shows what CMS sees: the RN coverage gaps and audit patterns CMS has named, and, if you add your resident days, an estimate of the staffing star rating with the published CMS method. It keeps the deadline in front of you. And each report carries the date and a SHA-256 fingerprint of the exact file checked, so you can keep a record of what was checked before submission. No software to install, no contract, and the test below needs no account.
A PASS does not mean the filing will survive a CMS audit. These are structural checks, not legal or compliance advice. A PASS does not mean CMS will accept the file either: CMS also checks your facility ID and employee IDs against its own records. PBJ audits compare reported hours with payroll, invoices and contracts, which this validator never sees.
Personal data. PBJ files identify staff by employee ID and contain hire and termination dates and hours worked. Under the Terms, files sent to this validator may contain that data: it is processed in memory only to produce the report and is not stored, and no value from your file is repeated in the report. You confirm you are permitted to share the file with SpreadRun as a service provider. Employee IDs should never be Social Security Numbers; CMS says so too, and the validator flags IDs that look like one. The sample files on this page are invented.
What it checks
1. CMS data specifications (v4.10.0)
- Structure. The nursingHomeData root, header, employees and staffingHours sections in the order and with the elements the CMS v4.10.0 XSD defines, and every required element present.
- Header. fileSpecVersion 4.10.0 (older versions have been rejected since April 1, 2026), state code, report quarter 1 to 4, federal fiscal year, text lengths and allowed characters.
- Allowed values. Job title codes 1 to 40, pay type codes 1 to 3, processType merge or replace, employee ID characters.
- Dates and hours. Valid YYYY-MM-DD dates, no work dates in the future, hours from 0 to 22.5 with at most two decimals, and no more than 22.5 hours for one employee on one date across all job titles.
Every CMS edit is reported with its CMS edit number, as CMS- and the number, at the severity CMS gives it: Fatal edits are errors and make the report FAIL.
2. Audit and rating risk flags
- Over 400 hours in a month for one employee ID. A CMS audit selection criterion. Often a sign of several agency staff grouped under one ID, which the PBJ FAQ says fails an audit with no reconsideration.
- Four or more days with no RN hours. Under the Five-Star Technical Users' Guide, that brings a one-star staffing rating when residents were present.
- Employee IDs shaped like a Social Security Number. The Policy Manual says IDs must not contain one.
- A replace upload with no hours. It deletes everything already submitted for the quarter.
Risk flags are warnings, never errors, and each one names its source. No flag is used unless CMS or the OIG published it.
3. Internal consistency
- Dates inside the quarter. Work dates outside the quarter in the header (CMS skips those records), and hours before an employee's hire date or after their termination date.
- Employees. Hours for an employee ID missing from the file's employees section, duplicate employee IDs, termination dates before hire dates.
4. See what CMS sees (optional)
- Staffing star estimate. Add your resident days for the quarter and the report computes total nurse, RN and weekend hours per resident day from the file, scores them with the CMS cut points, and gives an estimated staffing star rating or range. Add your case-mix ratio and turnover to narrow it. Always labelled as an estimate, not your CMS rating.
- Deadline. Every report names the CMS deadline for the file's quarter and the days left.
Who it's for
- Nursing home operators: check the quarter's file before upload, with time left to fix it.
- Multi-facility groups: check every building's file from one script.
- Payroll and scheduling vendors: test a PBJ export in CI with a structured JSON report.
- AI agents and automation: a plain REST endpoint with a file in and JSON out.
Not checked
- Whether hours match payroll, invoices or contracts. That is what PBJ audits test, and only your records can answer it. The OIG found 45 of 100 sampled nursing homes reported RN hours that their records did not support (March 2024 data, report A-09-24-02005).
- Whether your facility ID and employee IDs are on file with CMS (CMS edits -3693 and -4016 need the CMS system). Hours for an ID that is not in the file's own employees section are flagged.
- Whether hours were worked onsite and whether the 30-minute meal break was deducted. The file has no shift times or locations.
- Your actual CMS staffing rating. CMS takes census and case mix from MDS and turnover from six quarters of PBJ; the estimate uses the numbers you send.
- Employee Link (administration) files, and ZIP and file naming rules.
Input and output
Send
POST the PBJ staffing XML file, a gzip of it, or the upload ZIP as the request body. Up to 4.4 MB per request; inside a ZIP, each XML file may be up to 50 MB. The whole file is checked: no sampling.
Validate
Structure and allowed values from the CMS v4.10.0 specifications, then daily and monthly totals, quarter coverage and the risk patterns.
Report
JSON with
status(PASS, WARN or FAIL),findings(severity, ruleId, XPath-style path, message, source), the reporting quarter, counts of employees, days and hours, days with and without RN hours, the deadline, and the staffing estimate when you send a census.
Full request and report schema in the API docs.
Try it now
| Severity | Rule | Where and what |
|---|---|---|
| Error | CMS-1021 | /header/@fileSpecVersionThis fileSpecVersion was retired on April 1, 2026. Files must use 4.10.0. |
| Error | CMS-3676 | /staffingHours/staffHours[8]/workDays/workDay[67]/hourEntries/hourEntry/jobTitleCodejobTitleCode must be one of the CMS job title codes 1 to 40. |
| Error | CMS-3676 | /staffingHours/staffHours[9]/workDays/workDay[66]/hourEntries/hourEntry/payTypeCodepayTypeCode must be 1 (exempt), 2 (non-exempt) or 3 (contract). |
| Error | CMS-3677 | /employees/employee[14]/hireDatehireDate is empty. Remove the tag when there is no date. |
| Error | CMS-3677 | /staffingHours/staffHours[3]/workDays/workDay[53]/datedate must be a valid date written as YYYY-MM-DD. |
| Error | CMS-4025 | /staffingHours/staffHours[4]/workDays/workDay[2]This employee has more than 22.5 hours in total on this date (all job titles together). CMS allows at most 22.5 and rejects the file above it. |
| Warning | CMS-1010 | /staffingHours/staffHours[7]/workDays/workDay[67]/datedate is outside the reporting quarter in the header. CMS does not process staffing hours records outside the quarter. |
| Warning | RISK-HOURS-PER-MONTH | /staffingHours/staffHours[12]This employee ID has more than 400 hours in one calendar month. CMS has named individual employees reporting over 400 hours a month as an audit selection criterion. The PBJ FAQ separately lists grouping several contract staff under one ID as a reason audits fail. Check that this ID is one person. |
| Warning | RISK-ID-PII | /employees/employee[13]/employeeIdThis employeeId has the shape of a Social Security Number. CMS requires IDs that contain no personal information such as an SSN. |
| Warning | RISK-NO-RN-DAYS | /staffingHours13 days in the reporting quarter have no RN hours (job title codes 5, 6 and 7). CMS gives a one-star staffing rating for four or more such days when residents were in the facility. This file is a merge, so hours already in the PBJ system may cover some of those days. |
Due to CMS by 2026-11-14, 11:59 PM Eastern Time: 42 days left.
Estimate only. This is not the CMS staffing rating, which CMS computes from its own MDS census, case mix and six quarters of PBJ data.
1 star score 145 to 255 of 380
Four or more days in the quarter have no RN hours, which brings a one-star staffing rating whatever the score.
- Every day in the quarter had at least one resident.
- Case mix at the national average (nursing case-mix ratio 1.0). CMS adjusts for your residents' acuity; send caseMixRatio if you know it.
- Case-mix adjustment approximated as reported hours divided by the case-mix ratio.
- This file is a merge: only the hours in this file are counted, not hours already submitted to CMS for the quarter.
- Turnover measures not supplied: the range covers every possible turnover score.
Checked as of 2026-10-03.
Pricing
$25.00 per completed report. One upload, one full report, even when the ZIP holds several XML files.
- Billed when a report is produced, PASS, WARN or FAIL. Invalid input is never billed: not XML, not a PBJ file, an Employee Link file, a ZIP with no XML.
- Paid from the same prepaid credits as every SpreadRun API, in $5, $20, $50 or $100 packs. A $50 pack covers 2 reports. Credits never expire. All pricing
- Checking files for many buildings every quarter? Talk to us first so we can tell you honestly whether this fits.
Call it from code
Parameters, the report format, rule IDs, error codes and limits are in the API docs.
curl -X POST "https://www.spreadrun.com/api/v1/pbj-staffing-qa" \
-H "Authorization: Bearer $SPREADRUN_API_KEY" \
-H "Content-Type: application/zip" \
--data-binary @pbj_2026_q4.zipQuestions
CMS already validates PBJ files for free. Why pay for this?
You should still upload to CMS: it is free, and its Final File Validation Report in iQIES is the one that counts. The PBJ Policy Manual says that report can take up to 24 hours, and that facilities must leave time to fix errors and resubmit before the deadline. SpreadRun answers in seconds, before you upload, from this page or from code. It also checks things the CMS edits do not, such as dates outside an employee's hire and termination dates and duplicate employee IDs, and it flags staffing patterns CMS has documented as audit or rating risks.
Does a PASS mean CMS will accept the file?
No. A PASS means the file passed the checks listed on this page. CMS also checks things only its system knows, such as whether your facility ID and each employee ID are on file, and the facility has to confirm acceptance in the Final File Validation Report. These are structural checks, not legal or compliance advice.
Does a PASS mean the file will survive a CMS audit?
No. PBJ audits compare reported hours with payroll, invoices and contracts. SpreadRun only sees the XML file, so it cannot tell whether the hours are true. The risk flags point at patterns CMS has named, which is useful, but a file with no flags can still fail an audit.
Where do the audit risk flags come from?
Only from what CMS or the HHS Office of Inspector General has published, and each finding names its source. Today that is: individual employees reported at more than 400 hours in a month (a CMS audit selection criterion, reported in 2018), four or more days in the quarter with no RN hours (which brings a one-star staffing rating under the Five-Star Technical Users' Guide), employee IDs shaped like Social Security Numbers (the Policy Manual says IDs must not contain one), and a replace upload with no hours in it. Numbers that circulate without a CMS or OIG source, such as hour thresholds per quarter, are not used.
Which files can I send?
The quarterly PBJ staffing XML file (fileSpecVersion 4.10.0), gzip of it, or the ZIP you upload to CMS, including a ZIP with several XML files. The request limit is 4.4 MB, and a large facility's XML can be bigger than that, so send the ZIP: staffing XML compresses to a few percent of its size. Each XML file inside may be up to 50 MB, the CMS limit. Employee Link (administration) files are not supported yet; they are rejected and not charged.
Which quarter and deadline apply right now?
PBJ follows the federal fiscal year. Hours for July 1 to September 30, 2026 are fiscal year 2026 quarter 4, and CMS must receive them by the end of the 45th day after the quarter ends: November 14, 2026, 11:59 PM Eastern Time. CMS accepts no submissions after the deadline. Since August 2026, PBJ files are uploaded in iQIES.
Is the staffing data stored?
No. Files are processed in memory for the length of the request and are not stored or shared. PBJ files identify staff by employee ID and contain hire and termination dates and hours worked, which is personal data about your staff. Findings name the location, the rule and the problem, never a value from your file. For billing and usage we log the time, endpoint, result status, upload size and duration, never the file contents.
When is a run charged?
When the validator finishes and returns a report, whether it says PASS, WARN or FAIL: $25.00 per report. Requests rejected before a report exists are free: not XML, not a PBJ nursingHomeData file, an Employee Link file, a ZIP with no XML file, or DOCTYPE and entity declarations.
How close is the staffing star estimate to the real rating?
It follows the published CMS method (Five-Star Technical Users' Guide, September 2026): reported nurse hours per resident day, adjusted for case mix, scored with the CMS cut points, plus the three turnover measures, against the 380-point scale. What it cannot match is CMS's inputs. CMS takes the census and case mix from MDS assessments and turnover from six quarters of PBJ data. If you send your resident days, case-mix ratio and turnover from your own reports, the estimate is close; leave any out and it shows a range. Either way it is an estimate, not your CMS rating.
Why do some dates show as in the future?
CMS rejects any date after the day you upload. The check uses today by default. To check a file as of the day you plan to upload it, pass asOf=YYYY-MM-DD. The count of days without RN hours also stops at that date, so a quarter still in progress is not penalized for days that have not happened.
Sources
- 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)
SpreadRun is not affiliated with or endorsed by CMS. Where this validator and the CMS PBJ data specifications differ, the CMS specifications control.
More validators: Hospital MRF Validator | the full catalog