api-ninjas-com Motor Carrier API

openapi: 3.2.0
info:
  title: Ninjas Motor Carrier API
  description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
  version: 1.0.0
  contact:
    name: API Ninjas
    url: https://api-ninjas.com
  license:
    name: Proprietary
servers:
- url: https://api.api-ninjas.com
  description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: Motor Carrier
  description: 'Look up any US motor carrier, broker or freight forwarder by USDOT or docket (MC) number. Returns identity, operating authority, insurance filings, safety rating, out-of-service status, and crash and inspection history, sourced from public Federal Motor Carrier Safety Administration records.


    API Ninjas is not affiliated with, endorsed by, or sponsored by the US Department of Transportation or FMCSA. This API is not a consumer report and may not be used for employment, credit, tenant screening or individual insurance underwriting. United States only.'
paths:
  /v1/motorcarrier:
    get:
      tags:
      - Motor Carrier
      summary: Look up a motor carrier by USDOT or MC number
      operationId: getMotorCarrier
      description: Canonical carrier profile. Provide exactly one of dot or mc.
      parameters:
      - $ref: '#/components/parameters/dot'
      - $ref: '#/components/parameters/mc'
      - $ref: '#/components/parameters/checks'
      - $ref: '#/components/parameters/min_bipd'
      - $ref: '#/components/parameters/min_cargo'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotorCarrierOpenapi_ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotorCarrierOpenapi_ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotorCarrierOpenapi_ErrorResponse'
      security:
      - ApiKeyAuth: []
  /v1/motorcarriersearch:
    get:
      tags:
      - Motor Carrier
      summary: Search carriers by name or attributes
      operationId: searchMotorCarriers
      description: Find carriers by name, location or status, or reverse-look-up by phone or email (Business+).
      parameters:
      - $ref: '#/components/parameters/MotorCarrierOpenapi_name'
      - $ref: '#/components/parameters/MotorCarrierOpenapi_state'
      - $ref: '#/components/parameters/MotorCarrierOpenapi_city'
      - $ref: '#/components/parameters/zip'
      - $ref: '#/components/parameters/status'
      - $ref: '#/components/parameters/phone'
      - $ref: '#/components/parameters/email'
      - $ref: '#/components/parameters/MotorCarrierOpenapi_limit'
      - $ref: '#/components/parameters/MotorCarrierOpenapi_offset'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotorCarrierOpenapi_ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotorCarrierOpenapi_ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotorCarrierOpenapi_ErrorResponse'
      security:
      - ApiKeyAuth: []
  /v1/motorcarrierinsurance:
    get:
      tags:
      - Motor Carrier
      summary: Insurance filings for a carrier
      operationId: getMotorCarrierInsurance
      description: Business+ only. Policy-level filings with coverage in US dollars, plus the 30-day BMC-35 cancellation window.
      parameters:
      - $ref: '#/components/parameters/dot'
      - $ref: '#/components/parameters/mc'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsuranceResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotorCarrierOpenapi_ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotorCarrierOpenapi_ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotorCarrierOpenapi_ErrorResponse'
      security:
      - ApiKeyAuth: []
  /v1/motorcarriersafety:
    get:
      tags:
      - Motor Carrier
      summary: Crash, inspection and BASIC results
      operationId: getMotorCarrierSafety
      description: Crash counts, out-of-service rates against the national average, and public BASIC measures.
      parameters:
      - $ref: '#/components/parameters/dot'
      - $ref: '#/components/parameters/mc'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SafetyResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotorCarrierOpenapi_ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotorCarrierOpenapi_ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotorCarrierOpenapi_ErrorResponse'
      security:
      - ApiKeyAuth: []
  /v1/motorcarrierlinks:
    get:
      tags:
      - Motor Carrier
      summary: Carriers sharing an address, phone, email domain or officer
      operationId: getMotorCarrierLinks
      description: Business+ only. Entity graph over the full FMCSA census for chameleon-carrier and double-brokering review.
      parameters:
      - $ref: '#/components/parameters/dot'
      - $ref: '#/components/parameters/mc'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinksResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotorCarrierOpenapi_ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotorCarrierOpenapi_ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotorCarrierOpenapi_ErrorResponse'
      security:
      - ApiKeyAuth: []
components:
  parameters:
    MotorCarrierOpenapi_city:
      name: city
      in: query
      required: false
      schema:
        type: string
    zip:
      name: zip
      in: query
      required: false
      schema:
        type: string
    mc:
      name: mc
      in: query
      required: false
      schema:
        type: string
      example: MC227271
      description: Docket number, with or without the MC/MX/FF prefix. Provide either dot or mc.
    MotorCarrierOpenapi_name:
      name: name
      in: query
      required: false
      schema:
        type: string
      example: knight transportation
      description: Company name. Matching is prefix-based against a normalised form of the legal and DBA name.
    min_cargo:
      name: min_cargo
      in: query
      required: false
      schema:
        type: integer
        default: 100000
      description: Cargo coverage threshold in dollars used by the criteria checks.
    email:
      name: email
      in: query
      required: false
      schema:
        type: string
      description: Business+ only. Reverse lookup by full email address or by domain.
    phone:
      name: phone
      in: query
      required: false
      schema:
        type: string
      description: 'Business+ only. Reverse lookup: find carriers registered with this phone number.'
    dot:
      name: dot
      in: query
      required: false
      schema:
        type: integer
      example: 428823
      description: USDOT number. Provide either dot or mc.
    MotorCarrierOpenapi_state:
      name: state
      in: query
      required: false
      schema:
        type: string
      example: AZ
    MotorCarrierOpenapi_limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        default: 20
        maximum: 100
    checks:
      name: checks
      in: query
      required: false
      schema:
        type: boolean
      description: Business+ only. Include a per-check evaluation against C.H. Robinson's published carrier criteria.
    MotorCarrierOpenapi_offset:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        default: 0
        maximum: 10000
    status:
      name: status
      in: query
      required: false
      schema:
        type: string
        enum:
        - active
        - inactive
        - pending
    min_bipd:
      name: min_bipd
      in: query
      required: false
      schema:
        type: integer
        default: 1000000
      description: BI&PD threshold in dollars used by the criteria checks.
  schemas:
    Authority:
      type: object
      properties:
        docket:
          type: string
        type:
          type: string
        status:
          type:
          - string
          - 'null'
          description: Active, Pending, Inactive or Withdrawn.
        bipd_required_usd:
          type:
          - integer
          - 'null'
        bipd_on_file_usd:
          type:
          - integer
          - 'null'
        cargo_required:
          type:
          - boolean
          - 'null'
        cargo_on_file:
          type:
          - boolean
          - 'null'
        bond_required:
          type:
          - boolean
          - 'null'
        bond_on_file:
          type:
          - boolean
          - 'null'
    SearchResponse:
      allOf:
      - $ref: '#/components/schemas/Provenance'
      - type: object
        properties:
          count:
            type: integer
          limit:
            type: integer
          offset:
            type: integer
          carriers:
            type: array
            items:
              $ref: '#/components/schemas/CarrierSummary'
    InsuranceFiling:
      type: object
      properties:
        form_code:
          type: string
          description: BMC-91, BMC-91X, BMC-34, BMC-84, BMC-85 or BMC-35.
        insurance_type:
          type:
          - string
          - 'null'
        insurer_name:
          type:
          - string
          - 'null'
        policy_number:
          type:
          - string
          - 'null'
        coverage_amount:
          type:
          - integer
          - 'null'
          description: Always US dollars.
        coverage_currency:
          type: string
          example: USD
        underlying_limit:
          type:
          - integer
          - 'null'
        effective_date:
          type:
          - string
          - 'null'
          format: date
        cancellation_date:
          type:
          - string
          - 'null'
          format: date
        days_until_cancellation:
          type:
          - integer
          - 'null'
        cancellation_pending:
          type: boolean
          description: Within the 30-day BMC-35 notice window under 49 CFR 387.313(d).
        docket:
          type:
          - string
          - 'null'
    Provenance:
      type: object
      properties:
        data_as_of:
          type: object
          additionalProperties:
            type: string
            format: date
          description: Publication date of each dataset.
          properties:
            census:
              type: string
              format: date
              description: Publication date of the carrier registration data.
              example: '2026-08-18'
            insurance:
              type: string
              format: date
              description: Publication date of the insurance filing data.
              example: '2026-08-20'
            authority:
              type: string
              format: date
              description: Publication date of the operating authority data.
              example: '2026-08-20'
            safety:
              type: string
              format: date
              description: Publication date of the safety measurement data.
              example: '2026-08-13'
            crashes:
              type: string
              format: date
              description: Publication date of the crash data.
              example: '2026-08-20'
            inspections:
              type: string
              format: date
              description: Publication date of the inspection data.
              example: '2026-08-18'
            out_of_service:
              type: string
              format: date
              description: Publication date of the out-of-service order data.
              example: '2026-08-20'
        retrieved_at:
          type: string
          format: date-time
        source:
          type: string
    CarrierResponse:
      allOf:
      - $ref: '#/components/schemas/Provenance'
      - type: object
        properties:
          found:
            type: boolean
          carrier:
            $ref: '#/components/schemas/Carrier'
          criteria:
            $ref: '#/components/schemas/Criteria'
    MotorCarrierOpenapi_ErrorResponse:
      type: object
      properties:
        error:
          type: string
    Docket:
      type: object
      properties:
        docket:
          type: string
          example: MC227271
        prefix:
          type: string
          enum:
          - MC
          - MX
          - FF
        number:
          type: integer
        status:
          type:
          - string
          - 'null'
    SafetyResponse:
      allOf:
      - $ref: '#/components/schemas/Provenance'
      - type: object
        properties:
          found:
            type: boolean
          dot_number:
            type:
            - integer
            - 'null'
          carrier_class:
            type:
            - string
            - 'null'
            enum:
            - property
            - passenger
            - null
          window_months:
            type: integer
          crashes:
            type: object
            properties:
              total:
                type: integer
              fatal:
                type: integer
              injury:
                type: integer
              tow_away:
                type: integer
          inspections:
            type: object
            additionalProperties:
              type: object
              properties:
                inspections:
                  type: integer
                out_of_service:
                  type: integer
                out_of_service_pct:
                  type:
                  - number
                  - 'null'
                national_average_pct:
                  type:
                  - number
                  - 'null'
                  description: Premium (Business+) field.
          basics:
            type: array
            items:
              $ref: '#/components/schemas/Basic'
          percentile_availability:
            type: string
          percentile_note:
            type: string
          not_public:
            type: array
            items:
              type: string
          coverage_note:
            type: string
    LinksResponse:
      allOf:
      - $ref: '#/components/schemas/Provenance'
      - type: object
        properties:
          found:
            type: boolean
          dot_number:
            type:
            - integer
            - 'null'
          linked_carrier_count:
            type: integer
          links:
            type: array
            items:
              $ref: '#/components/schemas/Link'
          linked_to_revoked_authority:
            type: boolean
          revoked_linked_dot_numbers:
            type: array
            items:
              type: integer
          note:
            type: string
    Link:
      type: object
      properties:
        link_type:
          type: string
          enum:
          - address
          - phone
          - email_domain
          - officer
        description:
          type: string
        shared_value:
          type:
          - string
          - 'null'
        association:
          type:
          - string
          - 'null'
        linked_carrier_count:
          type: integer
        linked_carriers:
          type: array
          items:
            $ref: '#/components/schemas/CarrierSummary'
    Address:
      type: object
      properties:
        street:
          type:
          - string
          - 'null'
        city:
          type:
          - string
          - 'null'
        state:
          type:
          - string
          - 'null'
        zip:
          type:
          - string
          - 'null'
        country:
          type:
          - string
          - 'null'
        county:
          type:
          - string
          - 'null'
        colonia:
          type:
          - string
          - 'null'
          description: Mexican-domiciled carriers only.
    Criteria:
      type: object
      description: 'Per-check evaluation against C.H. Robinson''s published carrier selection criteria. Deliberately returns no overall verdict: these are individual criteria checks, not a safety determination.'
      properties:
        criteria_source:
          type: string
        checks:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Check'
        checks_passed:
          type: array
          items:
            type: string
        checks_failed:
          type: array
          items:
            type: string
        note:
          type: string
    Basic:
      type: object
      properties:
        basic:
          type: string
        code:
          type:
          - string
          - 'null'
        measure:
          type:
          - number
          - 'null'
        inspections_with_violation:
          type:
          - integer
          - 'null'
        acute_critical_violation:
          type:
          - boolean
          - 'null'
        percentile:
          type:
          - number
          - 'null'
          description: Published by FMCSA for passenger carriers only.
        alert:
          type:
          - boolean
          - 'null'
          description: Passenger carriers only.
        trend:
          type:
          - string
          - 'null'
          description: Premium (Business+) field. up, down or flat against the prior monthly snapshot.
        availability:
          type:
          - string
          - 'null'
          description: Set to not_public for Crash Indicator and HazMat Compliance, which FMCSA withholds.
    Carrier:
      type: object
      properties:
        dot_number:
          type: integer
          example: 428823
        legal_name:
          type:
          - string
          - 'null'
        dba_name:
          type:
          - string
          - 'null'
        status:
          type:
          - string
          - 'null'
          description: Active, Inactive or Pending.
        entity_types:
          type: array
          items:
            type: string
          description: Carrier, Broker, Freight Forwarder, Shipper, Registrant, IEP or Cargo Tank.
        carrier_operation:
          type:
          - string
          - 'null'
        business_type:
          type:
          - string
          - 'null'
        registration_date:
          type:
          - string
          - 'null'
          format: date
        physical_address:
          $ref: '#/components/schemas/Address'
        mailing_address:
          $ref: '#/components/schemas/Address'
        dockets:
          type: array
          items:
            $ref: '#/components/schemas/Docket'
        authority:
          type: array
          items:
            $ref: '#/components/schemas/Authority'
        power_units:
          type:
          - integer
          - 'null'
        drivers:
          type:
          - integer
          - 'null'
        mcs150_date:
          type:
          - string
          - 'null'
          format: date
        safety_rating:
          type: string
          description: 'Satisfactory, Conditional, Unsatisfactory or Unrated. Unrated is a normal, acceptable state: roughly 92% of active interstate carriers hold no rating.'
        safety_rating_date:
          type:
          - string
          - 'null'
          format: date
        out_of_service:
          type: boolean
        out_of_service_date:
          type:
          - string
          - 'null'
          format: date
        out_of_service_reason:
          type:
          - string
          - 'null'
        phone:
          type:
          - string
          - 'null'
          description: Premium (Business+) field.
        fax:
          type:
          - string
          - 'null'
          description: Premium (Business+) field.
        cell_phone:
          type:
          - string
          - 'null'
          description: Premium (Business+) field.
        email_address:
          type:
          - string
          - 'null'
          description: Premium (Business+) field.
        company_officer_1:
          type:
          - string
          - 'null'
          description: Premium (Business+) field.
        company_officer_2:
          type:
          - string
          - 'null'
          description: Premium (Business+) field.
        undeliverable_address:
          type:
          - boolean
          - 'null'
          description: Premium (Business+) field. FMCSA mail to the physical address was returned undeliverable.
        prior_revocation:
          type:
          - boolean
          - 'null'
          description: Premium (Business+) field.
        prior_revocation_dot_number:
          type:
          - integer
          - 'null'
          description: Premium (Business+) field.
        mcs150_due_date:
          type:
          - string
          - 'null'
          format: date
          description: Premium (Business+) field. Last day of the next scheduled biennial MCS-150 update month (49 CFR 390.19).
        mcs150_overdue:
          type:
          - boolean
          - 'null'
          description: Premium (Business+) field.
        mcs150_mileage:
          type:
          - integer
          - 'null'
          description: Premium (Business+) field.
        recordable_crash_rate:
          type:
          - number
          - 'null'
          description: Premium (Business+) field.
        operation_classifications:
          type: array
          items:
            type: string
          description: Premium (Business+) field.
        cargo_classes:
          type: array
          items:
            type: string
          description: Premium (Business+) field.
        equipment:
          type: object
          description: Premium (Business+) field. Owned, term-leased and trip-leased counts by body class.
          additionalProperties: true
        hazmat:
          type:
          - boolean
          - 'null'
          description: Premium (Business+) field.
        dun_bradstreet_number:
          type:
          - string
          - 'null'
          description: Premium (Business+) field.
    CarrierSummary:
      type: object
      properties:
        dot_number:
          type: integer
        legal_name:
          type:
          - string
          - 'null'
        dba_name:
          type:
          - string
          - 'null'
        city:
          type:
          - string
          - 'null'
        state:
          type:
          - string
          - 'null'
        zip:
          type:
          - string
          - 'null'
        status:
          type:
          - string
          - 'null'
        carrier_operation:
          type:
          - string
          - 'null'
        power_units:
          type:
          - integer
          - 'null'
        drivers:
          type:
          - integer
          - 'null'
        safety_rating:
          type: string
    InsuranceResponse:
      allOf:
      - $ref: '#/components/schemas/Provenance'
      - type: object
        properties:
          found:
            type: boolean
          dot_number:
            type:
            - integer
            - 'null'
          summary:
            type: object
            properties:
              bipd_coverage:
                type:
                - integer
                - 'null'
                description: Total BI&PD liability limit in force, in US dollars. An excess layer counts on top of its underlying limit.
              cargo_coverage:
                type:
                - integer
                - 'null'
              bond_coverage:
                type:
                - integer
                - 'null'
              active_filings:
                type: integer
              cancellation_pending:
                type: boolean
              days_until_cancellation:
                type:
                - integer
                - 'null'
              bond_below_threshold:
                type: boolean
                description: Broker bond under the $75,000 floor in 49 CFR 387.307.
              bond_threshold:
                type: integer
              insurer_count:
                type: integer
          filings:
            type: array
            items:
              $ref: '#/components/schemas/InsuranceFiling'
          cancellation_notices:
            type: array
            items:
              $ref: '#/components/schemas/InsuranceFiling'
            description: BMC-35 filings. These are cancellation notices, not coverage.
          note:
            type: string
            description: Explains the dollar normalization and the BMC-35 split.
            example: Coverage amounts are in US dollars. BMC-35 filings are cancellation notices, not coverage, and are listed separately under cancellation_notices.
    Check:
      type: object
      properties:
        pass:
          type: boolean
        reason:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api