{"openapi":"3.0.3","info":{"title":"LongMile Carrier Intelligence API","version":"1.0.0","description":"REST API for enriched FMCSA carrier and broker data. Profile lookups work with no auth up to the configured free visitor quota, or with OAuth 2.1 Bearer tokens for account quota.","contact":{"url":"https://longmile.io"}},"servers":[{"url":"https://longmile.io","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. No Authorization header is required for the free no-auth quota. Add an OAuth Bearer token to use your account's lookup quota.","security":[{},{"BearerAuth":[]}],"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":"Lookup quota or IP request limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"message":"You've used the 50 free no-auth lookups for this month. Create a free LongMile account for more lookups and higher trust limits.","reason":"anon_limit","quota":{"plan":"No auth","used":50,"limit":50,"remaining":0,"window":"monthly"},"next_step":{"label":"Create a free account for more lookups","url":"/signup"}}}}}}}},"/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–50). Defaults to 25.","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}}],"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":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"OAuth 2.1 access token","description":"Optional OAuth Bearer access token issued by the LongMile authorization flow."}},"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."}}}}}}