openapi: 3.2.0
info:
title: AlphaLoops FMCSA Carrier Data Carriers 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.
Base URL: https://api.runalphaloops.com
API 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: []
tags:
- name: Carriers
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'
tags:
- Carriers
/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'
tags:
- Carriers
/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'
tags:
- Carriers
/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'
tags:
- Carriers
/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'
tags:
- Carriers
/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'
tags:
- Carriers
/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'
tags:
- Carriers
/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'
tags:
- Carriers
/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'
tags:
- Carriers
/v1/carriers/query:
post:
operationId: queryCarriers
summary: Advanced filtered carrier search
description: Filtered search with include/exclude conditions, geo-radius search, sorting, and field projection. No company name required — filter by state, fleet size, cargo type, technology, authority status, revenue, and more.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CarrierQueryRequest'
responses:
'200':
description: Paginated, optionally field-projected carrier results
content:
application/json:
schema:
$ref: '#/components/schemas/CarrierQueryResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
tags:
- Carriers
/v1/carriers/{dot_number}/insurance:
get:
operationId: getCarrierInsurance
summary: Get carrier insurance filings
description: Retrieve insurance filings (BIPD, cargo, bond) for a carrier from the FMCSA insurance table. Includes policy numbers, coverage limits, and insurer details.
parameters:
- $ref: '#/components/parameters/dotNumber'
- name: limit
in: query
required: false
schema:
type: integer
default: 50
maximum: 500
description: 'Results per page (default: 50, max: 500)'
- $ref: '#/components/parameters/page'
- name: sort_by
in: query
required: false
schema:
type: string
enum:
- effective_date
- insurance_type_code
- bipd_maximum_dollar_limit
- insurance_company_name
default: effective_date
description: Sort field
- name: sort_order
in: query
required: false
schema:
type: string
enum:
- asc
- desc
default: desc
description: Sort direction
- name: insurance_type
in: query
required: false
schema:
type: string
description: Filter by insurance type code (e.g. BIPD, CARGO, BOND)
- name: insurer
in: query
required: false
schema:
type: string
description: Partial match on insurance company name
- name: min_coverage
in: query
required: false
schema:
type: integer
description: Minimum BIPD dollar limit
- name: date_from
in: query
required: false
schema:
type: string
format: date
description: Effective date start (ISO date)
- name: date_to
in: query
required: false
schema:
type: string
format: date
description: Effective date end (ISO date)
responses:
'200':
description: Paginated insurance filings
content:
application/json:
schema:
$ref: '#/components/schemas/InsuranceResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
tags:
- Carriers
/v1/carriers/mc/{mc_number}/insurance:
get:
operationId: getCarrierInsuranceByMc
summary: Get carrier insurance filings by MC number
description: Retrieve insurance filings by MC docket number. Same response shape and filters as the DOT-based insurance endpoint.
parameters:
- name: mc_number
in: path
required: true
schema:
type: string
description: MC docket number (numeric)
- name: limit
in: query
required: false
schema:
type: integer
default: 50
maximum: 500
description: 'Results per page (default: 50, max: 500)'
- $ref: '#/components/parameters/page'
- name: sort_by
in: query
required: false
schema:
type: string
enum:
- effective_date
- insurance_type_code
- bipd_maximum_dollar_limit
- insurance_company_name
default: effective_date
description: Sort field
- name: sort_order
in: query
required: false
schema:
type: string
enum:
- asc
- desc
default: desc
description: Sort direction
- name: insurance_type
in: query
required: false
schema:
type: string
description: Filter by insurance type code
- name: insurer
in: query
required: false
schema:
type: string
description: Partial match on insurance company name
- name: min_coverage
in: query
required: false
schema:
type: integer
description: Minimum BIPD dollar limit
responses:
'200':
description: Paginated insurance filings
content:
application/json:
schema:
$ref: '#/components/schemas/InsuranceResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
tags:
- Carriers
/v1/carriers/{dot_number}/timeline:
get:
operationId: getCarrierTimeline
summary: Get carrier change-event and authority timeline
description: Merged chronological feed of carrier change events and authority history. Combines field-level changes from monthly FMCSA census diffs (contact, address, fleet, operations, authority, people) with authority history records.
parameters:
- $ref: '#/components/parameters/dotNumber'
- name: limit
in: query
required: false
schema:
type: integer
default: 50
maximum: 200
description: 'Max results (default: 50, max: 200)'
- $ref: '#/components/parameters/offset'
- name: category
in: query
required: false
schema:
type: string
description: 'Comma-separated categories: contact, address, fleet, operations, authority, people'
- name: date_from
in: query
required: false
schema:
type: string
format: date
description: Start date (ISO date)
- name: date_to
in: query
required: false
schema:
type: string
format: date
description: End date (ISO date)
responses:
'200':
description: Merged timeline of change events and authority actions
content:
application/json:
schema:
$ref: '#/components/schemas/TimelineResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
tags:
- Carriers
/v1/carriers/{dot_number}/mc-sales:
get:
operationId: getCarrierMcSales
summary: Get authority-for-sale listings for a carrier
description: 'Returns any authority-for-sale listings (Facebook groups, Telegram channels, BizBuySell, etc.) linked to this carrier''s DOT number, with seller info, asking prices, post URLs, and matching reasoning. Returns found: false with mc_sale: null when no listings are linked.'
parameters:
- name: dot_number
in: path
required: true
schema:
type: integer
description: The carrier's USDOT number
responses:
'200':
description: 'Authority-for-sale listings, or a found: false sentinel when none are linked'
content:
application/json:
schema:
$ref: '#/components/schemas/McSalesResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
tags:
- Carriers
/v1/carriers/{dot_number}/equipment-for-sale:
get:
operationId: getCarrierEquipmentForSale
summary: Get carrier fleet VINs listed for sale
description: Cross-references the VINs this carrier has been inspected with against a marketplace dataset of trucks and trailers currently (or recently) listed for sale. Returns one row per matching VIN, sorted by most recent inspection date. Empty results are common.
parameters:
- $ref: '#/components/parameters/dotNumber'
- name: limit
in: query
required: false
schema:
type: integer
default: 25
maximum: 200
description: 'Results per page (default: 25, max: 200)'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Paginated equipment-marketplace matches
content:
application/json:
schema:
$ref: '#/components/schemas/EquipmentForSaleResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
tags:
- Carriers
/v1/carriers/{dot_number}/connections:
get:
operationId: getCarrierConnections
summary: Get a carrier's relationship graph
description: Retrieve a carrier's corporate connections graph — shared officers, addresses, phones, emails, and equipment linking it to other carriers.
parameters:
- $ref: '#/components/parameters/dotNumber'
- name: limit
in: query
required: false
schema:
type: integer
default: 50
maximum: 200
description: 'Max results (default: 50, max: 200)'
responses:
'200':
description: Connection graph nodes and edges
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
tags:
- Carriers
/v1/carriers/{dot_number}/risk-signals:
get:
operationId: getCarrierRiskSignals
summary: Get aggregated carrier risk signals
description: Aggregated carrier risk assessment in a single call. Returns an AI-generated risk score (0-10) and level, plus six signal categories — authority-for-sale listings, equipment-for-sale marketplace matches, financial-distress indicators, fraud/chameleon patterns, historical authority/insurance/change-event patterns, and recent news sentiment. Each category carries a derived level of "high", "medium", "clear", or "unknown". The risk summary is cached; pass force_refresh=true to force regeneration.
parameters:
- $ref: '#/components/parameters/dotNumber'
- name: force_refresh
in: query
required: false
schema:
type: boolean
default: false
description: Set to true to bypass the cached risk summary and regenerate it from current signals (slower).
- name: include_equipment
in: query
required: false
schema:
type: boolean
default: true
description: Set to false to skip the equipment-marketplace VIN lookup for a faster response.
responses:
'200':
description: Scored risk header plus six derived signal categories
content:
application/json:
schema:
$ref: '#/components/schemas/RiskSignalsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
tags:
- Carriers
/v1/carriers/{dot_number}/similar:
get:
operationId: getSimilarCarriers
summary: Find carriers similar to a given carrier
description: Find carriers similar to the specified carrier based on fleet size, location, cargo type, and other attributes.
parameters:
- $ref: '#/components/parameters/dotNumber'
- name: limit
in: query
required: false
schema:
type: integer
default: 20
maximum: 100
description: 'Max results (default: 20, max: 100)'
responses:
'200':
description: Ranked list of similar carriers
content:
application/json:
schema:
$ref: '#/components/schemas/SimilarResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
tags:
- Carriers
/v1/carriers/{dot_number}/overview:
get:
operationId: getCarrierOverview
summary: Get an AI-generated carrier overview
description: Returns an AI-generated summary overview of a carrier including key highlights.
parameters:
- $ref: '#/components/parameters/dotNumber'
responses:
'200':
description: AI-generated overview and highlights
content:
application/json:
schema:
$ref: '#/components/schemas/OverviewResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
tags:
- Carriers
components:
schemas:
TimelineEvent:
type: object
properties:
id:
oneOf:
- type: integer
- type: string
dot_number:
type: string
detected_at:
type: string
format: date
category:
type: string
enum:
- contact
- address
- fleet
- operations
- authority
- people
event_type:
type: string
headline:
type: string
field_name:
type: string
nullable: true
old_value:
type: string
nullable: true
new_value:
type: string
nullable: true
metadata:
type: object
nullable: true
additionalProperties: true
source:
type: string
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
ConnectionsResponse:
type: object
properties:
dot_number:
type: string
total_nodes:
type: integer
total_edges:
type: integer
nodes:
type: array
items:
$ref: '#/components/schemas/ConnectionNode'
edges:
type: array
items:
$ref: '#/components/schemas/ConnectionEdge'
FleetComposition:
type: object
properties:
owned:
type: integer
leased:
type: integer
ConnectionNode:
type: object
properties:
id:
type: string
description: DOT number
label:
type: string
state:
type: string
nullable: true
city:
type: string
nullable: true
isFocal:
type: boolean
description: True for the queried carrier
additionalProperties: true
CarrierQueryRequest:
type: object
description: Filter body for POST /v1/carriers/query. All fields optional.
properties:
include:
type: object
description: Filter conditions to include. Supports scalar equality, arrays, range objects ({ min, max }), and a location object ({ latitude, longitude, radius_miles }).
additionalProperties: true
example:
state: TX
power_units:
min: 50
cargo_type:
- Van
- Reefer
operating_authority_status: Active
location:
latitude: 29.76
longitude: -95.37
radius_miles: 100
exclude:
type: object
description: Filter conditions to exclude (same shape as include).
additionalProperties: true
fields:
type: array
items:
type: string
description: Fields to return on each result (e.g. ["dot_number", "legal_name", "power_units"]).
sort_by:
type: string
description: 'Sort field: power_units, drivers, date_added, safety_rating, annual_revenue, distance, etc.'
sort_order:
type: string
enum:
- asc
- desc
default: desc
limit:
type: integer
default: 25
page:
type: integer
default: 1
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
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
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
Pagination:
type: object
properties:
page:
type: integer
limit:
type: integer
total_results:
type: integer
total_pages:
type: integer
McSaleListing:
type: object
properties:
seller_name:
type: string
nullable: true
phone:
type: string
nullable: true
email:
type: string
nullable: true
asking_price:
type: string
nullable: true
authority_age:
type: string
nullable: true
post_url:
type: string
nullable: true
source_file:
type: string
nullable: true
confidence:
type: number
nullable: true
description: 0–1 match confidence for this observation
reasoning:
type: string
nullable: true
CarrierSearchResponse:
type: object
properties:
total_results:
type: integer
results:
type: array
items:
$ref: '#/components/schemas/CarrierSearchResult'
pagination:
$ref: '#/components/schemas/Pagination'
Address:
type: object
properties:
street:
type: string
city:
type: string
state:
type: string
zip:
type: string
OverviewResponse:
type: object
properties:
dot_number:
type: string
overview:
type: string
highlights:
type: array
items:
type: string
InsuranceResponse:
type: object
properties:
dot_number:
type: string
mc_number:
type: integer
to
# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/alphaloops-fmcsa-carrier-data-api/refs/heads/main/openapi/alphaloops-fmcsa-carrier-data-api-carriers-api-openapi.yml