API Documentation

Getting Started

1. Create a free account (50 lookups/month, no credit card)
2. Verify your email — you will receive your API key
3. Make your first API call:

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.fastdol.com/v1/employers?name=walmart&zip=83669"

Authentication

Include your API key in the X-Api-Key header with every request. Keys are created when you verify your email. You can view your key on the account page.

Endpoints

Search Employers

GET /v1/employers?name=walmart&state=ID&zip=83669&limit=20&offset=0

Parameters:

Get Employer Detail

GET /v1/employers/{employer_id}

Inspection History

GET /v1/employers/{employer_id}/inspections?limit=20&offset=0

Free — not counted against your quota.

Risk History

GET /v1/employers/{employer_id}/risk-history?limit=90

Parent Company Rollup

GET /v1/employers/parent?name=Amazon&state=CA

Aggregate risk across all locations of a parent company.

Batch Lookup

POST /v1/employers/batch
Content-Type: application/json

{
  "lookups": [
    {"name": "Walmart", "state": "ID", "zip": "83669"},
    {"name": "Amazon", "state": "CA"},
    {"name": "Target", "zip": "55403"}
  ]
}

Up to 100 items per request. Each item can include name, ein, employer_id, state, zip, city.

CSV Upload

POST /v1/employers/upload-csv
Content-Type: multipart/form-data

file: employers.csv

Upload a CSV with employer names. Returns a CSV with risk profiles appended. Max 500 rows, 5MB.

Industry Benchmarks

GET /v1/industries/4451
GET /v1/industries/naics-codes

Response Format

{
  "results": [
    {
      "employer_id": "uuid",
      "employer_name": "WALMART",
      "address": "123 MAIN ST",
      "city": "STAR",
      "state": "ID",
      "zip": "83669",
      "naics_code": "452112",
      "naics_description": "Discount Department Stores",
      "risk_tier": "MEDIUM",
      "risk_score": 12.5,
      "osha_inspections": 3,
      "osha_violations": 7,
      "osha_total_penalties": 15000.00,
      "whd_cases": 1,
      "whd_backwages_total": 5000.00,
      "trend_signal": "STABLE",
      "confidence_tier": "HIGH",
      "svep_flag": false,
      "parent_name": "Walmart Inc.",
      "location_count": 140
    }
  ],
  "total_count": 1,
  "limit": 20,
  "offset": 0,
  "data_notes": {
    "freshness": "OSHA citations typically appear 3-8 months after inspection date.",
    "coverage": "Data includes OSHA inspections/violations and WHD wage enforcement.",
    "scoring": "Risk scores combine OSHA violation severity and WHD back wages."
  }
}

Risk Scoring

Risk scores range from 0-100 and combine:

• OSHA violations — willful (30 pts), repeat (15 pts), serious (3 pts)
• OSHA penalties — up to 15 pts based on dollar amount
• WHD enforcement — back wages (up to 8 pts), cases (up to 4 pts), employees violated (up to 3 pts)
• MSHA mine safety — violations and assessed penalties contribute to risk score for mining employers

Risk tiers: HIGH (willful violations, >$100k penalties), ELEVATED, MEDIUM, LOW.

Rate Limits

100 requests per minute per API key. If exceeded, you will receive a 429 response. Wait and retry.

Errors

{
  "detail": {
    "error": "error_code",
    "message": "Human-readable description"
  }
}

Code Examples

Python

import requests

API_KEY = "your_api_key"
BASE = "https://api.fastdol.com/v1"

# Search
r = requests.get(f"{BASE}/employers",
    headers={"X-Api-Key": API_KEY},
    params={"name": "Walmart", "state": "ID"})
print(r.json()["results"][0]["risk_tier"])

# Batch
r = requests.post(f"{BASE}/employers/batch",
    headers={"X-Api-Key": API_KEY},
    json={"lookups": [
        {"name": "Walmart", "zip": "83669"},
        {"name": "Amazon", "state": "CA"},
    ]})
for item in r.json()["results"]:
    print(item["query"]["name"], "->", item["match"]["risk_tier"] if item["match"] else "no match")

JavaScript

const API_KEY = "your_api_key";
const BASE = "https://api.fastdol.com/v1";

const res = await fetch(
  `${BASE}/employers?name=walmart&zip=83669`,
  { headers: { "X-Api-Key": API_KEY } }
);
const data = await res.json();
console.log(data.results[0].risk_tier);

curl

# Search
curl -H "X-Api-Key: YOUR_KEY" \
  "https://api.fastdol.com/v1/employers?name=walmart&zip=83669"

# CSV Upload
curl -H "X-Api-Key: YOUR_KEY" \
  -F "file=@employers.csv" \
  "https://api.fastdol.com/v1/employers/upload-csv" \
  -o results.csv