/fmcsa/carriers/snapshots

POST /api/fmcsa/carriers/snapshots

Price: 5 credits

Get a motor carrier's SAFER Company Snapshot by USDOT or MC/MX number: USDOT and authority status, fleet size, operation classification, cargo carried, US and Canada inspection and crash counts with out-of-service rates, and the safety rating.

How to use it

Use this to vet a carrier's safety record: inspections, out-of-service rates against the national average, crashes and the FMCSA safety rating. It accepts an MC docket number when the USDOT number is unknown.

Parameters

• access-token string required

Request body

• timeout integer — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)
• usdot string nullable — USDOT number of the carrier; pass this or mc_number (examples: "54283")
• mc_number string nullable — MC or MX docket number of the carrier; pass this or usdot (examples: "MC-136818")

Response

• @type string (default: "FmcsaCarrierSnapshot")
• usdot string required
• url string required
• name string nullable
• dba_name string nullable
• registrant_type string nullable
• usdot_status string nullable
• out_of_service_at integer nullable
• state_carrier_id string nullable
• mcs150_filed_at integer nullable
• mcs150_mileage integer nullable
• mcs150_mileage_year integer nullable
• operating_authority_status string nullable
• docket_numbers array (default: [])
• physical_address string nullable
• mailing_address string nullable
• phone string nullable
• duns string nullable
• power_unit_count integer nullable
• non_cmv_unit_count integer nullable
• driver_count integer nullable
• operation_classifications array (default: [])
• carrier_operations array (default: [])
• cargo_carried array (default: [])
• us_total_inspection_count integer nullable
• us_total_iep_inspection_count integer nullable
• us_inspections_period_end_at integer nullable
• us_inspections array (default: [])
  • @type string (default: "FmcsaInspectionSummary")
  • inspection_type string required
  • inspection_count integer nullable
  • out_of_service_count integer nullable
  • out_of_service_percent number nullable
  • national_average_percent number nullable
• us_crashes_period_end_at integer nullable
• us_crashes object nullable
  • @type string (default: "FmcsaCrashSummary")
  • fatal_count integer nullable
  • injury_count integer nullable
  • tow_count integer nullable
  • total_count integer nullable
• canada_total_inspection_count integer nullable
• canada_inspections_period_end_at integer nullable
• canada_inspections array (default: [])
  • @type string (default: "FmcsaInspectionSummary")
  • inspection_type string required
  • inspection_count integer nullable
  • out_of_service_count integer nullable
  • out_of_service_percent number nullable
  • national_average_percent number nullable
• canada_crashes_period_end_at integer nullable
• canada_crashes object nullable
  • @type string (default: "FmcsaCrashSummary")
  • fatal_count integer nullable
  • injury_count integer nullable
  • tow_count integer nullable
  • total_count integer nullable
• safety_rating object nullable
  • @type string (default: "FmcsaSafetyRating")
  • rating string nullable
  • rating_type string nullable
  • rated_at integer nullable
  • reviewed_at integer nullable
• data_updated_at integer nullable

Errors

• 422 — The request body did not validate Check the fields against this schema. A URN with the wrong prefix is the most common cause.
• 408 — The request ran past its time limit Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner.
• 412 — No carrier matches this USDOT or MC/MX number, or SAFER marks its record inactive Retrying will not help: either the entity does not exist, or the input points at a different one.
• 429 — Too many requests: a rate limit or a usage window is exhausted When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit.
• 500 — Something broke on our side Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers.
• 529 — Rate limit reached, or the endpoint is overloaded Wait at least 30 seconds, then retry.

Response headers

• X-Error — Error message text (present only on error)
• X-Request-ID — Unique request identifier
• X-Execution-Time — Execution time in seconds
• X-Result-Count — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently.
• X-Total-Available-Results — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact.
• X-Warning — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry.
• X-Retry-After — Seconds to wait before retrying. Present only on 429.