openapi: 3.0.2 info: title: FastDOL API version: '1.0' description: FastDOL aggregates federal workplace enforcement records on 2.3M US employers across 16 federal agencies — OSHA, WHD, MSHA, EPA ECHO, NLRB, FMCSA, OFLC, BLS SOII, SAM.gov, CMS, USAspending, CPSC, NHTSA, SEC, and the UVA Corporate Prosecution Registry. Query inspections, violations, penalties, wage theft cases, severe injury reports, recalls, and federal contract awards via a single, normalized JSON API. contact: name: FastDOL Support email: ben@fastdol.com url: https://fastdol.com/enterprise termsOfService: https://fastdol.com/terms paths: /v1/employers: get: summary: FastDOL Search Employers description: '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.' operationId: search_employers_v1_employers_get parameters: - name: name in: query required: false schema: anyOf: - type: string maxLength: 200 - type: 'null' description: Fuzzy employer name search title: Name description: Fuzzy employer name search example: Acme Construction Inc - name: ein in: query required: false schema: anyOf: - type: string maxLength: 12 - type: 'null' description: Exact EIN match title: Ein description: Exact EIN match example: 12-3456789 - name: state in: query required: false schema: anyOf: - type: string maxLength: 2 - type: 'null' description: State code filter (e.g., CA) title: State description: State code filter (e.g., CA) example: CA - name: zip in: query required: false schema: anyOf: - type: string maxLength: 10 - type: 'null' description: 5-digit zip code filter title: Zip description: 5-digit zip code filter example: '94105' - name: naics in: query required: false schema: anyOf: - type: string maxLength: 6 - type: 'null' description: 4-digit NAICS prefix filter title: Naics description: 4-digit NAICS prefix filter example: '2362' - name: parent_only in: query required: false schema: type: boolean description: Only return employers with a parent_name (known parent companies) default: false title: Parent Only description: Only return employers with a parent_name (known parent companies) example: false - name: parent_name in: query required: false schema: anyOf: - type: string maxLength: 200 - type: 'null' description: Filter to locations under a specific parent company (exact match) title: Parent Name description: Filter to locations under a specific parent company (exact match) example: walmart-inc - name: has_fatalities in: query required: false schema: type: boolean description: Filter to locations with fatality investigations default: false title: Has Fatalities description: Filter to locations with fatality investigations example: false - name: svep in: query required: false schema: type: boolean description: Filter to locations on the Severe Violator Enforcement Program default: false title: Svep description: Filter to locations on the Severe Violator Enforcement Program example: false - name: sort_by in: query required: false schema: anyOf: - type: string maxLength: 20 - type: 'null' description: 'Sort results by: risk_score (default), violations, penalties, inspections, fatalities' title: Sort By description: 'Sort results by: risk_score (default), violations, penalties, inspections, fatalities' example: string - name: sort_dir in: query required: false schema: anyOf: - type: string maxLength: 4 - type: 'null' description: 'Sort direction: desc (default) or asc' title: Sort Dir description: 'Sort direction: desc (default) or asc' example: string - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 20 title: Limit example: 20 - name: offset in: query required: false schema: type: integer minimum: 0 default: 0 title: Offset example: 0 - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string responses: '200': description: Successful Response content: application/json: schema: {} examples: SearchEmployersV1EmployersGet200Example: summary: Default SearchEmployersV1EmployersGet 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: SearchEmployersV1EmployersGet422Example: summary: Default SearchEmployersV1EmployersGet 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/employers/parent: get: summary: FastDOL GET Parent Company description: '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.' operationId: get_parent_company_v1_employers_parent_get parameters: - name: name in: query required: true schema: type: string description: Parent company name (e.g., 'Amazon', 'Walmart') title: Name description: Parent company name (e.g., 'Amazon', 'Walmart') example: Acme Construction Inc - name: state in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter locations by state title: State description: Filter locations by state example: CA - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 20 title: Limit example: 20 - name: offset in: query required: false schema: type: integer minimum: 0 default: 0 title: Offset example: 0 - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string responses: '200': description: Successful Response content: application/json: schema: {} examples: GetParentCompanyV1EmployersParentGet200Example: summary: Default GetParentCompanyV1EmployersParentGet 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: GetParentCompanyV1EmployersParentGet422Example: summary: Default GetParentCompanyV1EmployersParentGet 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/employers/ein/{ein}: get: summary: FastDOL GET Employer by EIN description: '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'').' operationId: get_employer_by_ein_v1_employers_ein__ein__get parameters: - name: ein in: path required: true schema: type: string title: Ein example: 12-3456789 - name: state in: query required: false schema: anyOf: - type: string - type: 'null' description: State code filter title: State description: State code filter example: CA - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 20 title: Limit example: 20 - name: offset in: query required: false schema: type: integer minimum: 0 default: 0 title: Offset example: 0 - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string responses: '200': description: Successful Response content: application/json: schema: {} examples: GetEmployerByEinV1EmployersEinEinGet200Example: summary: Default GetEmployerByEinV1EmployersEinEinGet 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: GetEmployerByEinV1EmployersEinEinGet422Example: summary: Default GetEmployerByEinV1EmployersEinEinGet 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/employers/{employer_id}: get: summary: FastDOL GET Employer description: Direct lookup by employer_id UUID. operationId: get_employer_v1_employers__employer_id__get parameters: - name: employer_id in: path required: true schema: type: string title: Employer Id example: emp_8a3b9c2d1e4f - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string responses: '200': description: Successful Response content: application/json: schema: {} examples: GetEmployerV1EmployersEmployerIdGet200Example: summary: Default GetEmployerV1EmployersEmployerIdGet 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: GetEmployerV1EmployersEmployerIdGet422Example: summary: Default GetEmployerV1EmployersEmployerIdGet 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/employers/{employer_id}/inspections: get: summary: FastDOL GET Inspections description: '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).' operationId: get_inspections_v1_employers__employer_id__inspections_get parameters: - name: employer_id in: path required: true schema: type: string title: Employer Id example: emp_8a3b9c2d1e4f - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 20 title: Limit example: 20 - name: offset in: query required: false schema: type: integer minimum: 0 default: 0 title: Offset example: 0 - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string responses: '200': description: Successful Response content: application/json: schema: {} examples: GetInspectionsV1EmployersEmployerIdInspectionsGet200Example: summary: Default GetInspectionsV1EmployersEmployerIdInspectionsGet 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: GetInspectionsV1EmployersEmployerIdInspectionsGet422Example: summary: Default GetInspectionsV1EmployersEmployerIdInspectionsGet 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/employers/{employer_id}/severe-injuries: get: summary: FastDOL GET Severe Injuries description: '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.' operationId: get_severe_injuries_v1_employers__employer_id__severe_injuries_get parameters: - name: employer_id in: path required: true schema: type: string title: Employer Id example: emp_8a3b9c2d1e4f - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 20 title: Limit example: 20 - name: offset in: query required: false schema: type: integer minimum: 0 default: 0 title: Offset example: 0 - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string responses: '200': description: Successful Response content: application/json: schema: {} examples: GetSevereInjuriesV1EmployersEmployerIdSevereInjuriesGet200Example: summary: Default GetSevereInjuriesV1EmployersEmployerIdSevereInjuriesGet 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: GetSevereInjuriesV1EmployersEmployerIdSevereInjuriesGet422Example: summary: Default GetSevereInjuriesV1EmployersEmployerIdSevereInjuriesGet 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/employers/{employer_id}/whd-cases: get: summary: FastDOL GET WHD Cases description: '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.' operationId: get_whd_cases_v1_employers__employer_id__whd_cases_get parameters: - name: employer_id in: path required: true schema: type: string title: Employer Id example: emp_8a3b9c2d1e4f - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 20 title: Limit example: 20 - name: offset in: query required: false schema: type: integer minimum: 0 default: 0 title: Offset example: 0 - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string responses: '200': description: Successful Response content: application/json: schema: {} examples: GetWhdCasesV1EmployersEmployerIdWhdCasesGet200Example: summary: Default GetWhdCasesV1EmployersEmployerIdWhdCasesGet 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: GetWhdCasesV1EmployersEmployerIdWhdCasesGet422Example: summary: Default GetWhdCasesV1EmployersEmployerIdWhdCasesGet 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/employers/{employer_id}/osha-accidents: get: summary: FastDOL GET OSHA Accidents description: '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 as inspections / SIR. Newest event first.' operationId: get_osha_accidents_v1_employers__employer_id__osha_accidents_get parameters: - name: employer_id in: path required: true schema: type: string title: Employer Id example: emp_8a3b9c2d1e4f - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 20 title: Limit example: 20 - name: offset in: query required: false schema: type: integer minimum: 0 default: 0 title: Offset example: 0 - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string responses: '200': description: Successful Response content: application/json: schema: {} examples: GetOshaAccidentsV1EmployersEmployerIdOshaAccidentsGet200Example: summary: Default GetOshaAccidentsV1EmployersEmployerIdOshaAccidentsGet 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: GetOshaAccidentsV1EmployersEmployerIdOshaAccidentsGet422Example: summary: Default GetOshaAccidentsV1EmployersEmployerIdOshaAccidentsGet 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/employers/{employer_id}/sec-enforcement: get: summary: FastDOL GET SEC Enforcement description: '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.' operationId: get_sec_enforcement_v1_employers__employer_id__sec_enforcement_get parameters: - name: employer_id in: path required: true schema: type: string title: Employer Id example: emp_8a3b9c2d1e4f - name: limit in: query required: false schema: type: integer maximum: 200 minimum: 1 default: 50 title: Limit example: 20 - name: offset in: query required: false schema: type: integer minimum: 0 default: 0 title: Offset example: 0 - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string responses: '200': description: Successful Response content: application/json: schema: {} examples: GetSecEnforcementV1EmployersEmployerIdSecEnforcementGet200Example: summary: Default GetSecEnforcementV1EmployersEmployerIdSecEnforcementGet 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: GetSecEnforcementV1EmployersEmployerIdSecEnforcementGet422Example: summary: Default GetSecEnforcementV1EmployersEmployerIdSecEnforcementGet 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/employers/{employer_id}/peers: get: summary: FastDOL GET Peers description: '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 the human reader and stronger anchor-text diversity in the per-page link set. Metered same as get_inspections. The endpoint is heavy enough (two indexed lookups + N projections) that an unmetered version would invite scraping.' operationId: get_peers_v1_employers__employer_id__peers_get parameters: - name: employer_id in: path required: true schema: type: string title: Employer Id example: emp_8a3b9c2d1e4f - name: limit in: query required: false schema: type: integer maximum: 20 minimum: 1 default: 10 title: Limit example: 20 - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string responses: '200': description: Successful Response content: application/json: schema: {} examples: GetPeersV1EmployersEmployerIdPeersGet200Example: summary: Default GetPeersV1EmployersEmployerIdPeersGet 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: GetPeersV1EmployersEmployerIdPeersGet422Example: summary: Default GetPeersV1EmployersEmployerIdPeersGet 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/inspections/{activity_nr}/violations: get: summary: FastDOL GET Violations description: 'Get violation detail for a specific inspection. Metered: one lookup per call. See get_inspections for rationale.' operationId: get_violations_v1_inspections__activity_nr__violations_get parameters: - name: activity_nr in: path required: true schema: type: string title: Activity Nr example: '316254783' - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string responses: '200': description: Successful Response content: application/json: schema: {} examples: GetViolationsV1InspectionsActivityNrViolationsGet200Example: summary: Default GetViolationsV1InspectionsActivityNrViolationsGet 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: GetViolationsV1InspectionsActivityNrViolationsGet422Example: summary: Default GetViolationsV1InspectionsActivityNrViolationsGet 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/employers/batch: post: summary: FastDOL Batch Lookup description: '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.' operationId: batch_lookup_v1_employers_batch_post parameters: - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchLookupRequest' examples: BatchLookupV1EmployersBatchPostRequestExample: summary: Default BatchLookupV1EmployersBatchPost request x-microcks-default: true value: lookups: - name: Acme Construction Inc ein: 12-3456789 employer_id: emp_8a3b9c2d1e4f state: CA zip: '94105' city: string responses: '200': description: Successful Response content: application/json: schema: {} examples: BatchLookupV1EmployersBatchPost200Example: summary: Default BatchLookupV1EmployersBatchPost 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: BatchLookupV1EmployersBatchPost422Example: summary: Default BatchLookupV1EmployersBatchPost 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/employers/{employer_id}/risk-history: get: summary: FastDOL GET Risk History description: Risk tier history for an employer over time. Shows nightly snapshots. operationId: get_risk_history_v1_employers__employer_id__risk_history_get parameters: - name: employer_id in: path required: true schema: type: string title: Employer Id example: emp_8a3b9c2d1e4f - name: limit in: query required: false schema: type: integer maximum: 365 minimum: 1 default: 90 title: Limit example: 20 - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string responses: '200': description: Successful Response content: application/json: schema: {} examples: GetRiskHistoryV1EmployersEmployerIdRiskHistoryGet200Example: summary: Default GetRiskHistoryV1EmployersEmployerIdRiskHistoryGet 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: GetRiskHistoryV1EmployersEmployerIdRiskHistoryGet422Example: summary: Default GetRiskHistoryV1EmployersEmployerIdRiskHistoryGet 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/employers/{employer_id}/feedback: post: summary: FastDOL Submit Feedback description: Submit feedback about an employer match. Not metered. operationId: submit_feedback_v1_employers__employer_id__feedback_post parameters: - name: employer_id in: path required: true schema: type: string title: Employer Id example: emp_8a3b9c2d1e4f - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FeedbackRequest' examples: SubmitFeedbackV1EmployersEmployerIdFeedbackPostRequestExample: summary: Default SubmitFeedbackV1EmployersEmployerIdFeedbackPost request x-microcks-default: true value: type: string description: string contact_email: analyst@example.com responses: '200': description: Successful Response content: application/json: schema: {} examples: SubmitFeedbackV1EmployersEmployerIdFeedbackPost200Example: summary: Default SubmitFeedbackV1EmployersEmployerIdFeedbackPost 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: SubmitFeedbackV1EmployersEmployerIdFeedbackPost422Example: summary: Default SubmitFeedbackV1EmployersEmployerIdFeedbackPost 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/industries/naics-codes: get: summary: FastDOL List NAICS Codes description: List all 4-digit NAICS codes with employer counts. operationId: list_naics_codes_v1_industries_naics_codes_get parameters: - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string responses: '200': description: Successful Response content: application/json: schema: {} examples: ListNaicsCodesV1IndustriesNaicsCodesGet200Example: summary: Default ListNaicsCodesV1IndustriesNaicsCodesGet 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: ListNaicsCodesV1IndustriesNaicsCodesGet422Example: summary: Default ListNaicsCodesV1IndustriesNaicsCodesGet 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/industries/{naics4}: get: summary: FastDOL GET Industry description: Industry-level risk benchmarks for a 4-digit NAICS code. operationId: get_industry_v1_industries__naics4__get parameters: - name: naics4 in: path required: true schema: type: string title: Naics4 example: '2362' - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string responses: '200': description: Successful Response content: application/json: schema: {} examples: GetIndustryV1IndustriesNaics4Get200Example: summary: Default GetIndustryV1IndustriesNaics4Get 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: GetIndustryV1IndustriesNaics4Get422Example: summary: Default GetIndustryV1IndustriesNaics4Get 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/sitemap/employers: get: summary: FastDOL Sitemap Employers description: '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 knows how many pages to request — the count reflects the indexable_only filter when set.' operationId: sitemap_employers_v1_sitemap_employers_get parameters: - name: limit in: query required: false schema: type: integer maximum: 50000 minimum: 1 default: 50000 title: Limit example: 20 - name: offset in: query required: false schema: type: integer minimum: 0 default: 0 title: Offset example: 0 - name: indexable_only in: query required: false schema: type: boolean 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. default: false title: Indexable Only 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. example: false - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string responses: '200': description: Successful Response content: application/json: schema: {} examples: SitemapEmployersV1SitemapEmployersGet200Example: summary: Default SitemapEmployersV1SitemapEmployersGet 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: SitemapEmployersV1SitemapEmployersGet422Example: summary: Default SitemapEmployersV1SitemapEmployersGet 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /auth/signup: post: summary: FastDOL Signup description: Create account with email + password. Sends verification email. operationId: signup_auth_signup_post requestBody: content: application/json: schema: $ref: '#/components/schemas/SignupRequest' examples: SignupAuthSignupPostRequestExample: summary: Default SignupAuthSignupPost request x-microcks-default: true value: email: analyst@example.com password: CorrectHorseBatteryStaple1! company_name: string required: true responses: '200': description: Successful Response content: application/json: schema: {} examples: SignupAuthSignupPost200Example: summary: Default SignupAuthSignupPost 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: SignupAuthSignupPost422Example: summary: Default SignupAuthSignupPost 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /auth/verify: post: summary: FastDOL Verify Email description: "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\nThe 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 (was: auto-issued an API key + set the\naccess_token cookie on the first POST): now the endpoint only\nflips customers.email_verified to TRUE. The user must explicitly\nlog in afterwards and create their first API key from the\n/account dashboard. This closes the email-link-prefetch attack\nwhere a corporate gateway, AV scanner, or IT admin reading a\nforwarded message could auto-claim the account." operationId: verify_email_auth_verify_post requestBody: content: application/json: schema: $ref: '#/components/schemas/VerifyEmailRequest' examples: VerifyEmailAuthVerifyPostRequestExample: summary: Default VerifyEmailAuthVerifyPost request x-microcks-default: true value: token: tok_9d2e1c4b7a6f3e5d required: true responses: '200': description: Successful Response content: application/json: schema: {} examples: VerifyEmailAuthVerifyPost200Example: summary: Default VerifyEmailAuthVerifyPost 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: VerifyEmailAuthVerifyPost422Example: summary: Default VerifyEmailAuthVerifyPost 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /auth/login: post: summary: FastDOL Login description: Login with email + password. Returns JWT as HttpOnly cookie. operationId: login_auth_login_post requestBody: content: application/json: schema: $ref: '#/components/schemas/LoginRequest' examples: LoginAuthLoginPostRequestExample: summary: Default LoginAuthLoginPost request x-microcks-default: true value: email: analyst@example.com password: CorrectHorseBatteryStaple1! required: true responses: '200': description: Successful Response content: application/json: schema: {} examples: LoginAuthLoginPost200Example: summary: Default LoginAuthLoginPost 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: LoginAuthLoginPost422Example: summary: Default LoginAuthLoginPost 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /auth/logout: post: summary: FastDOL Logout description: '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.' operationId: logout_auth_logout_post responses: '200': description: Successful Response content: application/json: schema: {} examples: LogoutAuthLogoutPost200Example: summary: Default LogoutAuthLogoutPost 200 response x-microcks-default: true value: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /auth/me: get: summary: FastDOL GET Me description: '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.' operationId: get_me_auth_me_get responses: '200': description: Successful Response content: application/json: schema: {} examples: GetMeAuthMeGet200Example: summary: Default GetMeAuthMeGet 200 response x-microcks-default: true value: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /auth/forgot-password: post: summary: FastDOL Forgot Password description: '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.' operationId: forgot_password_auth_forgot_password_post requestBody: content: application/json: schema: $ref: '#/components/schemas/ForgotPasswordRequest' examples: ForgotPasswordAuthForgotPasswordPostRequestExample: summary: Default ForgotPasswordAuthForgotPasswordPost request x-microcks-default: true value: email: analyst@example.com required: true responses: '200': description: Successful Response content: application/json: schema: {} examples: ForgotPasswordAuthForgotPasswordPost200Example: summary: Default ForgotPasswordAuthForgotPasswordPost 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: ForgotPasswordAuthForgotPasswordPost422Example: summary: Default ForgotPasswordAuthForgotPasswordPost 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /auth/reset-password: post: summary: FastDOL Reset Password description: Reset password using token from email. operationId: reset_password_auth_reset_password_post requestBody: content: application/json: schema: $ref: '#/components/schemas/ResetPasswordRequest' examples: ResetPasswordAuthResetPasswordPostRequestExample: summary: Default ResetPasswordAuthResetPasswordPost request x-microcks-default: true value: token: tok_9d2e1c4b7a6f3e5d new_password: CorrectHorseBatteryStaple1! required: true responses: '200': description: Successful Response content: application/json: schema: {} examples: ResetPasswordAuthResetPasswordPost200Example: summary: Default ResetPasswordAuthResetPasswordPost 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: ResetPasswordAuthResetPasswordPost422Example: summary: Default ResetPasswordAuthResetPasswordPost 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /dashboard/plan: get: summary: FastDOL GET Plan description: Return current plan info including pending cancellation status. operationId: get_plan_dashboard_plan_get responses: '200': description: Successful Response content: application/json: schema: {} examples: GetPlanDashboardPlanGet200Example: summary: Default GetPlanDashboardPlanGet 200 response x-microcks-default: true value: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /dashboard/keys: get: summary: FastDOL List Keys description: List all API keys for the current customer. operationId: list_keys_dashboard_keys_get responses: '200': description: Successful Response content: application/json: schema: {} examples: ListKeysDashboardKeysGet200Example: summary: Default ListKeysDashboardKeysGet 200 response x-microcks-default: true value: string x-microcks-operation: delay: 0 dispatcher: FALLBACK post: summary: FastDOL Create Key description: Generate a new API key. Raw key shown ONCE in response. operationId: create_key_dashboard_keys_post requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateKeyRequest' examples: CreateKeyDashboardKeysPostRequestExample: summary: Default CreateKeyDashboardKeysPost request x-microcks-default: true value: label: string scopes: - string required: true responses: '200': description: Successful Response content: application/json: schema: {} examples: CreateKeyDashboardKeysPost200Example: summary: Default CreateKeyDashboardKeysPost 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: CreateKeyDashboardKeysPost422Example: summary: Default CreateKeyDashboardKeysPost 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /dashboard/keys/{key_id}/rotate: post: summary: FastDOL Rotate Key description: Rotate a key. Old key works for 48h, new key is immediately active. operationId: rotate_key_dashboard_keys__key_id__rotate_post parameters: - name: key_id in: path required: true schema: type: string title: Key Id example: key_5f8c3a2d1e4b responses: '200': description: Successful Response content: application/json: schema: {} examples: RotateKeyDashboardKeysKeyIdRotatePost200Example: summary: Default RotateKeyDashboardKeysKeyIdRotatePost 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: RotateKeyDashboardKeysKeyIdRotatePost422Example: summary: Default RotateKeyDashboardKeysKeyIdRotatePost 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /dashboard/keys/{key_id}: delete: summary: FastDOL Revoke Key description: Immediately revoke an API key. operationId: revoke_key_dashboard_keys__key_id__delete parameters: - name: key_id in: path required: true schema: type: string title: Key Id example: key_5f8c3a2d1e4b responses: '200': description: Successful Response content: application/json: schema: {} examples: RevokeKeyDashboardKeysKeyIdDelete200Example: summary: Default RevokeKeyDashboardKeysKeyIdDelete 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: RevokeKeyDashboardKeysKeyIdDelete422Example: summary: Default RevokeKeyDashboardKeysKeyIdDelete 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /dashboard/account: delete: summary: FastDOL Delete Account description: "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 batch_jobs — ON DELETE CASCADE\n - api_key_audit_log, api_usage — customer_id set to NULL (we keep the\n audit/usage trail; the PII linkage is severed)\n - audit_log — customer_id set to NULL (same rationale)\n\nNote: the customers table still carries a vestigial `stripe_customer_id`\ncolumn from when paid tiers were self-serve via Stripe. The column is\nnot selected here — Stripe was retired in the May 2026 redesign and\ncommercial accounts are now handled out-of-band. If we ever need the\nhistorical mapping back, it's still in the DB row; we just don't surface\nit from this delete flow." operationId: delete_account_dashboard_account_delete requestBody: content: application/json: schema: $ref: '#/components/schemas/DeleteAccountRequest' examples: DeleteAccountDashboardAccountDeleteRequestExample: summary: Default DeleteAccountDashboardAccountDelete request x-microcks-default: true value: password: CorrectHorseBatteryStaple1! confirm: string required: true responses: '200': description: Successful Response content: application/json: schema: {} examples: DeleteAccountDashboardAccountDelete200Example: summary: Default DeleteAccountDashboardAccountDelete 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: DeleteAccountDashboardAccountDelete422Example: summary: Default DeleteAccountDashboardAccountDelete 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /webhooks/stripe: post: summary: FastDOL Stripe Webhook Tombstone description: '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.' operationId: stripe_webhook_tombstone_webhooks_stripe_post responses: '200': description: Successful Response content: application/json: schema: {} examples: StripeWebhookTombstoneWebhooksStripePost200Example: summary: Default StripeWebhookTombstoneWebhooksStripePost 200 response x-microcks-default: true value: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/employers/upload-csv: post: summary: FastDOL Upload CSV description: "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,\n\ location_count, trend_signal" operationId: upload_csv_v1_employers_upload_csv_post parameters: - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/Body_upload_csv_v1_employers_upload_csv_post' responses: '200': description: Successful Response content: application/json: schema: {} examples: UploadCsvV1EmployersUploadCsvPost200Example: summary: Default UploadCsvV1EmployersUploadCsvPost 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: UploadCsvV1EmployersUploadCsvPost422Example: summary: Default UploadCsvV1EmployersUploadCsvPost 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/stats/state/{code}: get: summary: FastDOL State Stats description: "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 volume in this state\n - `top_contractors`: top 10 federal contractors by 5yr obligations (only\n populated once USAspending has landed; empty list otherwise)" operationId: state_stats_v1_stats_state__code__get parameters: - name: code in: path required: true schema: type: string title: Code example: CA responses: '200': description: Successful Response content: application/json: schema: {} examples: StateStatsV1StatsStateCodeGet200Example: summary: Default StateStatsV1StatsStateCodeGet 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: StateStatsV1StatsStateCodeGet422Example: summary: Default StateStatsV1StatsStateCodeGet 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/stats/industry/{naics}: get: summary: FastDOL Industry Stats description: '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").' operationId: industry_stats_v1_stats_industry__naics__get parameters: - name: naics in: path required: true schema: type: string title: Naics example: '2362' responses: '200': description: Successful Response content: application/json: schema: {} examples: IndustryStatsV1StatsIndustryNaicsGet200Example: summary: Default IndustryStatsV1StatsIndustryNaicsGet 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: IndustryStatsV1StatsIndustryNaicsGet422Example: summary: Default IndustryStatsV1StatsIndustryNaicsGet 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/stats/industries: get: summary: FastDOL Industries Index description: '3-digit NAICS subsectors that have any employer on file, with volumes. Powers the /industries landing page.' operationId: industries_index_v1_stats_industries_get responses: '200': description: Successful Response content: application/json: schema: {} examples: IndustriesIndexV1StatsIndustriesGet200Example: summary: Default IndustriesIndexV1StatsIndustriesGet 200 response x-microcks-default: true value: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/stats/nursing-home/{ccn}: get: summary: FastDOL Nursing Home Detail description: '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.' operationId: nursing_home_detail_v1_stats_nursing_home__ccn__get parameters: - name: ccn in: path required: true schema: type: string title: Ccn example: '055123' responses: '200': description: Successful Response content: application/json: schema: {} examples: NursingHomeDetailV1StatsNursingHomeCcnGet200Example: summary: Default NursingHomeDetailV1StatsNursingHomeCcnGet 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: NursingHomeDetailV1StatsNursingHomeCcnGet422Example: summary: Default NursingHomeDetailV1StatsNursingHomeCcnGet 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/stats/nursing-homes/{state_code}: get: summary: FastDOL Nursing Homes by State description: State-level nursing home aggregates + top/bottom facilities. operationId: nursing_homes_by_state_v1_stats_nursing_homes__state_code__get parameters: - name: state_code in: path required: true schema: type: string title: State Code example: CA responses: '200': description: Successful Response content: application/json: schema: {} examples: NursingHomesByStateV1StatsNursingHomesStateCodeGet200Example: summary: Default NursingHomesByStateV1StatsNursingHomesStateCodeGet 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: NursingHomesByStateV1StatsNursingHomesStateCodeGet422Example: summary: Default NursingHomesByStateV1StatsNursingHomesStateCodeGet 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/stats/nursing-homes: get: summary: FastDOL Nursing Homes Index description: '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.' operationId: nursing_homes_index_v1_stats_nursing_homes_get responses: '200': description: Successful Response content: application/json: schema: {} examples: NursingHomesIndexV1StatsNursingHomesGet200Example: summary: Default NursingHomesIndexV1StatsNursingHomesGet 200 response x-microcks-default: true value: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/stats/states: get: summary: FastDOL States Index description: List of all supported state codes + employer counts for the /states page. operationId: states_index_v1_stats_states_get responses: '200': description: Successful Response content: application/json: schema: {} examples: StatesIndexV1StatsStatesGet200Example: summary: Default StatesIndexV1StatsStatesGet 200 response x-microcks-default: true value: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/export: post: summary: FastDOL Create Export description: '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.' operationId: create_export_v1_export_post parameters: - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExportRequest' examples: CreateExportV1ExportPostRequestExample: summary: Default CreateExportV1ExportPost request x-microcks-default: true value: format: string filters: name: Acme Construction Inc ein: 12-3456789 state: CA states: string zip: '94105' naics: '2362' naics_codes: string parent_only: false parent_name: walmart-inc has_fatalities: false svep: false min_inspections: string min_violations: string min_penalties: string min_fatalities: string min_whd_cases: string min_whd_backwages: string max_rows: 1 sort_by: string sort_dir: string responses: '202': description: Successful Response content: application/json: schema: {} examples: CreateExportV1ExportPost202Example: summary: Default CreateExportV1ExportPost 202 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: CreateExportV1ExportPost422Example: summary: Default CreateExportV1ExportPost 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/export/{job_id}: get: summary: FastDOL GET Export description: 'Poll an export job. Returns status and — once finished — a download URL valid until the job expires (24h after creation).' operationId: get_export_v1_export__job_id__get parameters: - name: job_id in: path required: true schema: type: string title: Job Id example: job_2c5d7a93b1f0 - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string responses: '200': description: Successful Response content: application/json: schema: {} examples: GetExportV1ExportJobIdGet200Example: summary: Default GetExportV1ExportJobIdGet 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: GetExportV1ExportJobIdGet422Example: summary: Default GetExportV1ExportJobIdGet 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/export/{job_id}/download: get: summary: FastDOL Download Export description: Stream the generated export file. 404 if not finished or expired. operationId: download_export_v1_export__job_id__download_get parameters: - name: job_id in: path required: true schema: type: string title: Job Id example: job_2c5d7a93b1f0 - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key example: string responses: '200': description: Successful Response content: application/json: schema: {} examples: DownloadExportV1ExportJobIdDownloadGet200Example: summary: Default DownloadExportV1ExportJobIdDownloadGet 200 response x-microcks-default: true value: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' examples: DownloadExportV1ExportJobIdDownloadGet422Example: summary: Default DownloadExportV1ExportJobIdDownloadGet 422 response x-microcks-default: true value: detail: - loc: - string msg: string type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/usage/lookup: post: summary: FastDOL Log Lookup description: '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.' operationId: log_lookup_v1_usage_lookup_post responses: '200': description: Successful Response content: application/json: schema: {} examples: LogLookupV1UsageLookupPost200Example: summary: Default LogLookupV1UsageLookupPost 200 response x-microcks-default: true value: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/usage/pdf-report-claim: post: summary: FastDOL Claim PDF Report description: '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.' operationId: claim_pdf_report_v1_usage_pdf_report_claim_post responses: '200': description: Successful Response content: application/json: schema: {} examples: ClaimPdfReportV1UsagePdfReportClaimPost200Example: summary: Default ClaimPdfReportV1UsagePdfReportClaimPost 200 response x-microcks-default: true value: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/usage: get: summary: FastDOL GET Usage description: '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.' operationId: get_usage_v1_usage_get responses: '200': description: Successful Response content: application/json: schema: {} examples: GetUsageV1UsageGet200Example: summary: Default GetUsageV1UsageGet 200 response x-microcks-default: true value: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/health: get: summary: FastDOL Health description: '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.' operationId: health_v1_health_head responses: '200': description: Successful Response content: application/json: schema: {} examples: HealthV1HealthHead200Example: summary: Default HealthV1HealthHead 200 response x-microcks-default: true value: string x-microcks-operation: delay: 0 dispatcher: FALLBACK head: summary: FastDOL Health description: '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.' operationId: health_v1_health_head responses: '200': description: Successful Response content: application/json: schema: {} examples: HealthV1HealthHead200Example: summary: Default HealthV1HealthHead 200 response x-microcks-default: true value: string x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/health/detail: get: summary: FastDOL Health Detail description: '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.' operationId: health_detail_v1_health_detail_get responses: '200': description: Successful Response content: application/json: schema: {} examples: HealthDetailV1HealthDetailGet200Example: summary: Default HealthDetailV1HealthDetailGet 200 response x-microcks-default: true value: string x-microcks-operation: delay: 0 dispatcher: FALLBACK components: schemas: BatchLookupItem: properties: name: anyOf: - type: string - type: 'null' title: Name ein: anyOf: - type: string - type: 'null' title: Ein employer_id: anyOf: - type: string - type: 'null' title: Employer Id state: anyOf: - type: string - type: 'null' title: State zip: anyOf: - type: string - type: 'null' title: Zip city: anyOf: - type: string - type: 'null' title: City type: object title: BatchLookupItem BatchLookupRequest: properties: lookups: items: $ref: '#/components/schemas/BatchLookupItem' type: array title: Lookups type: object required: - lookups title: BatchLookupRequest Body_upload_csv_v1_employers_upload_csv_post: properties: file: type: string format: binary title: File description: CSV file with employer names and optional location fields example: string type: object required: - file title: Body_upload_csv_v1_employers_upload_csv_post CreateKeyRequest: properties: label: type: string title: Label default: default example: string scopes: items: type: string type: array title: Scopes default: - employer:read type: object title: CreateKeyRequest DeleteAccountRequest: properties: password: type: string title: Password example: CorrectHorseBatteryStaple1! confirm: type: string title: Confirm example: string type: object required: - password - confirm title: DeleteAccountRequest ExportFilters: properties: name: anyOf: - type: string maxLength: 200 - type: 'null' title: Name ein: anyOf: - type: string maxLength: 20 - type: 'null' title: Ein state: anyOf: - type: string maxLength: 2 - type: 'null' title: State states: anyOf: - items: type: string type: array maxItems: 60 - type: 'null' title: States zip: anyOf: - type: string maxLength: 5 - type: 'null' title: Zip naics: anyOf: - type: string maxLength: 6 - type: 'null' title: Naics description: Single NAICS prefix, 2-6 digits naics_codes: anyOf: - items: type: string type: array maxItems: 50 - type: 'null' title: Naics Codes description: Multiple NAICS prefixes (OR) parent_only: type: boolean title: Parent Only default: false example: false parent_name: anyOf: - type: string maxLength: 200 - type: 'null' title: Parent Name has_fatalities: type: boolean title: Has Fatalities default: false example: false svep: type: boolean title: Svep default: false example: false min_inspections: anyOf: - type: integer minimum: 0.0 - type: 'null' title: Min Inspections min_violations: anyOf: - type: integer minimum: 0.0 - type: 'null' title: Min Violations min_penalties: anyOf: - type: number minimum: 0.0 - type: 'null' title: Min Penalties min_fatalities: anyOf: - type: integer minimum: 0.0 - type: 'null' title: Min Fatalities min_whd_cases: anyOf: - type: integer minimum: 0.0 - type: 'null' title: Min Whd Cases min_whd_backwages: anyOf: - type: number minimum: 0.0 - type: 'null' title: Min Whd Backwages type: object title: ExportFilters description: 'Filter surface for bulk exports — richer than the interactive search endpoint because enterprise analysts need structured queries (e.g. "top 50K employers by fatality rate with OSHA penalties > $100K in construction NAICS").' ExportRequest: properties: format: type: string pattern: ^(csv|json)$ title: Format default: csv example: string filters: $ref: '#/components/schemas/ExportFilters' max_rows: type: integer maximum: 100000.0 minimum: 1.0 title: Max Rows default: 50000 example: 1 sort_by: anyOf: - type: string - type: 'null' title: Sort By description: 'One of: contracts_value, employer_id, fatalities, inspections, penalties, risk_score, violations, whd_backwages, whd_cases' sort_dir: type: string pattern: ^(asc|desc)$ title: Sort Dir default: desc example: string type: object title: ExportRequest FeedbackRequest: properties: type: type: string title: Type example: string description: anyOf: - type: string - type: 'null' title: Description contact_email: anyOf: - type: string - type: 'null' title: Contact Email type: object required: - type title: FeedbackRequest ForgotPasswordRequest: properties: email: type: string format: email title: Email example: analyst@example.com type: object required: - email title: ForgotPasswordRequest HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError LoginRequest: properties: email: type: string format: email title: Email example: analyst@example.com password: type: string title: Password example: CorrectHorseBatteryStaple1! type: object required: - email - password title: LoginRequest ResetPasswordRequest: properties: token: type: string title: Token example: tok_9d2e1c4b7a6f3e5d new_password: type: string title: New Password example: CorrectHorseBatteryStaple1! type: object required: - token - new_password title: ResetPasswordRequest SignupRequest: properties: email: type: string format: email title: Email example: analyst@example.com password: type: string title: Password example: CorrectHorseBatteryStaple1! company_name: anyOf: - type: string - type: 'null' title: Company Name type: object required: - email - password title: SignupRequest ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message example: string type: type: string title: Error Type example: string type: object required: - loc - msg - type title: ValidationError VerifyEmailRequest: properties: token: type: string title: Token example: tok_9d2e1c4b7a6f3e5d type: object required: - token title: VerifyEmailRequest servers: - url: https://api.fastdol.com description: FastDOL production API