Complifield Docs
Reference documentation for the Complifield grade platform — how to use the search, how grades are calculated, and how to access data programmatically.
Using the platform
Searching for a contractor
Complifield searches federal OSHA enforcement records maintained by the U.S. Department of Labor. Enter a contractor's company name or license number in the search bar and select their state. Results are matched against 980,000+ graded contractors across 10 states.
Search tips:
- Use the legal business name, not a trade name or DBA
- License number format varies by state — e.g. FL licenses begin with CGC, CBC, CFC, or similar prefix
- Partial name matches are supported — "Apex Roofing" will return "Apex Roofing Co. LLC"
Reading a grade report
Each report summarizes a contractor's federal safety record into a single letter grade, numeric score, and plain-English verdict. Factor breakdowns show how severity, frequency, response time, and recency contributed to the final grade.
| Grade | Score | What it means | When to hire |
|---|---|---|---|
| A | 90–100 | Clean federal record or very old, minor violations | Hire with confidence |
| B | 70–89 | Minor or well-aged violations, corrected promptly | Ask one or two questions |
| C | 50–69 | Moderate violations or slow correction history | Proceed with conditions |
| D | 30–49 | Serious violations or recent pattern | Consider alternatives |
| F | 0–29 | Willful violations, fatality record, or severe pattern | Do not hire without review |
Score override rules
Two conditions lock the grade regardless of factor scores:
Willful violation cap — any willful OSHA citation in the record locks the grade at C or below. A willful violation means the hazard was known and ignored. This cap cannot be overridden by strong scores in other factors.
Fatality cap — a fatality inspection within the past 36 months locks the grade at D or below, regardless of other factors.
Data source and freshness
Grades are generated from the U.S. Department of Labor OSHA federal enforcement database, updated from bulk CSV exports. Coverage spans 10 states: FL, TX, CA, NY, WA, OR, ID, GA, IL, and WI. State-plan states (where OSHA enforcement is handled by the state rather than federal OSHA) may have incomplete coverage.
Data is not real-time. The banner on each report indicates the most recent data load date.
Complifield is informational only and is not affiliated with OSHA or the U.S. Department of Labor.
How grades are calculated
The four-factor model
Every Complifield grade is a weighted composite of four signals drawn from federal OSHA enforcement records. Each factor is scored 0–100 before weighting.
| Factor | Weight | What it measures | Signal quality |
|---|---|---|---|
| Severity | 40% | Violation tier assigned by OSHA (Willful, Repeat, Serious, Other) | Highest — not self-reported |
| Frequency | 30% | Violation rate normalized per inspection | High — controls for firm size |
| Response Time | 15% | Days to abate each cited violation | Moderate — influenced by legal timing |
| Recency | 15% | How recent the violations are, with exponential decay | Lower for old records |
Temporal discounting
Past violations are not treated equally. A citation from 40 years ago carries approximately 2% of the weight of a citation issued last month. The recency score uses a piecewise approximation of exponential decay.
| Violation Age | Recency Score | Weight Remaining |
|---|---|---|
| 0–1 year | 0–60 | Full weight |
| 1–3 years | 40–60 | Partial |
| 3–7 years | 60–80 | Moderate |
| 7–15 years | 75–90 | Low |
| 15+ years | ~92 | Near-zero |
The recency ceiling is 92, not 100. A score of 100 would treat a historically-cited company identically to one that was never inspected — which is economically incorrect.
For the complete academic framework — including the five economic models, Nobel Prize connections, and worked examples from live OSHA data — see the Methodology page.
Read the full methodology →Programmatic access
Private Beta
The Complifield API allows programmatic access to contractor grades, inspection history, and violation records. It is designed for general contractors running bulk sub-vetting workflows, insurance underwriters integrating safety scores into pricing models, and enterprise platforms building contractor qualification tools.
The API is currently in private beta. Access is granted by application. Public availability is planned for Q3 2026.
Endpoint reference
Returns the grade, score, and summary for a single contractor by slug.
Search contractors by name or license number. Returns a paginated list with grade and score for each result.
Returns the full inspection history and citation detail for a contractor.
Example response
{
"slug": "apex-roofing-co-fl",
"name": "Apex Roofing Co.",
"state": "FL",
"license": "CCC1234567",
"grade": "C",
"score": 67.4,
"verdict": "Proceed carefully",
"factors": {
"severity": 58,
"frequency": 63,
"response_time": 80,
"recency": 79
},
"inspection_count": 4,
"violation_count": 3,
"last_inspection": "2021-08-14",
"data_as_of": "2026-06-01"
}
Authentication
API requests require a Bearer token passed in the Authorization header. Tokens are issued per account and scoped to your plan's rate limits.
API keys are available to Enterprise plan subscribers. During private beta, keys are issued manually upon approval.
Rate limits
| Plan | Requests / minute | Requests / month |
|---|---|---|
| Premium | — | — |
| Enterprise | 60 | 50,000 |
| Private Beta | 10 | 1,000 |
Rate limit headers are returned with every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Join the API waitlist
The Complifield API is currently in private beta. We're onboarding general contractors, insurers, and enterprise platforms. Describe your use case and we'll reach out.