{"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.\n\nThe same screening is available to AI assistants over the Model Context Protocol at `POST /mcp` (`search_entities`, `get_entity_profile`), which returns the profile as readable Markdown rather than JSON. It draws on the same quota.\n\nEvery payload carrying a screening result also carries a `notice` field. Our Terms require it to travel with the result wherever you surface it.","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 screening profile for a USDOT entity, motor carrier or freight broker.\n\nBy default the response is the COMPACT profile: the screening decision, the eligibility gates, the evidence-weighted risk score, authority, insurance (with the filing in force marked), safety, operations, the shared-identity screen and the company's dated record on one timeline. Add `?raw=1` to receive the full internal profile instead — a superset, with every source field, which is larger and changes more often.\n\nBoth shapes carry a `notice` field. Our Terms require it to travel with any screening result you surface.\n\nRead `decision.meets_federal_requirements` to branch on eligibility, `decision.display_score` for the number to show a person, `decision.unverified_checks` for any requirement that could not be checked (it holds the verdict at Review), and `method.scoring_edition` to tell whether a stored response was produced under the rules currently in force.\n\nA company registered as both a carrier and a broker is screened as a carrier by default; `profile.registered_as` lists every role on its registration and `profile.also_broker` says when `?view=broker` will return its broker screen (judged on its broker authority and bond).\n\nNo Authorization header is required for the free no-auth quota. Add an OAuth Bearer token to use your account's lookup quota.","security":[{},{"BearerAuth":[]},{"LongMileOAuth":["carrier:read"]}],"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"}},{"name":"raw","in":"query","required":false,"description":"Set to `1` for the full internal profile instead of the compact one. The compact shape is the documented contract; the raw shape is a superset that carries every source field and is not held stable in the same way.","schema":{"type":"string","enum":["1"]}},{"name":"view","in":"query","required":false,"description":"`carrier` (default) or `broker`. `broker` returns the broker screen of a company that holds broker authority — the view a carrier needs before hauling for it. Returns 404 when the company holds no broker authority. Costs one lookup, like any profile.","schema":{"type":"string","enum":["carrier","broker"],"default":"carrier"}}],"responses":{"200":{"description":"Screening profile retrieved. The compact shape is shown; `?raw=1` returns the full internal profile instead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompactProfile"},"example":{"notice":"Informational only. Compiled from public and government records that may be cached, delayed, or incomplete — verify at the source before acting. Not legal advice, not a consumer report, and not a recommendation to transact with any party.","as_of":"2026-09-04T11:00:00.000Z","sources":[{"source":"FMCSA Motus","status":"live","checked_at":"2026-09-04T11:00:00.000Z","detail":"3 insurance filing rows available; active BMC-91X found"}],"method":{"scoring_edition":13,"current_scoring_edition":13,"score_generation":"v1","identity_thresholds":{"review":40,"high":100},"crash_window_months":24},"profile":{"legal_name":"ACME TRUCKING LLC","dba_name":null,"usdot":"3600129","mc":"123456","entity_type":"carrier","registered_as":["Carrier"],"also_broker":false,"also_carrier":false,"officer":"JOHN DOE","phone":"2145550100","email":null,"address":"123 Main St, Dallas, TX 75201"},"decision":{"recommendation":"Cleared — no disqualifying findings in the records screened","score":87,"band":"Excellent","display_score":{"value":87,"source":"legacy","withheld":null},"hard_stops":[],"review_flags":[],"meets_federal_requirements":true,"federal_disqualifiers":[],"bookable":true,"gated":false,"blocked_only_by_unverifiable":false,"unverified_checks":[],"gate_reason":null,"gates":[{"key":"authority","status":"pass","detail":"Active authority on file.","code":"authority_active"},{"key":"insurance","status":"pass","detail":"BMC-91X in force.","code":"insurance_on_file"}]},"risk":{"score":78,"band":"Average","method_version":2,"statement":"Scores better than 62% of carriers with 1–6 power units.","confidence":"medium","measured_share":0.71,"percentile":62,"peer_group":"1–6 power units","peer_sample":48210,"signals":[{"key":"inspection_oos","state":"measured","value":74,"weight":0.25,"detail":"Vehicle and driver OOS below the national average."}],"patterns":[]},"authority":{"status":"A","active":true,"out_of_service":false,"out_of_service_date":null,"granted":{"common":true,"contract":false,"broker":false},"state":"active","state_label":"Active interstate authority","state_detail":"Common authority in force.","carrier_operation":["Interstate"],"granted_on":"2019-07-02","adverse":false,"broker_authority":null},"insurance":{"bmc91x":true,"status":"Active","insurer":"PROGRESSIVE INSURANCE","coverage":"$1,000,000","required":"$750,000","adequate":true,"state":"in_force","verification":"motus_rest","decisive":true,"filing_date":"2021-03-15","filings":[{"form":"BMC-91X","covers":"Public liability","insurer":"PROGRESSIVE INSURANCE","status":"Active","policy_number":"MCP-88213","coverage":"1000000","effective_date":"2021-03-15","received_date":"2021-03-17","cancellation_date":null,"in_force":true}]},"safety":{"rating":"Satisfactory","score":90,"band":"Excellent","oos_hint":"normal","inspections":{"total":19,"verdict":"Pass","verdict_detail":"Both categories screen at or below the national average.","vehicle_inspections":12,"driver_inspections":7,"vehicle_oos_rate":16.7,"driver_oos_rate":14.3,"vehicle_national_average":22.26,"driver_national_average":6.67,"vehicle":{"inspections":12,"oos_rate":16.7,"adjusted_oos_rate":18.4,"national_average":22.26,"delta_from_average":-5.56,"estimated_oos_count":2,"comparison":"better","status":"pass","tier":"pass"},"driver":{"inspections":7,"oos_rate":14.3,"adjusted_oos_rate":9.1,"national_average":6.67,"delta_from_average":7.63,"estimated_oos_count":1,"comparison":"worse","status":"watch","tier":"review"},"basic_alerts":["Vehicle Maintenance"],"basics":{"published":2,"total":7,"areas":[{"key":"vehicle_maintenance","label":"Vehicle Maintenance","category":"vehicle","status":"Alert","detail":"Above intervention threshold."}]}},"crashes":{"window_months":24,"in_window":0,"all_time":1,"fatal_in_window":0,"injury_in_window":0}},"operations":{"fleet_size":12,"power_units":12,"drivers":15,"annual_mileage":500000,"years_active":5,"registered_on":"2019-06-01","mcs150_date":"2025-01-10","cargo_types":["General Freight"],"hauls_motor_vehicles":false,"hazmat":false},"identity_risk":{"verdict":"clean","verdict_label":"Clear","verdict_statement":"No shared-identity pattern found in the records screened.","score":30,"blocking":false,"chameleon_suspect":false,"chameleon_risk":"low","shared_contact_groups":1,"shared_contacts":[{"contact_type":"officer","matching":[{"usdot":"2811004","legal_name":"SOLIS LOGISTICS LLC","operating_status":"A"}]}],"warning_flags":[],"findings":[{"code":"shared_officer_active","points":30,"summary":"Company officer also listed on 2 companies that are still operating.","related_usdots":["2811004","3140922"]}],"notes":["Officer links to operating entities are capped and cannot reach the review threshold alone."],"linked_entities":[{"usdot":"2811004","legal_name":"SOLIS LOGISTICS LLC","standing":"active","status_detail":"Active interstate authority","linked_by":["officer"],"ceased_at":null,"registered_at":"2018-03-01","self_affiliate":false}],"federal_excluded":false,"federal_exclusion_checked":true,"screen_unavailable":false},"timeline":[{"date":"2021-03-15","kind":"insurance","title":"BMC-91X · Public liability","detail":"PROGRESSIVE INSURANCE · $1,000,000"},{"date":"2019-06-01","kind":"registration","title":"USDOT number issued","detail":"FMCSA registration for DOT 3600129. Everything below dates from here."}]}}}},"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":"","physical_address":"2200 S 75TH AVE","city":"PHOENIX","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/me":{"get":{"summary":"Account and lookup allowance","operationId":"getMe","description":"Returns the LongMile account a Bearer token belongs to, together with the lookup allowance it draws on and when that allowance resets. Requires an OAuth Bearer token. Reading it consumes no lookups.","security":[{"BearerAuth":[]},{"LongMileOAuth":[]}],"parameters":[],"responses":{"200":{"description":"The token's account and allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"},"example":{"account":{"email":"dispatch@example.com","name":"Dispatch","role":"user","team_owner_email":null},"plan":{"name":"Starter","slug":"starter"},"quota":{"plan":"Starter","used":128,"limit":1500,"remaining":1372,"unlimited":false,"window":"monthly","period_start":"2026-04-01T00:00:00.000Z","resets_at":"2026-05-01T00:00:00.000Z"},"scopes":["profile:read","search:read"]}}}},"401":{"description":"Missing, expired or revoked access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"message":"Invalid or expired access token"}}}}}}},"/api/methodology":{"get":{"summary":"Published screening methodology","operationId":"getMethodology","description":"The machine-readable method behind every verdict: the eligibility gates, the scored factors and their weights, the peer groups, the shared-identity screen with its point weights and thresholds, the published national benchmarks, and the method's own stated limitations. Versioned alongside the engine — `scoring_edition` here is the same number a profile carries in `method.scoring_edition`, so a result can always be read against the rules that produced it. Cached for an hour; consumes no lookup quota.","parameters":[],"responses":{"200":{"description":"The current methodology.","content":{"application/json":{"schema":{"type":"object","properties":{"notice":{"type":"string"},"version":{"type":"integer","description":"Score method version."},"scoring_edition":{"type":"integer","description":"Matches `method.scoring_edition` on a profile."},"updated":{"type":"string","format":"date"},"summary":{"type":"string"},"principles":{"type":"array","items":{"type":"object"}},"gates":{"type":"array","items":{"type":"object"}},"factors":{"type":"array","items":{"type":"object"}},"thresholds":{"type":"object"},"peer_groups":{"type":"array","items":{"type":"object"}},"identity_screen":{"type":"object","description":"The shared-identity screen stated in full: verdicts, thresholds, and why a link weighs what it does."},"benchmarks":{"type":"object","description":"The published figures a result is measured against."},"patterns":{"type":"array","items":{"type":"object"}},"sources":{"type":"array","items":{"type":"object"}},"limitations":{"type":"array","items":{"type":"string"}}}}}}}}}},"/api/health":{"get":{"summary":"Health check","operationId":"healthCheck","description":"Liveness check. Returns 200 whenever the server is up; it does not probe upstream data sources.","parameters":[],"responses":{"200":{"description":"Server is up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"example":{"status":"ok"}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"OAuth 2.1 access token","description":"OAuth 2.1 access token (prefix lm_at_, valid 1 hour). Get one from Account → Connections → Developer apps → Generate tokens, or through the LongMileOAuth flow. See https://longmile.io/docs#oauth-overview."},"LongMileOAuth":{"type":"oauth2","description":"Authorization code flow with PKCE (S256 required). Create a client ID under Account → Connections → Developer apps; server-side apps also get a client secret. Refresh tokens rotate on every use.","flows":{"authorizationCode":{"authorizationUrl":"https://longmile.io/oauth/authorize","tokenUrl":"https://longmile.io/oauth/token","refreshUrl":"https://longmile.io/oauth/token","scopes":{"mcp":"Use LongMile's MCP tools (carrier & broker lookups)","carrier:read":"Look up carrier and broker intelligence profiles","risk-acceptance:write":"Record and withdraw documented risk acceptances in your workspace","profile":"Read your basic profile (name)","email":"Read your email address","openid":"Confirm your LongMile identity"}}}}},"schemas":{"CompactProfile":{"type":"object","description":"The default response shape: a screening decision with the evidence behind it. Additive by contract — new fields appear, existing ones keep their name and type.","required":["notice","profile","decision"],"properties":{"notice":{"type":"string","description":"Informational-use notice. Preserve it wherever you surface a result taken from this payload."},"as_of":{"type":"string","nullable":true,"format":"date-time","description":"Newest source check across `sources`. Null when no source reported a time."},"sources":{"type":"array","description":"Each upstream source, its state at screening time, and what it held.","items":{"type":"object","properties":{"source":{"type":"string"},"status":{"type":"string","enum":["live","cached","local","stale","unknown"]},"checked_at":{"type":"string","format":"date-time"},"detail":{"type":"string","nullable":true}}}},"method":{"type":"object","description":"Which rules produced this answer. Compare `scoring_edition` against `current_scoring_edition` on a STORED payload to tell whether it is still current; on a live response they always agree.","properties":{"scoring_edition":{"type":"integer","nullable":true},"current_scoring_edition":{"type":"integer"},"score_generation":{"type":"string","enum":["v1","v2"]},"identity_thresholds":{"type":"object","description":"Weighed identity points at which the shared-identity screen moves off clear.","properties":{"review":{"type":"number"},"high":{"type":"number"}}},"crash_window_months":{"type":"integer"}}},"profile":{"type":"object","properties":{"legal_name":{"type":"string"},"dba_name":{"type":"string","nullable":true},"usdot":{"type":"string"},"mc":{"type":"string","nullable":true},"entity_type":{"type":"string","enum":["carrier","broker"],"description":"The screen this payload ran: `carrier` (default) or `broker` (`?view=broker`)."},"registered_as":{"type":"array","items":{"type":"string"},"description":"Every role on the FMCSA registration in plain words (Carrier, Broker, Freight forwarder, Shipper, …) — SAFER's Entity Type. Empty when not yet known."},"also_broker":{"type":"boolean","description":"Carrier screen only: the company also holds a broker role. `?view=broker` returns that screen."},"also_carrier":{"type":"boolean","description":"Broker screen only: the company is also registered as a carrier."},"officer":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"address":{"type":"string","nullable":true}}},"decision":{"type":"object","description":"The screening result and everything it rests on.","properties":{"recommendation":{"type":"string","description":"The verdict sentence, as shown on the profile."},"score":{"type":"number","nullable":true,"description":"v1 composite. Unchanged for existing integrations."},"band":{"type":"string","nullable":true,"enum":["Excellent","Average","Poor","Unrated",null]},"display_score":{"type":"object","description":"The number the LongMile screens show, resolved once. Render this, not `score`, so your UI cannot publish a figure our own verdict contradicts. A null `value` with a `withheld` reason is a real answer, not a missing field.","properties":{"value":{"type":"number","nullable":true},"source":{"type":"string","nullable":true},"withheld":{"type":"string","nullable":true,"enum":["gated","failed_screening","insufficient_evidence",null]}}},"meets_federal_requirements":{"type":"boolean","description":"THE FIELD TO BRANCH ON. False when the federal record shows a condition federal law itself treats as disqualifying — no active authority, no insurance or bond on file, an out-of-service order, a federal exclusion, an Unsatisfactory rating."},"federal_disqualifiers":{"type":"array","items":{"type":"string"}},"bookable":{"type":"boolean","deprecated":true,"description":"Same value as `meets_federal_requirements`. Kept for existing integrations; prefer the better name."},"gated":{"type":"boolean"},"blocked_only_by_unverifiable":{"type":"boolean","description":"True when nothing failed but at least one requirement could not be CHECKED. A check we could not run does not gate the profile: the score is shown and the verdict is held at Review. Reporting it as a failure is a false accusation about a real company."},"unverified_checks":{"type":"array","items":{"type":"string"},"description":"The requirements that could not be checked, by name (e.g. \"Federal exclusion\"). Each holds the verdict at Review; none is a finding about the company."},"gate_reason":{"type":"string","nullable":true},"gates":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"status":{"type":"string","enum":["pass","fail","not_applicable","unverifiable"]},"detail":{"type":"string"},"code":{"type":"string"}}}},"hard_stops":{"type":"array","items":{"type":"string"}},"review_flags":{"type":"array","items":{"type":"string"},"description":"Never repeats a fact a hard stop already carries."}}},"risk":{"type":"object","nullable":true,"description":"Evidence-weighted score (method v2), alongside the v1 number rather than replacing it. `score` is null when the evidence base was too thin to justify one.","properties":{"score":{"type":"number","nullable":true},"band":{"type":"string","enum":["Excellent","Average","Poor","Unrated"]},"method_version":{"type":"integer"},"statement":{"type":"string"},"confidence":{"type":"string","enum":["low","medium","high"],"description":"How much of the signal set was measured — not a peer ranking."},"measured_share":{"type":"number"},"percentile":{"type":"number","nullable":true},"peer_group":{"type":"string","nullable":true},"peer_sample":{"type":"number","nullable":true},"signals":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"state":{"type":"string","enum":["measured","insufficient","missing","not_applicable"]},"value":{"type":"number","nullable":true},"weight":{"type":"number"},"detail":{"type":"string"}}}},"patterns":{"type":"array","items":{"type":"string"}}}},"authority":{"type":"object","properties":{"status":{"type":"string"},"active":{"type":"boolean"},"out_of_service":{"type":"boolean","description":"Read this, not the date: an order exists even where FMCSA publishes no date for it."},"out_of_service_date":{"type":"string","nullable":true},"granted":{"type":"object","properties":{"common":{"type":"boolean"},"contract":{"type":"boolean"},"broker":{"type":"boolean"}}},"state":{"type":"string","nullable":true,"enum":["revoked","out_of_service","not_authorized","pending_applicant","active","not_applicable","unverified",null],"description":"Resolved standing. Separates cases the single status string cannot: an applicant awaiting FMCSA's grant, an authority revoked for cause, and an intrastate carrier that needs none."},"state_label":{"type":"string","nullable":true},"state_detail":{"type":"string","nullable":true},"carrier_operation":{"type":"array","items":{"type":"string"}},"granted_on":{"type":"string","nullable":true,"description":"Earliest grant on the authority timeline."},"adverse":{"type":"boolean","nullable":true,"description":"Enforcement outcome rather than administrative."},"broker_authority":{"type":"object","nullable":true,"description":"Broker screen only: the broker authority the verdict is judged on — never the carriage authority of a company holding both.","properties":{"status":{"type":"string","nullable":true},"type":{"type":"string","nullable":true,"description":"The deciding authority, e.g. \"Broker of Property (Except Household Goods)\"."},"types":{"type":"array","items":{"type":"string"},"description":"Every ACTIVE broker authority on file."},"docket":{"type":"string","nullable":true},"source":{"type":"string","nullable":true,"enum":["motus","fmcsa_authority",null]}}}}},"insurance":{"type":"object","description":"Carrier fields shown. For a broker this object carries `bmc84`, `bmc85`, `company`, `status` and `filing_date` instead.","properties":{"bmc91x":{"type":"boolean"},"status":{"type":"string","nullable":true},"insurer":{"type":"string","nullable":true},"coverage":{"type":"string","nullable":true},"required":{"type":"string","nullable":true},"adequate":{"type":"boolean","nullable":true},"state":{"type":"string","nullable":true,"enum":["in_force","not_in_force","pending","unknown",null],"description":"`bmc91x: false` means two different things. Read this with `decisive`: a source ALLOWED to say no actually said no (a finding about the carrier), versus nothing authoritative could be reached (a gap in what we can see). Printing 'No insurance' for the second accuses a carrier who may be perfectly covered."},"verification":{"type":"string","nullable":true,"enum":["motus_rest","motus_mirror","legacy_archive","none",null]},"decisive":{"type":"boolean","nullable":true,"description":"True when a source allowed to assert absence actually answered."},"filing_date":{"type":"string","nullable":true},"filings":{"type":"array","description":"The docket, newest first — evidence, not the verdict. At most one row carries `in_force: true`, and only where the verdict itself says a filing is on file. If no row is marked, do not describe any of them as current cover.","items":{"type":"object","properties":{"form":{"type":"string","nullable":true},"covers":{"type":"string","nullable":true,"description":"What that form covers in plain words."},"insurer":{"type":"string","nullable":true},"status":{"type":"string","nullable":true,"description":"FMCSA's own word for where the filing stands — Active, Pending, Replaced or Cancelled. Null when the source did not say; a missing status is not 'active'."},"policy_number":{"type":"string","nullable":true},"coverage":{"type":"string","nullable":true},"effective_date":{"type":"string","nullable":true},"received_date":{"type":"string","nullable":true,"description":"When FMCSA received the filing, where the source recorded it."},"cancellation_date":{"type":"string","nullable":true,"description":"When the filing stopped, or is scheduled to stop, covering. A past date means the row is history even with no status word; a future date is the scheduled end of live cover."},"in_force":{"type":"boolean"}}}}}},"safety":{"type":"object","properties":{"rating":{"type":"string","nullable":true},"score":{"type":"number","nullable":true},"band":{"type":"string","nullable":true},"oos_hint":{"type":"string","enum":["normal","watch","elevated"]},"inspections":{"type":"object","nullable":true,"properties":{"total":{"type":"integer","description":"Distinct inspections: a Level I counts as both vehicle and driver."},"verdict":{"type":"string","enum":["Pass","Watch","Fail","Unknown"]},"verdict_detail":{"type":"string"},"vehicle":{"$ref":"#/components/schemas/InspectionCategory"},"driver":{"$ref":"#/components/schemas/InspectionCategory"},"basic_alerts":{"type":"array","items":{"type":"string"}},"basics":{"type":"object","description":"How much of the BASIC table FMCSA publishes. An empty `basic_alerts` means either every area published and clean, or FMCSA publishing nothing at all — which is ordinary for a small fleet and is a gap in the record, not a pass. `published` tells the two apart.","properties":{"published":{"type":"integer"},"total":{"type":"integer"},"areas":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"category":{"type":"string","enum":["vehicle","driver","other"]},"status":{"type":"string","nullable":true,"enum":["Normal","Alert","N/A",null]},"detail":{"type":"string"}}}}}}}},"crashes":{"type":"object","description":"Both counts, named. The score is measured over FMCSA's window; the record lists everything.","properties":{"window_months":{"type":"integer"},"in_window":{"type":"integer"},"all_time":{"type":"integer"},"fatal_in_window":{"type":"integer"},"injury_in_window":{"type":"integer"}}}}},"operations":{"type":"object","properties":{"fleet_size":{"type":"number","nullable":true},"power_units":{"type":"number","nullable":true,"description":"The same number under the name FMCSA prints it — commercial motor vehicles only, matching SAFER."},"drivers":{"type":"number","nullable":true},"annual_mileage":{"type":"number","nullable":true},"years_active":{"type":"number","nullable":true,"description":"Years since first registration. Not years operating — see `registered_on`."},"registered_on":{"type":"string","nullable":true},"mcs150_date":{"type":"string","nullable":true},"cargo_types":{"type":"array","items":{"type":"string"}},"hauls_motor_vehicles":{"type":"boolean"},"hazmat":{"type":"boolean","nullable":true}}},"identity_risk":{"type":"object","description":"The shared-identity (chameleon-pattern) screen. Read `verdict`: it separates 'unverified' — a linked entity whose operating standing no source could confirm, which is NOT a pass — from 'clean'.","properties":{"verdict":{"type":"string","enum":["clean","unverified","medium","high"]},"verdict_label":{"type":"string","nullable":true,"description":"The badge the LongMile profile shows for this verdict."},"verdict_statement":{"type":"string","nullable":true,"description":"What that verdict means, in the site's own words."},"score":{"type":"number","nullable":true,"description":"Total weighed identity points. Read against `method.identity_thresholds` — the same verdict at 42 points and at 260 are not the same finding."},"blocking":{"type":"boolean","description":"False by default. A shared-identity pattern is a reason to look, not a disqualification LongMile makes for you."},"chameleon_suspect":{"type":"boolean","description":"Legacy projection of `verdict`."},"chameleon_risk":{"type":"string","enum":["low","medium","high"],"description":"Legacy projection of `verdict`."},"shared_contact_groups":{"type":"integer"},"shared_contacts":{"type":"array","description":"What is shared and with whom. The raw contact value is not republished here; fetch `?raw=1` for it.","items":{"type":"object","properties":{"contact_type":{"type":"string","enum":["address","phone","email","officer"]},"matching":{"type":"array","items":{"type":"object","properties":{"usdot":{"type":"string"},"legal_name":{"type":"string"},"operating_status":{"type":"string","nullable":true}}}}}}},"warning_flags":{"type":"array","items":{"type":"string"}},"findings":{"type":"array","description":"Each finding with the points it contributed. `points` is what separates a shared officer at a company still trading — capped, informational, incapable of reaching the review line alone — from a predecessor that was revoked and re-registered, which is conclusive on its own. The two summaries read alike; the weights do not.","items":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine key. Branch on this, not on the prose summary."},"points":{"type":"number"},"summary":{"type":"string"},"related_usdots":{"type":"array","items":{"type":"string"}}}}},"notes":{"type":"array","items":{"type":"string"},"description":"Context that scored nothing — a registration-agent address, dual authority, damping applied."},"linked_entities":{"type":"array","items":{"type":"object","properties":{"usdot":{"type":"string"},"legal_name":{"type":"string"},"standing":{"type":"string","enum":["active","inactive","revoked","oos","unresolved"]},"status_detail":{"type":"string","nullable":true},"linked_by":{"type":"array","items":{"type":"string","enum":["address","mailing_address","phone","email","officer"]}},"ceased_at":{"type":"string","nullable":true},"registered_at":{"type":"string","nullable":true},"self_affiliate":{"type":"boolean","description":"True when the link is to another registration of this same company."}}}},"federal_excluded":{"type":"boolean"},"federal_exclusion_checked":{"type":"boolean","description":"False when the lookup ran against an empty or stale mirror. `federal_excluded: false` alone cannot tell 'checked, clear' from 'could not check'."},"screen_unavailable":{"type":"boolean","description":"True when the identity screen could not run at all; its verdict means nothing."}}},"timeline":{"type":"array","description":"Every dated record on one line of time, newest first: registration, authority actions, insurance filings, the last MCS-150, any out-of-service order. Capped at 24 entries.","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"kind":{"type":"string","enum":["registration","authority","insurance","filing","adverse"]},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"InspectionCategory":{"type":"object","description":"One inspection category with the figures the screen itself used. A carrier with three inspections and one out-of-service reads 33% — five times the national average, on a sample far too small to mean it. The policy shrinks a small sample toward the average before screening it, so `adjusted_oos_rate` is what the tier was decided on. Quoting `oos_rate` beside a verdict of Pass makes the verdict look wrong.","properties":{"inspections":{"type":"integer"},"oos_rate":{"type":"number","nullable":true,"description":"The observed rate."},"adjusted_oos_rate":{"type":"number","nullable":true,"description":"The sample-adjusted rate the screen compared. Null on profiles built before the adjustment shipped — not a finding."},"national_average":{"type":"number","nullable":true},"delta_from_average":{"type":"number","nullable":true},"estimated_oos_count":{"type":"number","nullable":true},"comparison":{"type":"string","enum":["better","average","worse","unknown"]},"status":{"type":"string","enum":["pass","watch","fail","unknown"]},"tier":{"type":"string","nullable":true,"enum":["pass","review","fail","insufficient_data","no_data",null],"description":"The five-way screening result `status` collapses into three. 'insufficient_data' is the one to tell apart from 'watch': the sample was too small to screen, not that something was found."}}},"CarrierSearchResult":{"type":"object","description":"One search hit. Names repeat across states — always disambiguate on `city`/`state` before screening a USDOT.","properties":{"usdot":{"type":"string","description":"USDOT number."},"legal_name":{"type":"string","description":"Legal company name."},"dba_name":{"type":"string","description":"DBA name if any."},"physical_address":{"type":"string","description":"Street address of record."},"city":{"type":"string","description":"Physical city."},"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":"ok"}}},"MeResponse":{"type":"object","properties":{"account":{"type":"object","properties":{"email":{"type":"string","description":"Email of the LongMile account the token belongs to."},"name":{"type":"string","nullable":true},"role":{"type":"string","example":"user"},"team_owner_email":{"type":"string","nullable":true,"description":"Set when the allowance is billed to a team owner rather than this account."}}},"plan":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"quota":{"type":"object","properties":{"plan":{"type":"string"},"used":{"type":"integer"},"limit":{"type":"integer","nullable":true,"description":"Null when the account is uncapped."},"remaining":{"type":"integer","nullable":true},"unlimited":{"type":"boolean"},"window":{"type":"string","example":"monthly"},"period_start":{"type":"string","format":"date-time"},"resets_at":{"type":"string","format":"date-time","description":"When the used counter returns to zero."}}},"scopes":{"type":"array","items":{"type":"string"}}}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message."}}}}}}