FastDOL

opencollection: 1.0.0
info:
  name: FastDOL API
  version: '1.0'
items:
- info:
    name: FastDOL Search Employers
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/employers
    headers:
    - name: X-Api-Key
      value: string
    params:
    - name: name
      value: Acme Construction Inc
      type: query
      description: Fuzzy employer name search
    - name: ein
      value: 12-3456789
      type: query
      description: Exact EIN match
    - name: state
      value: CA
      type: query
      description: State code filter (e.g., CA)
    - name: zip
      value: '94105'
      type: query
      description: 5-digit zip code filter
    - name: naics
      value: '2362'
      type: query
      description: 4-digit NAICS prefix filter
    - name: parent_only
      value: 'false'
      type: query
      description: Only return employers with a parent_name (known parent companies)
    - name: parent_name
      value: walmart-inc
      type: query
      description: Filter to locations under a specific parent company (exact match)
    - name: has_fatalities
      value: 'false'
      type: query
      description: Filter to locations with fatality investigations
    - name: svep
      value: 'false'
      type: query
      description: Filter to locations on the Severe Violator Enforcement Program
    - name: sort_by
      value: string
      type: query
      description: 'Sort results by: risk_score (default), violations, penalties, inspections, fatalities'
    - name: sort_dir
      value: string
      type: query
      description: 'Sort direction: desc (default) or asc'
    - name: limit
      value: '20'
      type: query
    - name: offset
      value: '0'
      type: query
  docs: 'Search employers by name, EIN, zip, state, or NAICS.


    Returns a flat list of employer locations sorted by risk score (worst first).

    Each result includes `related_locations_count` showing how many locations

    share the same normalized employer name — useful for national chains.'
- info:
    name: FastDOL GET Parent Company
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/employers/parent
    headers:
    - name: X-Api-Key
      value: string
    params:
    - name: name
      value: Acme Construction Inc
      type: query
      description: Parent company name (e.g., 'Amazon', 'Walmart')
    - name: state
      value: CA
      type: query
      description: Filter locations by state
    - name: limit
      value: '20'
      type: query
    - name: offset
      value: '0'
      type: query
  docs: 'Parent company risk rollup — aggregate risk across all locations.


    Returns company-wide statistics (total inspections, violations, penalties,

    risk distribution) plus a paginated list of individual locations sorted

    by risk score (worst first).


    Premium feature for enterprise customers evaluating national employers.'
- info:
    name: FastDOL GET Employer by EIN
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/employers/ein/:ein
    headers:
    - name: X-Api-Key
      value: string
    params:
    - name: ein
      value: 12-3456789
      type: path
    - name: state
      value: CA
      type: query
      description: State code filter
    - name: limit
      value: '20'
      type: query
    - name: offset
      value: '0'
      type: query
  docs: 'Lookup employers by FEIN (Federal Employer Identification Number).


    Returns all locations matching the given EIN. Insurance professionals

    identify employers by FEIN — this is the primary lookup for underwriting

    integrations.


    EIN format: 9 digits (e.g., ''943067788'' or ''94-3067788'').'
- info:
    name: FastDOL GET Employer
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/employers/:employer_id
    headers:
    - name: X-Api-Key
      value: string
    params:
    - name: employer_id
      value: emp_8a3b9c2d1e4f
      type: path
  docs: Direct lookup by employer_id UUID.
- info:
    name: FastDOL GET Inspections
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/employers/:employer_id/inspections
    headers:
    - name: X-Api-Key
      value: string
    params:
    - name: employer_id
      value: emp_8a3b9c2d1e4f
      type: path
    - name: limit
      value: '20'
      type: query
    - name: offset
      value: '0'
      type: query
  docs: 'Get inspection history with violation detail for an employer.


    Metered: one lookup per call. Previously unmetered, which made it trivial

    for a free-tier key to scrape the entire product by combining the sitemap

    endpoint (employer IDs) with this one (full inspection history per id).'
- info:
    name: FastDOL GET Severe Injuries
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/employers/:employer_id/severe-injuries
    headers:
    - name: X-Api-Key
      value: string
    params:
    - name: employer_id
      value: emp_8a3b9c2d1e4f
      type: path
    - name: limit
      value: '20'
      type: query
    - name: offset
      value: '0'
      type: query
  docs: 'Per-event OSHA Severe Injury Reports (29 CFR 1904.39) for an employer.


    Each row is an injury the employer self-reported within 24 hours

    -- in-patient hospitalization, amputation, or loss of an eye.

    Distinct from /employers/{id}/inspections (inspection-triggered):

    SIR is injury-triggered, so the same event may or may not have a

    related inspection (see inspection_activity_nr -- often NULL).


    Metered: one lookup per call, same as inspections / SEC enforcement.

    Newest event first.'
- info:
    name: FastDOL GET WHD Cases
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/employers/:employer_id/whd-cases
    headers:
    - name: X-Api-Key
      value: string
    params:
    - name: employer_id
      value: emp_8a3b9c2d1e4f
      type: path
    - name: limit
      value: '20'
      type: query
    - name: offset
      value: '0'
      type: query
  docs: 'Per-case WHD (Wage & Hour Division) enforcement records for an

    employer.


    Each row is one closed case carrying backwages assessed

    (`bw_amt`) and the count of underpaid employees

    (`ee_violtd_cnt`). Covers FLSA, FMLA, MSPA, H-1B/H-2A/H-2B, CCPA,

    and any other DOL WHD-administered statute.


    Metered: one lookup per call, same pattern as the other detail

    endpoints. Most-recent case first.'
- info:
    name: FastDOL GET OSHA Accidents
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/employers/:employer_id/osha-accidents
    headers:
    - name: X-Api-Key
      value: string
    params:
    - name: employer_id
      value: emp_8a3b9c2d1e4f
      type: path
    - name: limit
      value: '20'
      type: query
    - name: offset
      value: '0'
      type: query
  docs: 'Per-event OSHA accident records (inspection-triggered).


    Each row is an accident/fatality/catastrophe OSHA documented while

    investigating an inspection at this employer. Distinct from

    /employers/{id}/severe-injuries (SIR is injury-triggered and

    self-reported under 29 CFR 1904.39); accidents only surface through

    an OSHA-opened inspection.


    The narrative `abstract_text` is truncated at 4000 chars upstream

    (silver/osha_accident_detail) to keep row size bounded.


    Metered: one lookup per call, same a'
- info:
    name: FastDOL GET SEC Enforcement
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/employers/:employer_id/sec-enforcement
    headers:
    - name: X-Api-Key
      value: string
    params:
    - name: employer_id
      value: emp_8a3b9c2d1e4f
      type: path
    - name: limit
      value: '20'
      type: query
    - name: offset
      value: '0'
      type: query
  docs: 'Get SEC enforcement actions filed against an employer''s parent

    company.


    Joined via employer_profile.parent_name → sec_enforcement_detail

    .parent_name. Returns empty results for non-public-parent employers

    (~99% of employers — most aren''t SEC registrants).


    Metered: one lookup per call. Same justification as get_inspections

    — un-metered would let a free-tier key scrape the entire SEC

    enforcement-history dataset for free by walking the sitemap.'
- info:
    name: FastDOL GET Peers
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/employers/:employer_id/peers
    headers:
    - name: X-Api-Key
      value: string
    params:
    - name: employer_id
      value: emp_8a3b9c2d1e4f
      type: path
    - name: limit
      value: '20'
      type: query
  docs: 'Peer establishments — same NAICS+state cohort, plus same-parent

    siblings.


    Powers the "Other employers in this industry" and "Other

    establishments under this parent" sections of the profile page.

    These sections double as internal-link targets that pass authority

    to long-tail leaf URLs (otherwise SEO dead-ends since most thin

    profiles have no inbound links).


    Returns up to `limit` rows per cohort, ordered by

    agency_violation_count DESC so the most-active peers surface first

    — better signal for th'
- info:
    name: FastDOL GET Violations
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/inspections/:activity_nr/violations
    headers:
    - name: X-Api-Key
      value: string
    params:
    - name: activity_nr
      value: '316254783'
      type: path
  docs: 'Get violation detail for a specific inspection.


    Metered: one lookup per call. See get_inspections for rationale.'
- info:
    name: FastDOL Batch Lookup
    type: http
  http:
    method: POST
    url: https://api.fastdol.com/v1/employers/batch
    headers:
    - name: X-Api-Key
      value: string
    body:
      type: json
      data: '{}'
  docs: 'Batch employer lookup — designed for spreadsheet-style bulk searches.


    Each item can include name, ein, employer_id, plus optional location

    filters (state, zip, city) to narrow to a specific site.


    Up to 100 items processed synchronously. 101-500 returns a job_id

    for async polling (coming soon). Max 500 items per request.


    Typical usage: underwriter uploads a spreadsheet with company name +

    address for each policy they''re quoting.'
- info:
    name: FastDOL GET Risk History
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/employers/:employer_id/risk-history
    headers:
    - name: X-Api-Key
      value: string
    params:
    - name: employer_id
      value: emp_8a3b9c2d1e4f
      type: path
    - name: limit
      value: '20'
      type: query
  docs: Risk tier history for an employer over time. Shows nightly snapshots.
- info:
    name: FastDOL Submit Feedback
    type: http
  http:
    method: POST
    url: https://api.fastdol.com/v1/employers/:employer_id/feedback
    headers:
    - name: X-Api-Key
      value: string
    params:
    - name: employer_id
      value: emp_8a3b9c2d1e4f
      type: path
    body:
      type: json
      data: '{}'
  docs: Submit feedback about an employer match. Not metered.
- info:
    name: FastDOL List NAICS Codes
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/industries/naics-codes
    headers:
    - name: X-Api-Key
      value: string
  docs: List all 4-digit NAICS codes with employer counts.
- info:
    name: FastDOL GET Industry
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/industries/:naics4
    headers:
    - name: X-Api-Key
      value: string
    params:
    - name: naics4
      value: '2362'
      type: path
  docs: Industry-level risk benchmarks for a 4-digit NAICS code.
- info:
    name: FastDOL Sitemap Employers
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/sitemap/employers
    headers:
    - name: X-Api-Key
      value: string
    params:
    - name: limit
      value: '20'
      type: query
    - name: offset
      value: '0'
      type: query
    - name: indexable_only
      value: 'false'
      type: query
      description: When true, return only employers with at least one enforcement signal across any aggregated source. Used
        by the Next.js sitemap generator so Google isn't asked to crawl thin templated profiles that the page itself noindex's
        anyway.
  docs: 'Return employer IDs for sitemap generation with pagination. Not metered.


    Requires the dedicated ``sitemap:read`` scope — intentionally NOT in the

    free-tier default scopes. The only legitimate caller is the Next.js

    server generating sitemap shards for SEO; that route uses DEMO_API_KEY

    whose scopes must include ''sitemap:read''. Free customer keys cannot

    enumerate the entire dataset via this endpoint.


    Pagination: use offset/limit to page through all employers.

    Returns total_count so the caller kno'
- info:
    name: FastDOL Signup
    type: http
  http:
    method: POST
    url: https://api.fastdol.com/auth/signup
    body:
      type: json
      data: '{}'
  docs: Create account with email + password. Sends verification email.
- info:
    name: FastDOL Verify Email
    type: http
  http:
    method: POST
    url: https://api.fastdol.com/auth/verify
    body:
      type: json
      data: '{}'
  docs: "Verify email address.\n\nAccepts the token in the JSON body (POST) rather than the URL\n(GET) so it doesn't leak\
    \ via:\n  * server access logs (nginx, application-level request logs)\n  * exception tracebacks that include request\
    \ URLs\n  * Referer headers when the verify page links anywhere\n  * browser history shared from a kiosk / shared screen\n\
    The Next.js verify page reads the token from the URL once,\nimmediately replaceState's it out of the address bar, then\
    \ POSTs\nthe value here.\n\nBehavior change (w"
- info:
    name: FastDOL Login
    type: http
  http:
    method: POST
    url: https://api.fastdol.com/auth/login
    body:
      type: json
      data: '{}'
  docs: Login with email + password. Returns JWT as HttpOnly cookie.
- info:
    name: FastDOL Logout
    type: http
  http:
    method: POST
    url: https://api.fastdol.com/auth/logout
  docs: 'End the current session. Records the JWT''s jti in revoked_tokens so

    the token cannot be reused even if the cookie was copied elsewhere

    (DevTools, proxy log, shared machine) before the browser cleared it.


    Best-effort: a request without a valid JWT still returns 200 so the

    frontend can always clear its local state, and a DB failure during

    revocation still clears the cookie (logging server-side) — we never

    want logout to fail in a way that leaves the user logged in.'
- info:
    name: FastDOL GET Me
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/auth/me
  docs: 'Return the authenticated customer''s public identity.


    Used by the frontend header + account pages to show the logged-in

    email without trusting client-side pathname heuristics. 401s when

    the access_token cookie is missing/expired/invalid so the frontend

    can reliably fall back to logged-out rendering.'
- info:
    name: FastDOL Forgot Password
    type: http
  http:
    method: POST
    url: https://api.fastdol.com/auth/forgot-password
    body:
      type: json
      data: '{}'
  docs: 'Request password reset. Always returns 202 (don''t leak if email exists).


    All real work runs in a background task so request-thread timing

    can''t distinguish the "email exists" path (DB write + Resend

    call: tens to hundreds of ms) from "email unknown" (immediate

    return) from "rate-limited" (immediate return). Closes the

    timing-enumeration vector flagged in the re-audit.'
- info:
    name: FastDOL Reset Password
    type: http
  http:
    method: POST
    url: https://api.fastdol.com/auth/reset-password
    body:
      type: json
      data: '{}'
  docs: Reset password using token from email.
- info:
    name: FastDOL GET Plan
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/dashboard/plan
  docs: Return current plan info including pending cancellation status.
- info:
    name: FastDOL List Keys
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/dashboard/keys
  docs: List all API keys for the current customer.
- info:
    name: FastDOL Create Key
    type: http
  http:
    method: POST
    url: https://api.fastdol.com/dashboard/keys
    body:
      type: json
      data: '{}'
  docs: Generate a new API key. Raw key shown ONCE in response.
- info:
    name: FastDOL Rotate Key
    type: http
  http:
    method: POST
    url: https://api.fastdol.com/dashboard/keys/:key_id/rotate
    params:
    - name: key_id
      value: key_5f8c3a2d1e4b
      type: path
  docs: Rotate a key. Old key works for 48h, new key is immediately active.
- info:
    name: FastDOL Revoke Key
    type: http
  http:
    method: DELETE
    url: https://api.fastdol.com/dashboard/keys/:key_id
    params:
    - name: key_id
      value: key_5f8c3a2d1e4b
      type: path
  docs: Immediately revoke an API key.
- info:
    name: FastDOL Delete Account
    type: http
  http:
    method: DELETE
    url: https://api.fastdol.com/dashboard/account
    body:
      type: json
      data: '{}'
  docs: "Delete the authenticated customer's account and all associated data.\n\nImplements GDPR Article 17 (\"right to erasure\"\
    ) and CCPA equivalents.\nRequires password re-authentication to prevent XSS / CSRF / session-theft\nescalating into full\
    \ account wipe, plus an explicit \"DELETE\" confirmation\nstring to defeat accidental or malicious one-click destruction.\n\
    \nCascades (via existing FKs in migrations/001_init + 002_add_constraints):\n  - api_keys, email_verifications, password_reset_tokens,\
    \ subscriptions,\n"
- info:
    name: FastDOL Stripe Webhook Tombstone
    type: http
  http:
    method: POST
    url: https://api.fastdol.com/webhooks/stripe
  docs: 'No-op accept for Stripe webhook deliveries post-redesign.


    Returns 200 immediately so Stripe''s retry loop doesn''t keep

    re-queuing events. We don''t read the body, don''t verify the

    signature, don''t log anything sensitive.


    Per-IP throttle keeps a non-Stripe attacker from using this

    unauthenticated endpoint as cheap bandwidth — legitimate Stripe

    deliveries come from many edge IPs and won''t hit the cap.'
- info:
    name: FastDOL Upload CSV
    type: http
  http:
    method: POST
    url: https://api.fastdol.com/v1/employers/upload-csv
    headers:
    - name: X-Api-Key
      value: string
    body:
      type: multipart-form
      data: []
  docs: "Upload a CSV of employers, get back a CSV with risk profiles.\n\nExpected CSV columns (flexible — matches by header\
    \ name):\n    Required: name OR company_name OR employer_name\n    Optional: state, zip, city, ein\n\nExtra columns in\
    \ the input are preserved in the output.\nOutput adds: employer_id, match_confidence, risk_tier, risk_score,\nosha_inspections,\
    \ osha_violations, osha_total_penalties,\nlocation_count, trend_signal"
- info:
    name: FastDOL State Stats
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/stats/state/:code
    params:
    - name: code
      value: CA
      type: path
  docs: "State-level aggregates + top employers + top industries.\n\nPowers the /state/[slug] SEO landing pages. Returns:\n\
    \  - `state`: 2-letter code and full name\n  - `totals`: inspections, violations, penalties, fatalities, WHD backwages,\n\
    \    employer count in one pass\n  - `top_by_violations`: top 50 employers ordered by osha_violations\n  - `top_by_penalties`:\
    \ top 50 by osha_total_penalties\n  - `top_by_fatalities`: top 20 by osha_fatalities (only non-zero)\n  - `top_naics`:\
    \ top 10 industries by violation v"
- info:
    name: FastDOL Industry Stats
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/stats/industry/:naics
    params:
    - name: naics
      value: '2362'
      type: path
  docs: 'Industry aggregates + top employers + state breakdown.


    Accepts 2-, 3-, or 4-digit NAICS prefixes. Matches against the 6-digit

    naics_code on employer_profile_latest via LIKE ''{prefix}%''. 3-digit is

    the sweet spot for SEO — broad enough to have volume, specific enough

    to rank ("Motor Vehicle Manufacturing OSHA Violations").'
- info:
    name: FastDOL Industries Index
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/stats/industries
  docs: '3-digit NAICS subsectors that have any employer on file, with volumes.

    Powers the /industries landing page.'
- info:
    name: FastDOL Nursing Home Detail
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/stats/nursing-home/:ccn
    params:
    - name: ccn
      value: '055123'
      type: path
  docs: 'Detailed view for a single nursing home facility.


    Returns the facility''s full CMS payload (ratings, deficiencies,

    penalties, ownership) plus a pointer to the matching employer_id so

    the frontend can link to the federal-enforcement profile.'
- info:
    name: FastDOL Nursing Homes by State
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/stats/nursing-homes/:state_code
    params:
    - name: state_code
      value: CA
      type: path
  docs: State-level nursing home aggregates + top/bottom facilities.
- info:
    name: FastDOL Nursing Homes Index
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/stats/nursing-homes
  docs: 'Per-state counts of nursing homes for the /nursing-homes index page.


    Returns an empty state list (rather than 500) when the CMS columns

    haven''t yet been projected into the employer_profile_latest

    materialized view — this happens between the migration apply and

    the first nightly sync.'
- info:
    name: FastDOL States Index
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/stats/states
  docs: List of all supported state codes + employer counts for the /states page.
- info:
    name: FastDOL Create Export
    type: http
  http:
    method: POST
    url: https://api.fastdol.com/v1/export
    headers:
    - name: X-Api-Key
      value: string
    body:
      type: json
      data: '{}'
  docs: 'Start a bulk export job. Returns 202 with a job_id to poll.


    At least one filter field must be set — unfiltered exports would

    scan the entire employer table and are refused.'
- info:
    name: FastDOL GET Export
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/export/:job_id
    headers:
    - name: X-Api-Key
      value: string
    params:
    - name: job_id
      value: job_2c5d7a93b1f0
      type: path
  docs: 'Poll an export job. Returns status and — once finished — a

    download URL valid until the job expires (24h after creation).'
- info:
    name: FastDOL Download Export
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/export/:job_id/download
    headers:
    - name: X-Api-Key
      value: string
    params:
    - name: job_id
      value: job_2c5d7a93b1f0
      type: path
  docs: Stream the generated export file. 404 if not finished or expired.
- info:
    name: FastDOL Log Lookup
    type: http
  http:
    method: POST
    url: https://api.fastdol.com/v1/usage/lookup
  docs: 'Increment lookups_used. Soft cap — return 200 with `over_quota`

    flag rather than 429, so the page render that triggered this isn''t

    interrupted. The UI uses the flag to render an upgrade banner.'
- info:
    name: FastDOL Claim PDF Report
    type: http
  http:
    method: POST
    url: https://api.fastdol.com/v1/usage/pdf-report-claim
  docs: 'Hard-cap claim for one PDF report. Returns 429 if the customer is

    at quota. Caller (the report page) refuses to render on 429 and

    shows an upgrade prompt instead.


    Atomic check-and-increment via SELECT ... FOR UPDATE inside a

    transaction. If the limit is 0 (Free tier), the customer never gets

    past the comparison — no slot is consumed and the upgrade response

    is consistent.'
- info:
    name: FastDOL GET Usage
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/usage
  docs: 'Return all three usage counters + their limits for the dashboard.


    Read-only convenience endpoint so the account page doesn''t have to

    join across customers + api_keys + the live api_usage row count.'
- info:
    name: FastDOL Health
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/health
  docs: 'Public health endpoint — returns ok/unhealthy only.


    Used by UptimeRobot and status-page builders. Intentionally minimal

    to avoid leaking internal operational detail. Only DB + data-loaded

    checks trigger 503 — pipeline freshness is not customer-facing and

    is exposed on /v1/health/detail for admin monitoring.'
- info:
    name: FastDOL Health
    type: http
  http:
    method: HEAD
    url: https://api.fastdol.com/v1/health
  docs: 'Public health endpoint — returns ok/unhealthy only.


    Used by UptimeRobot and status-page builders. Intentionally minimal

    to avoid leaking internal operational detail. Only DB + data-loaded

    checks trigger 503 — pipeline freshness is not customer-facing and

    is exposed on /v1/health/detail for admin monitoring.'
- info:
    name: FastDOL Health Detail
    type: http
  http:
    method: GET
    url: https://api.fastdol.com/v1/health/detail
  docs: 'Admin-only detailed health — requires admin JWT.


    Full diagnostics: DB, pipeline recency, pipeline status, profile

    count, data age, failing checks. Behind auth so customers can''t see

    internal operational state or fingerprint pipeline schedules.'
bundled: true