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 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 1,000,000+ graded contractors across 11 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 and numeric score. Factor breakdowns show how severity, frequency, abatement window, 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 | 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
Three 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.
Repeat violation cap — a Repeat citation issued within the past 60 months locks the grade at B or below. A Repeat citation means OSHA cited the employer again for a hazard it had already been cited for.
Data source and freshness
Grades are generated from the U.S. Department of Labor OSHA enforcement database, updated from bulk CSV exports. Coverage spans 11 states: CA, FL, GA, ID, IL, NY, OR, PA, TX, WA, 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 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 |
| Abatement Window | 15% | Days OSHA allowed to abate each citation | Moderate — influenced by legal timing |
| Recency | 15% | How recent the violations are, with exponential decay | Lower for old records |
Temporal discounting
Recency measures how long a contractor has gone since its most recent citation. A citation issued today scores 0; the score rises steadily with the age of that most recent citation, with no jumps, and levels off at 92 after 15 years. Withdrawn citations are not counted.
| Age of most recent citation | Recency Score |
|---|---|
| 0–1 year | 0–60 |
| 1–3 years | 60–80 |
| 3–7 years | 80–90 |
| 7–15 years | 90–92 |
| 15+ years | 92 |
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
Planned
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 not yet available. Join the waitlist below and we'll reach out when access opens.
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,
"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 will be issued per account and scoped to published rate limits.
API keys will be issued when the API becomes available.
Rate limits
| Plan | Requests / minute | Requests / month |
|---|---|---|
| Planned | 10 | 1,000 |
Rate limit headers will be returned with every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Join the API waitlist
The Complifield API is planned and not yet available. We're collecting use cases from general contractors, insurers, and enterprise platforms. Describe yours and we'll reach out when access opens.