{"openapi":"3.0.3","info":{"title":"LongMile Carrier Intelligence API","version":"1.0.0","description":"REST API for enriched FMCSA carrier and broker data. Carrier profile lookups require an API key (free). Search and health endpoints are open with no key needed.","contact":{"url":"https://longmile.co"}},"servers":[{"url":"https://www.longmile.co","description":"Production"}],"paths":{"/api/entity/{usdot}":{"get":{"summary":"Get entity profile","operationId":"getEntityProfile","description":"Returns the full enriched profile for a USDOT entity — motor carrier or freight broker. Includes authority, insurance, safety, booking/broker score, and chameleon check. Results are cached for performance.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"usdot","in":"path","required":true,"description":"The USDOT number of the carrier (6–8 digits).","schema":{"type":"string","pattern":"^\\d{6,8}$","example":"3600129"}}],"responses":{"200":{"description":"Carrier profile retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CarrierProfile"},"example":{"query":{"usdot":"3600129"},"identity":{"legal_name":"ACME TRUCKING LLC","dba_name":null,"usdot":"3600129","mc":"MC-123456","address":"123 Main St, Dallas, TX 75201","phone":"214-555-0100","email":null,"carrier_type":"CARRIER","company_officer":"JOHN DOE","risk_level":{"score":20,"level":"Low","factors":[]}},"authority":{"operating_status":"AUTHORIZED FOR Property","carrier_operation":["Interstate"],"authority_granted":{"common":true,"contract":false,"broker":false},"out_of_service_date":null},"insurance":{"has_bmc91x":true,"insurer":"PROGRESSIVE INSURANCE","filing_date":"2021-03-15","policy_status":"Active","bipd_coverage":"$1,000,000","bipd_required":"$750,000","coverage_adequate":true},"safety":{"rating":"Satisfactory","oos_hint":"normal","safety_block":null},"longevity":{"years_active":5,"add_date":"2019-06-01","last_mcs150_update":"2024-01-10"},"operations":{"fleet_size":12,"total_drivers":15,"annual_mileage":500000,"crash_rate":null,"stability_score":82},"chameleon_check":{"is_suspect":false,"risk_level":"low","shared_contacts":[],"warning_flags":[]},"carrier_score":{"score":87,"band":"Excellent","breakdown":{},"hardStops":[]},"safety_score":{"score":90,"rawScore":49,"maxRawScore":55,"band":"Excellent","breakdown":{}},"broker_score":null,"broker_bond":null,"broker_authority_detail":null}}}},"400":{"description":"Invalid USDOT number.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Invalid USDOT number. Must be 6-8 digits."}}}},"404":{"description":"Carrier not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Carrier not found with the provided USDOT number."}}}},"429":{"description":"Rate limit exceeded. 100 requests per hour per IP address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded. Please try again later."}}}}}}},"/api/entity/search":{"get":{"summary":"Search carriers","operationId":"searchCarriers","description":"Search for US motor carriers or brokers by legal name or DBA name. Returns a list of possible matches, or a single exact match when found. Sourced from FMCSA/Socrata public data.","parameters":[{"name":"q","in":"query","required":true,"description":"Carrier name or partial name to search (min 2 characters).","schema":{"type":"string","minLength":2,"example":"Swift"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of results (1–5). Defaults to 5.","schema":{"type":"integer","minimum":1,"maximum":5,"default":5}}],"responses":{"200":{"description":"Search results.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CarrierSearchResult"}},"example":[{"usdot":"266358","legal_name":"SWIFT TRANSPORTATION CO OF ARIZONA LLC","dba_name":"","state":"AZ","status":"A"}]}}},"502":{"description":"Upstream FMCSA API error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Failed to fetch from FMCSA"}}}}}}},"/api/health":{"get":{"summary":"Health check","operationId":"healthCheck","description":"Returns the operational status of the API and its upstream data sources.","parameters":[],"responses":{"200":{"description":"API is operational.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"example":{"status":"online","timestamp":"2026-04-02T12:00:00.000Z","apis":{"qcmobile":"available","socrata":"available"}}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key for carrier profile lookups. Free to obtain from the admin panel."}},"schemas":{"CarrierProfile":{"type":"object","description":"Full enriched carrier or broker profile.","properties":{"query":{"type":"object","properties":{"usdot":{"type":"string"}}},"identity":{"type":"object","properties":{"legal_name":{"type":"string","nullable":true},"dba_name":{"type":"string","nullable":true},"usdot":{"type":"string"},"mc":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"carrier_type":{"type":"string","nullable":true,"enum":["CARRIER","BROKER",null]},"company_officer":{"type":"string","nullable":true},"risk_level":{"type":"object","properties":{"score":{"type":"number"},"level":{"type":"string","enum":["Low","Medium","High"]},"factors":{"type":"array","items":{"type":"string"}}}}}},"authority":{"type":"object","properties":{"operating_status":{"type":"string","nullable":true},"carrier_operation":{"type":"array","items":{"type":"string"},"nullable":true},"authority_granted":{"type":"object","properties":{"common":{"type":"boolean"},"contract":{"type":"boolean"},"broker":{"type":"boolean"}}},"out_of_service_date":{"type":"string","nullable":true}}},"insurance":{"type":"object","properties":{"has_bmc91x":{"type":"boolean"},"insurer":{"type":"string","nullable":true},"filing_date":{"type":"string","nullable":true},"policy_status":{"type":"string","nullable":true,"enum":["Active","Cancelled","Pending","Valid","Invalid",null]},"bipd_coverage":{"type":"string","nullable":true},"bipd_required":{"type":"string","nullable":true},"coverage_adequate":{"type":"boolean","nullable":true}}},"safety":{"type":"object","properties":{"rating":{"type":"string","nullable":true},"oos_hint":{"type":"string","enum":["normal","watch","elevated"]},"safety_block":{"type":"object","nullable":true}}},"longevity":{"type":"object","properties":{"years_active":{"type":"number","nullable":true},"add_date":{"type":"string","nullable":true},"last_mcs150_update":{"type":"string","nullable":true}}},"operations":{"type":"object","properties":{"fleet_size":{"type":"number","nullable":true},"total_drivers":{"type":"number","nullable":true},"annual_mileage":{"type":"number","nullable":true},"crash_rate":{"type":"number","nullable":true},"stability_score":{"type":"number","nullable":true}}},"chameleon_check":{"type":"object","properties":{"is_suspect":{"type":"boolean"},"risk_level":{"type":"string","enum":["low","medium","high"]},"shared_contacts":{"type":"array","items":{"type":"object"}},"warning_flags":{"type":"array","items":{"type":"string"}}}},"carrier_score":{"type":"object","nullable":true},"safety_score":{"type":"object","nullable":true},"broker_score":{"type":"object","nullable":true},"broker_bond":{"type":"object","nullable":true},"broker_authority_detail":{"type":"object","nullable":true}}},"CarrierSearchResult":{"type":"object","properties":{"usdot":{"type":"string","description":"USDOT number."},"legal_name":{"type":"string","description":"Legal company name."},"dba_name":{"type":"string","description":"DBA name if any."},"state":{"type":"string","description":"Physical state abbreviation."},"status":{"type":"string","description":"Status code (A=Active, I=Inactive)."}}},"HealthResponse":{"type":"object","properties":{"status":{"type":"string","example":"online"},"timestamp":{"type":"string","format":"date-time"},"apis":{"type":"object","properties":{"qcmobile":{"type":"string"},"socrata":{"type":"string"}}}}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message."}}}}}}