Davis-Bacon WH-347 Certified Payroll Pre-Check API Reference

Beta. Recomputes one weekly certified payroll, in the fields of Form WH-347 (Rev. January 2025), against the wage determination rates sent with it. Product page and free test form.

Endpoint

Request

Workbook. Sheets named Header (two columns: field and value), Payroll, Wage Determination, and Apprenticeship when any worker is a registered apprentice. Row 1 of each table sheet holds the column names. Start from the sample workbook; its rates are invented.

JSON. The same tables as CSV text, with the header fields as an object:

{
  "header": {
    "project_name": "...",
    "project_no": "...",
    "payroll_no": 6,
    "contractor_name": "...",
    "contractor_address": "...",
    "project_location": "...",
    "wage_determination_no": "...",
    "week_ending": "2026-09-26"
  },
  "cwhssa": true,
  "payrollCsv": "entry_no,last_name,first_name,...,net_pay\\n1,...",
  "wageDeterminationCsv": "classification,base_rate,fringe_rate\\nElectrician,38.50,18.25\\n...",
  "apprenticeshipCsv": "classification,level,wage_percent,fringe_percent,ratio,program_name\\nElectrician,2,60,,1:1,..."
}

Up to 4.4 MB and 5,000 rows per table. Money cells may include a dollar sign and thousands separators. The wage determination rates are never looked up: the check uses exactly the rates you send, copied from the wage determination in the contract.

Header fields

Columns

Payroll: one row per worker per classification, as on the WH-347. Every column except the optional ones must be present; leave a cell blank or 0 where nothing applies.

Wage determination: classification, base_rate, fringe_rate (blank means 0). One row per classification.

Apprenticeship: classification, level, wage_percent (of the journeyworker basic rate), fringe_percent (blank when the program does not specify fringe benefits, so the full rate applies), ratio (apprentices:journeyworkers, such as 1:3), and optionally program_name.

Filled WH-347 (PDF)

Add ?form=pdf to a paid call. When the report is a PASS, the response also has filledForm, outside report: available, filename, contentType (application/pdf), bytes, base64 and a note. It is DOL Form WH-347, January 2025 revision, as published, with your values drawn on it: page 1 for every 8 payroll rows (entry numbers continue across pages), then page 2 with the project details, up to three apprenticeship programs and up to eight workers' total hourly fringe credit, and an addendum page for any more. Fringe plan names, types and numbers, the OA or SAA boxes, the Statement of Compliance boxes, the certifying official and the signature, date, telephone and email are left blank for the contractor.

For WARN or FAIL, filledForm is {"available": false, "reason": "..."}. Demo calls never get a form. The form is included in the report price, is built in memory for the response and is not stored, logged or cached. It contains your payroll values, as it must; the report still never does.

Report

Rule IDs

Money comparisons allow one cent for rounding.

Source keys, as returned in every report:

• DOL Wage and Hour Division: Form WH-347 (Rev. January 2025) and its instructions
• 29 CFR part 5: Davis-Bacon contract clauses (5.5), fringe benefit crediting (5.31) and overtime (5.32)
• SAM.gov wage determinations, where the rates for your contract are published

Not checked

• Whether the wage determination rates you supplied are the right ones for the contract, project location and dates. SpreadRun checks against the rates you send; it does not look them up.
• Whether workers are classified correctly for the work they actually did.
• Hours worked on other projects for the same contractor, which count toward the 40-hour overtime threshold but are not on this payroll.
• Whether apprentices are individually registered, and the apprentice ratio across the contractor's whole workforce on the job site (only this payroll is counted).
• Whether fringe benefit plans are bona fide, annualization of fringe credits, and approval of unfunded plans.
• Whether deductions are permitted under 29 CFR part 3.
• The Statement of Compliance and signature on page 2.

Example responses

A paid check of the clean sample payroll (report shortened to its summary fields), and the first 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": "wh347-payroll-precheck",
  "mode": "paid",
  "charged": true,
  "priceCents": 2500,
  "balanceCents": 7500,
  "report": {
    "schemaVersion": 1,
    "status": "PASS",
    "form": "WH-347 (Rev. January 2025)",
    "weekEnding": "2026-09-26",
    "overtimeRule": "cwhssa",
    "counts": {
      "rows": 5,
      "workers": 4,
      "apprentices": 1,
      "classifications": 4,
      "totalHours": "164.00"
    },
    "findingCount": 0,
    "findingCounts": {
      "error": 0,
      "warning": 0
    },
    "ruleCounts": {},
    "findings": [],
    "findingsTruncated": false,
    "scope": "Recomputes the payroll against the wage determination rates supplied. A PASS does not mean the payroll complies with Davis-Bacon requirements, and this is not legal or compliance advice.",
    "input": {
      "format": "json",
      "bytes": 1902
    },
    "inputSha256": "36a5a7ab053a3ab899ee436ccb0693dbcec207fe08057db699e76a0b5c880291"
  }
}

[
  {
    "severity": "error",
    "ruleId": "WH-APPR-PROGRAM",
    "path": "/payroll/row[8]/apprentice_level",
    "message": "No apprenticeship program wage schedule was supplied for this classification and level, so the journeyworker rate on the wage determination applies.",
    "source": "cfr5.5"
  },
  {
    "severity": "error",
    "ruleId": "WH-DEDUCTIONS-TOTAL",
    "path": "/payroll/row[4]/total_deductions",
    "message": "Total deductions does not equal tax withholdings plus FICA plus other deductions.",
    "source": "wh347"
  },
  {
    "severity": "error",
    "ruleId": "WH-FRINGE-SHORT",
    "path": "/payroll/row[3]",
    "message": "Wages, fringe benefit credit (6B) and cash in lieu of fringe benefits (6C) together are less than the basic hourly rate plus the fringe benefit rate owed for these hours (overtime premium on the basic rate only).",
    "source": "cfr5.31"
  },
  {
    "severity": "error",
    "ruleId": "WH-FRINGE-SHORT",
    "path": "/payroll/row[6]",
    "message": "Wages, fringe benefit credit (6B) and cash in lieu of fringe benefits (6C) together are less than the basic hourly rate plus the fringe benefit rate owed for these hours (overtime premium on the basic rate only).",
    "source": "cfr5.31"
  }
]

Errors

See the shared error table. Rejected with HTTP 400 and not charged: an empty body, a PDF, a ZIP that is not an .xlsx workbook, a workbook without Header, Payroll and Wage Determination sheets, DOCTYPE or entity declarations, JSON without payrollCsv or wageDeterminationCsv, CSV with repeated column names or ragged rows, more than 5,000 rows. Example (HTTP 400):

{
  "error": {
    "code": "input_error",
    "message": "wageDeterminationCsv is required: the table as CSV text, with a header row.",
    "requestId": "7f3c2a1e-5b8d-4c6f-9e0a-1d2b3c4d5e6f",
    "charged": false
  }
}

Code samples

# Excel workbook
curl -X POST "https://www.spreadrun.com/api/v1/wh347-payroll-precheck" \
  -H "Authorization: Bearer $SPREADRUN_API_KEY" \
  -H "Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" \
  --data-binary @payroll_week_06.xlsx

# JSON with CSV tables
curl -X POST "https://www.spreadrun.com/api/v1/wh347-payroll-precheck" \
  -H "Authorization: Bearer $SPREADRUN_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @payroll_week_06.json