{
  "openapi": "3.1.0",
  "info": {
    "title": "AlphaLoops FMCSA Carrier Data API",
    "version": "1.0.0",
    "description": "Fleet intelligence API for looking up FMCSA-registered carriers by DOT number, MC number, or company name. Access carrier profiles with 200+ fields, safety data, authority history, fleet equipment, inspections, crashes, news, and decision-maker contacts.\n\nBase URL: https://api.runalphaloops.com\n\nAPI access is available exclusively on the Enterprise plan. Contact sales at https://runalphaloops.com/contact to get your API key.",
    "contact": {
      "name": "AlphaLoops",
      "url": "https://runalphaloops.com/contact",
      "email": "hello@runalphaloop.com"
    }
  },
  "servers": [
    {
      "url": "https://api.runalphaloops.com",
      "description": "Production"
    }
  ],
  "security": [
    { "bearerAuth": [] }
  ],
  "paths": {
    "/v1/carriers/{dot_number}": {
      "get": {
        "operationId": "getCarrierByDot",
        "summary": "Look up a carrier by DOT number",
        "description": "Returns the full carrier profile with 200+ fields including identity, authority, safety, fleet, technology stack, and contacts. Use the fields parameter to project only the fields you need.",
        "parameters": [
          {
            "name": "dot_number",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "The carrier's USDOT number"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Comma-separated list of fields to return (e.g. \"legal_name,power_units,latitude,longitude\"). Omit to return all fields."
          }
        ],
        "responses": {
          "200": {
            "description": "Full carrier profile",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CarrierProfile" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/carriers/mc/{mc_number}": {
      "get": {
        "operationId": "getCarrierByMc",
        "summary": "Look up a carrier by MC/MX docket number",
        "description": "Returns the full carrier profile (same fields as the DOT lookup). Supports the same ?fields= projection parameter.",
        "parameters": [
          {
            "name": "mc_number",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "The carrier's MC or MX docket number"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Comma-separated list of fields to return. Omit to return all fields."
          }
        ],
        "responses": {
          "200": {
            "description": "Full carrier profile",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CarrierProfile" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/carriers/search": {
      "get": {
        "operationId": "searchCarriers",
        "summary": "Match a company to a carrier by name",
        "description": "Match a company to a carrier by name, domain, state, and city. Returns ranked results with a confidence score. At minimum, company_name is required.",
        "parameters": [
          {
            "name": "company_name",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Company name to match against (fuzzy matching)"
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Company website domain (e.g. \"swifttrans.com\") — improves match accuracy"
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "State abbreviation (e.g. \"TX\", \"CA\")"
          },
          {
            "name": "city",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "City name (e.g. \"Phoenix\", \"Dallas\")"
          },
          { "$ref": "#/components/parameters/page" },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 10, "maximum": 50 },
            "description": "Results per page (default: 10, max: 50)"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated search results with confidence scores",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CarrierSearchResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/carriers/{dot_number}/authority": {
      "get": {
        "operationId": "getCarrierAuthority",
        "summary": "Get carrier operating authority history",
        "description": "Returns all authority actions including grants, revocations, and reinstatements.",
        "parameters": [
          { "$ref": "#/components/parameters/dotNumber" },
          { "$ref": "#/components/parameters/limit" },
          { "$ref": "#/components/parameters/offset" }
        ],
        "responses": {
          "200": {
            "description": "Authority history records",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AuthorityResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/carriers/{dot_number}/trucks": {
      "get": {
        "operationId": "getCarrierTrucks",
        "summary": "Get carrier truck (power unit) fleet",
        "description": "Returns the carrier's registered truck fleet. Includes VIN, make, model, engine specs, weight, and manufacturing details.",
        "parameters": [
          { "$ref": "#/components/parameters/dotNumber" },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 50, "maximum": 200 },
            "description": "Results per page (default: 50, max: 200)"
          },
          { "$ref": "#/components/parameters/offset" }
        ],
        "responses": {
          "200": {
            "description": "Paginated truck fleet",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TrucksResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/carriers/{dot_number}/trailers": {
      "get": {
        "operationId": "getCarrierTrailers",
        "summary": "Get carrier trailer fleet",
        "description": "Returns the carrier's registered trailer fleet. Includes VIN, manufacturer, type, and reefer status.",
        "parameters": [
          { "$ref": "#/components/parameters/dotNumber" },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 50, "maximum": 200 },
            "description": "Results per page (default: 50, max: 200)"
          },
          { "$ref": "#/components/parameters/offset" }
        ],
        "responses": {
          "200": {
            "description": "Paginated trailer fleet",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TrailersResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/carriers/{dot_number}/inspections": {
      "get": {
        "operationId": "getCarrierInspections",
        "summary": "Get carrier inspection history",
        "description": "Returns roadside inspection history with metadata and out-of-service counts. Use /v1/inspections/{inspection_id}/violations to get violation details for a specific inspection.",
        "parameters": [
          { "$ref": "#/components/parameters/dotNumber" },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 50, "maximum": 200 },
            "description": "Results per page (default: 50, max: 200)"
          },
          { "$ref": "#/components/parameters/offset" }
        ],
        "responses": {
          "200": {
            "description": "Paginated inspection records",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/InspectionsResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/inspections/{inspection_id}/violations": {
      "get": {
        "operationId": "getInspectionViolations",
        "summary": "Get violations for a specific inspection",
        "description": "Retrieve all violations from a specific roadside inspection. Use the inspection report number returned from the Inspections endpoint.",
        "parameters": [
          {
            "name": "inspection_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "The inspection report number"
          },
          { "$ref": "#/components/parameters/page" },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 25, "maximum": 100 },
            "description": "Results per page (default: 25, max: 100)"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated violation records",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ViolationsResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/carriers/{dot_number}/crashes": {
      "get": {
        "operationId": "getCarrierCrashes",
        "summary": "Get carrier crash history",
        "description": "Returns reported crash history with details, severity, and contributing factors.",
        "parameters": [
          { "$ref": "#/components/parameters/dotNumber" },
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "format": "date" },
            "description": "Filter from date (ISO 8601, e.g. \"2024-01-01\")"
          },
          {
            "name": "end_date",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "format": "date" },
            "description": "Filter to date (ISO 8601, e.g. \"2024-12-31\")"
          },
          {
            "name": "severity",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["FATAL", "INJURY", "TOW", "PROPERTY_DAMAGE"] },
            "description": "Filter by severity"
          },
          { "$ref": "#/components/parameters/page" },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 25, "maximum": 100 },
            "description": "Results per page (default: 25, max: 100)"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated crash records",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CrashesResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/carriers/{dot_number}/news": {
      "get": {
        "operationId": "getCarrierNews",
        "summary": "Get carrier news and press mentions",
        "description": "Returns recent news articles and press mentions related to the carrier.",
        "parameters": [
          { "$ref": "#/components/parameters/dotNumber" },
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "format": "date" },
            "description": "Filter from date (ISO 8601)"
          },
          {
            "name": "end_date",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "format": "date" },
            "description": "Filter to date (ISO 8601)"
          },
          { "$ref": "#/components/parameters/page" },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 25, "maximum": 100 },
            "description": "Results per page (default: 25, max: 100)"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated news articles",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/NewsResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/contacts/search": {
      "get": {
        "operationId": "searchContacts",
        "summary": "Find people at a carrier company",
        "description": "Returns professional profiles including name, title, seniority, social profiles, and industry. Use dot_number or company_name to search. Note: This endpoint may return HTTP 202 with a Retry-After header if contacts are still being fetched — retry after the specified delay.",
        "parameters": [
          {
            "name": "dot_number",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "The carrier's USDOT number"
          },
          {
            "name": "company_name",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Company name to search (required if dot_number not provided)"
          },
          {
            "name": "job_title",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Filter by job title keyword (e.g. \"safety\", \"operations\")"
          },
          {
            "name": "job_title_levels",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["vp", "director", "manager", "c_suite"] },
            "description": "Filter by seniority level"
          },
          { "$ref": "#/components/parameters/page" },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 25, "maximum": 100 },
            "description": "Results per page (default: 25, max: 100)"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated contact results",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ContactSearchResponse" }
              }
            }
          },
          "202": {
            "description": "Contacts are being fetched asynchronously. Retry after the delay specified in the Retry-After header.",
            "headers": {
              "Retry-After": {
                "schema": { "type": "integer" },
                "description": "Seconds to wait before retrying"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "pending" },
                    "dot_number": { "type": "string" },
                    "message": { "type": "string" },
                    "retry_after": { "type": "integer" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/contacts/{contact_id}/enrich": {
      "get": {
        "operationId": "enrichContact",
        "summary": "Enrich a contact profile",
        "description": "Returns verified emails, phone numbers, skills, full work history, education, and social profiles. Consumes 1 enrichment credit per new lookup (cached results are free). Returns HTTP 402 when credits are exhausted.",
        "parameters": [
          {
            "name": "contact_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "The contact ID returned from /v1/contacts/search"
          }
        ],
        "responses": {
          "200": {
            "description": "Enriched contact profile",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/EnrichedContact" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": {
            "description": "Enrichment credits exhausted",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key provided by AlphaLoops. Include as: Authorization: Bearer YOUR_API_KEY"
      }
    },
    "parameters": {
      "dotNumber": {
        "name": "dot_number",
        "in": "path",
        "required": true,
        "schema": { "type": "string" },
        "description": "The carrier's USDOT number"
      },
      "page": {
        "name": "page",
        "in": "query",
        "required": false,
        "schema": { "type": "integer", "default": 1 },
        "description": "Page number (default: 1)"
      },
      "limit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "schema": { "type": "integer", "default": 50 },
        "description": "Results per page (default: 50)"
      },
      "offset": {
        "name": "offset",
        "in": "query",
        "required": false,
        "schema": { "type": "integer", "default": 0 },
        "description": "Number of results to skip (default: 0)"
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid parameters",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "Unauthorized": {
        "description": "Invalid or missing API key",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "NotFound": {
        "description": "Carrier does not exist",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests. Check X-RateLimit-Remaining and Retry-After headers.",
        "headers": {
          "Retry-After": {
            "schema": { "type": "integer" },
            "description": "Seconds to wait before retrying"
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "description": "Short error type" },
          "message": { "type": "string", "description": "Human-readable description" }
        },
        "required": ["error", "message"]
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "page": { "type": "integer" },
          "limit": { "type": "integer" },
          "total_results": { "type": "integer" },
          "total_pages": { "type": "integer" }
        }
      },
      "Address": {
        "type": "object",
        "properties": {
          "street": { "type": "string" },
          "city": { "type": "string" },
          "state": { "type": "string" },
          "zip": { "type": "string" }
        }
      },
      "FleetComposition": {
        "type": "object",
        "properties": {
          "owned": { "type": "integer" },
          "leased": { "type": "integer" }
        }
      },
      "GrowthMetrics": {
        "type": "object",
        "properties": {
          "power_units_12m": { "type": "integer", "description": "Net power unit change over 12 months" },
          "drivers_12m": { "type": "integer", "description": "Net driver change over 12 months" },
          "power_units_24m": { "type": "integer", "description": "Net power unit change over 24 months" },
          "drivers_24m": { "type": "integer", "description": "Net driver change over 24 months" }
        }
      },
      "TechnologyStack": {
        "type": "object",
        "properties": {
          "eld_provider": { "type": "string", "description": "ELD/telematics provider name" },
          "tms": { "type": "string", "description": "Transportation management system" },
          "fuel_card": { "type": "string", "description": "Fuel card provider" }
        }
      },
      "CompanyOfficer": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "title": { "type": "string" },
          "email": { "type": "string", "format": "email" }
        }
      },
      "CarrierProfile": {
        "type": "object",
        "description": "Full carrier profile with 200+ fields. Key fields shown below — use ?fields= to project specific fields.",
        "properties": {
          "dot_number": { "type": "string" },
          "legal_name": { "type": "string" },
          "dba_name": { "type": "string", "nullable": true },
          "mc_number": { "type": "string", "nullable": true },
          "operating_authority_status": { "type": "string", "enum": ["AUTHORIZED", "NOT AUTHORIZED", "REVOKED", "PENDING"] },
          "authority_types": { "type": "array", "items": { "type": "string" } },
          "authority_based_carrier_type": { "type": "string" },
          "carrier_type": { "type": "string" },
          "carrier_operation": { "type": "string", "enum": ["INTERSTATE", "INTRASTATE"] },
          "safety_rating": { "type": "string" },
          "phone": { "type": "string" },
          "fax": { "type": "string", "nullable": true },
          "cell_phone": { "type": "string", "nullable": true },
          "timezone": { "type": "string" },
          "date_added": { "type": "string", "format": "date" },
          "company_description": { "type": "string", "nullable": true },
          "physical_address": { "$ref": "#/components/schemas/Address" },
          "latitude": { "type": "number" },
          "longitude": { "type": "number" },
          "power_units": { "type": "integer" },
          "day_cabs": { "type": "integer" },
          "sleeper_cabs": { "type": "integer" },
          "drivers": { "type": "integer" },
          "drivers_added_24m": { "type": "integer" },
          "trucks_added_24m": { "type": "integer" },
          "avg_truck_age_years": { "type": "number" },
          "fleet_composition": { "$ref": "#/components/schemas/FleetComposition" },
          "oos_rate": { "type": "number", "description": "Out-of-service rate percentage" },
          "driver_oos_total": { "type": "integer" },
          "vehicle_oos_total": { "type": "integer" },
          "driver_oos_last_year": { "type": "integer" },
          "vehicle_oos_last_year": { "type": "integer" },
          "accidents_by_year": { "type": "object", "additionalProperties": { "type": "integer" } },
          "inspections_by_year": { "type": "object", "additionalProperties": { "type": "integer" } },
          "growth": { "$ref": "#/components/schemas/GrowthMetrics" },
          "services": { "type": "array", "items": { "type": "string" } },
          "cargo": { "type": "array", "items": { "type": "string" } },
          "trailers_by_type": { "type": "object", "additionalProperties": { "type": "integer" } },
          "technology": { "$ref": "#/components/schemas/TechnologyStack" },
          "company_officers": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyOfficer" } }
        }
      },
      "CarrierSearchResult": {
        "type": "object",
        "properties": {
          "dot_number": { "type": "string" },
          "legal_name": { "type": "string" },
          "dba_name": { "type": "string", "nullable": true },
          "physical_city": { "type": "string" },
          "physical_state": { "type": "string" },
          "confidence": { "type": "number", "description": "Match confidence score 0.0–1.0" }
        }
      },
      "CarrierSearchResponse": {
        "type": "object",
        "properties": {
          "total_results": { "type": "integer" },
          "results": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierSearchResult" } },
          "pagination": { "$ref": "#/components/schemas/Pagination" }
        }
      },
      "AuthorityRecord": {
        "type": "object",
        "properties": {
          "docket_number": { "type": "string" },
          "sub_number": { "type": "string" },
          "authority_type": { "type": "string" },
          "original_action": { "type": "string" },
          "original_served_date": { "type": "string", "format": "date" },
          "disposition_action": { "type": "string" },
          "disposition_decided_date": { "type": "string", "format": "date" },
          "disposition_served_date": { "type": "string", "format": "date" }
        }
      },
      "AuthorityResponse": {
        "type": "object",
        "properties": {
          "dot_number": { "type": "string" },
          "total_records": { "type": "integer" },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" },
          "authority_history": { "type": "array", "items": { "$ref": "#/components/schemas/AuthorityRecord" } }
        }
      },
      "Truck": {
        "type": "object",
        "properties": {
          "vin": { "type": "string" },
          "dot_number": { "type": "string" },
          "cab_type": { "type": "string" },
          "make": { "type": "string" },
          "model": { "type": "string" },
          "model_year": { "type": "integer" },
          "engine_manufacturer": { "type": "string" },
          "engine_model": { "type": "string" },
          "engine_displacement": { "type": "string" },
          "engine_type": { "type": "string" },
          "engine_cylinders": { "type": "integer" },
          "license_plate": { "type": "string" },
          "manufactured_by": { "type": "string" },
          "manufactured_in": { "type": "string" },
          "gross_weight": { "type": "integer" },
          "body_type": { "type": "string" },
          "brake_system_type": { "type": "string" },
          "plant_city": { "type": "string" },
          "plant_state": { "type": "string" }
        }
      },
      "TrucksResponse": {
        "type": "object",
        "properties": {
          "dot_number": { "type": "string" },
          "total_trucks": { "type": "integer" },
          "trucks": { "type": "array", "items": { "$ref": "#/components/schemas/Truck" } },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" },
          "total_results": { "type": "integer" }
        }
      },
      "Trailer": {
        "type": "object",
        "properties": {
          "vin": { "type": "string" },
          "dot_number": { "type": "string" },
          "manufacturer": { "type": "string" },
          "model_year": { "type": "integer" },
          "trailer_type": { "type": "string" },
          "reefer": { "type": "boolean" },
          "license_plate": { "type": "string" }
        }
      },
      "TrailersResponse": {
        "type": "object",
        "properties": {
          "dot_number": { "type": "string" },
          "total_trailers": { "type": "integer" },
          "trailers": { "type": "array", "items": { "$ref": "#/components/schemas/Trailer" } },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" },
          "total_results": { "type": "integer" }
        }
      },
      "Inspection": {
        "type": "object",
        "properties": {
          "inspection_id": { "type": "string" },
          "report_number": { "type": "string" },
          "date": { "type": "string", "format": "date" },
          "state": { "type": "string" },
          "level": { "type": "integer" },
          "start_time": { "type": "string" },
          "end_time": { "type": "string" },
          "location": { "type": "string" },
          "facility": { "type": "string" },
          "carrier_name": { "type": "string" },
          "shipper_name": { "type": "string" },
          "gross_vehicle_weight": { "type": "integer" },
          "violations_total": { "type": "integer" },
          "driver_violations": { "type": "integer" },
          "vehicle_violations": { "type": "integer" },
          "hazmat_violations": { "type": "integer" },
          "oos_total": { "type": "integer" },
          "oos_driver": { "type": "boolean" },
          "oos_vehicle": { "type": "boolean" },
          "oos_hazmat": { "type": "boolean" },
          "traffic_enforcement": { "type": "boolean" },
          "size_weight_enforcement": { "type": "boolean" }
        }
      },
      "InspectionsResponse": {
        "type": "object",
        "properties": {
          "dot_number": { "type": "string" },
          "total_inspections": { "type": "integer" },
          "inspections": { "type": "array", "items": { "$ref": "#/components/schemas/Inspection" } },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" },
          "total_results": { "type": "integer" }
        }
      },
      "Violation": {
        "type": "object",
        "properties": {
          "violation_code": { "type": "string" },
          "description": { "type": "string" },
          "oos": { "type": "boolean" },
          "unit_type": { "type": "string" },
          "basic_category": { "type": "string" }
        }
      },
      "ViolationsResponse": {
        "type": "object",
        "properties": {
          "inspection_id": { "type": "string" },
          "total_violations": { "type": "integer" },
          "violations": { "type": "array", "items": { "$ref": "#/components/schemas/Violation" } },
          "pagination": { "$ref": "#/components/schemas/Pagination" }
        }
      },
      "Crash": {
        "type": "object",
        "properties": {
          "crash_id": { "type": "string" },
          "report_number": { "type": "string" },
          "date": { "type": "string", "format": "date" },
          "state": { "type": "string" },
          "city": { "type": "string" },
          "location": { "type": "string" },
          "fatalities": { "type": "integer" },
          "injuries": { "type": "integer" },
          "tow_away": { "type": "boolean" },
          "hazmat_released": { "type": "boolean" },
          "severity": { "type": "string", "enum": ["FATAL", "INJURY", "TOW", "PROPERTY_DAMAGE"] },
          "vehicle_configuration": { "type": "string" },
          "cargo_body_type": { "type": "string" },
          "road_surface_condition": { "type": "string" },
          "trafficway": { "type": "string" },
          "weather_condition": { "type": "string" },
          "light_condition": { "type": "string" },
          "vehicles_in_accident": { "type": "integer" },
          "truck_or_bus": { "type": "string" },
          "gvw_rating": { "type": "string" },
          "federal_recordable": { "type": "boolean" }
        }
      },
      "CrashesResponse": {
        "type": "object",
        "properties": {
          "dot_number": { "type": "string" },
          "total_crashes": { "type": "integer" },
          "crashes": { "type": "array", "items": { "$ref": "#/components/schemas/Crash" } },
          "pagination": { "$ref": "#/components/schemas/Pagination" }
        }
      },
      "NewsArticle": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "source": { "type": "string" },
          "date": { "type": "string", "format": "date-time" },
          "type": { "type": "string" },
          "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral"] },
          "image_url": { "type": "string", "format": "uri", "nullable": true },
          "categories": { "type": "array", "items": { "type": "string" } },
          "topics": { "type": "array", "items": { "type": "string" } },
          "people": { "type": "array", "items": { "type": "string" } },
          "companies": { "type": "array", "items": { "type": "string" } }
        }
      },
      "NewsResponse": {
        "type": "object",
        "properties": {
          "dot_number": { "type": "string" },
          "total_results": { "type": "integer" },
          "articles": { "type": "array", "items": { "$ref": "#/components/schemas/NewsArticle" } }
        }
      },
      "Contact": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "full_name": { "type": "string" },
          "first_name": { "type": "string" },
          "last_name": { "type": "string" },
          "sex": { "type": "string" },
          "job_title": { "type": "string" },
          "job_title_role": { "type": "string" },
          "job_title_levels": { "type": "array", "items": { "type": "string" } },
          "job_company_name": { "type": "string" },
          "job_company_website": { "type": "string" },
          "job_company_size": { "type": "string" },
          "job_company_industry": { "type": "string" },
          "job_start_date": { "type": "string" },
          "industry": { "type": "string" },
          "linkedin_url": { "type": "string" },
          "facebook_url": { "type": "string", "nullable": true },
          "location_name": { "type": "string" },
          "location_region": { "type": "string" },
          "location_country": { "type": "string" }
        }
      },
      "ContactSearchResponse": {
        "type": "object",
        "properties": {
          "dot_number": { "type": "string" },
          "total_contacts": { "type": "integer" },
          "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } },
          "pagination": { "$ref": "#/components/schemas/Pagination" }
        }
      },
      "WorkExperience": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "company": { "type": "string" },
          "start_date": { "type": "string" },
          "end_date": { "type": "string", "nullable": true },
          "is_primary": { "type": "boolean" }
        }
      },
      "Education": {
        "type": "object",
        "properties": {
          "school": { "type": "string" },
          "start_date": { "type": "string" },
          "end_date": { "type": "string", "nullable": true }
        }
      },
      "EnrichedContact": {
        "type": "object",
        "description": "Enriched contact profile with verified emails, phone numbers, work history, education, and social profiles. Consumes 1 enrichment credit per new lookup.",
        "properties": {
          "id": { "type": "string" },
          "full_name": { "type": "string" },
          "first_name": { "type": "string" },
          "last_name": { "type": "string" },
          "sex": { "type": "string" },
          "job_title": { "type": "string" },
          "job_title_role": { "type": "string" },
          "job_title_levels": { "type": "array", "items": { "type": "string" } },
          "job_company_name": { "type": "string" },
          "job_company_website": { "type": "string" },
          "job_company_size": { "type": "string" },
          "job_company_industry": { "type": "string" },
          "work_email": { "type": "string", "format": "email", "nullable": true },
          "personal_emails": { "type": "array", "items": { "type": "string", "format": "email" } },
          "mobile_phone": { "type": "string", "nullable": true },
          "phone_numbers": { "type": "array", "items": { "type": "string" } },
          "linkedin_url": { "type": "string" },
          "facebook_url": { "type": "string", "nullable": true },
          "location_name": { "type": "string" },
          "location_locality": { "type": "string" },
          "location_region": { "type": "string" },
          "location_country": { "type": "string" },
          "location_geo": { "type": "string", "description": "Lat,lng coordinates" },
          "skills": { "type": "array", "items": { "type": "string" } },
          "experience": { "type": "array", "items": { "$ref": "#/components/schemas/WorkExperience" } },
          "education": { "type": "array", "items": { "$ref": "#/components/schemas/Education" } },
          "profiles": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "network": { "type": "string" },
                "url": { "type": "string" }
              }
            }
          },
          "credits": {
            "type": "object",
            "properties": {
              "remaining": { "type": "integer" },
              "total": { "type": "integer" },
              "used": { "type": "integer" }
            }
          }
        }
      }
    }
  }
}