{
  "openapi": "3.1.0",
  "info": {
    "title": "Carrier Lookup API",
    "version": "1.0.0",
    "description": "FMCSA carrier lookup by USDOT or MC number: operating status, authority dates, insurance on file and a plain-language broker verdict. Free anonymous use: 10 requests per minute per IP. An API key (X-Api-Key header) raises the limit to 120 per minute. Not affiliated with FMCSA. Docs: https://dotcarriercheck.com/for-ai-agents",
    "contact": {
      "url": "https://dotcarriercheck.com/about#contact"
    },
    "termsOfService": "https://dotcarriercheck.com/terms"
  },
  "servers": [
    {
      "url": "https://dotcarriercheck.com"
    }
  ],
  "externalDocs": {
    "url": "https://dotcarriercheck.com/for-ai-agents"
  },
  "security": [
    {},
    {
      "apiKey": []
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key"
      }
    },
    "schemas": {
      "Carrier": {
        "type": "object",
        "description": "A carrier record. When an MC docket maps to several USDOT numbers, status is \"multiple\" and matches lists them instead.",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "multiple"
            ]
          },
          "carrier": {
            "type": "object",
            "properties": {
              "dot": {
                "type": "string",
                "description": "USDOT number"
              },
              "legal_name": {
                "type": "string"
              },
              "dba_name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "location": {
                "type": "object",
                "properties": {
                  "city": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "state": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "country": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                }
              },
              "usdot_status": {
                "type": "string",
                "enum": [
                  "active",
                  "inactive",
                  "pending",
                  "unknown"
                ]
              },
              "operation": {
                "type": "string"
              },
              "entity_types": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "power_units": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "drivers": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "safety_rating": {
                "type": "object",
                "properties": {
                  "rating": {
                    "type": "string",
                    "enum": [
                      "satisfactory",
                      "conditional",
                      "unsatisfactory",
                      "none"
                    ]
                  },
                  "date": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                }
              },
              "verdict": {
                "type": "object",
                "description": "Plain-language broker verdict from fixed rules.",
                "properties": {
                  "level": {
                    "type": "string",
                    "enum": [
                      "ok",
                      "caution",
                      "stop",
                      "info"
                    ]
                  },
                  "code": {
                    "type": "string"
                  },
                  "headline": {
                    "type": "string"
                  },
                  "reasons": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "new_authority": {
                    "type": "boolean"
                  },
                  "authority_age_days": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  }
                }
              },
              "authorities": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "docket": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string"
                    },
                    "kind": {
                      "type": "string",
                      "enum": [
                        "carrier",
                        "broker",
                        "forwarder",
                        "other"
                      ]
                    },
                    "status": {
                      "type": "string"
                    },
                    "active_since": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "first_granted": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "last_change": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              },
              "insurance": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "suspension_notice",
                      "cancel_pending",
                      "meets_minimum",
                      "below_minimum",
                      "none_required",
                      "not_loaded"
                    ]
                  },
                  "requirements": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "policies": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "cancellations": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  }
                }
              },
              "source": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "datasets": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "partial": {
                    "type": "boolean"
                  }
                }
              },
              "fetched_at": {
                "type": "string",
                "format": "date-time"
              },
              "links": {
                "type": "object",
                "properties": {
                  "page": {
                    "type": "string",
                    "format": "uri"
                  },
                  "safer": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              }
            }
          },
          "matches": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "dot": {
                  "type": "string"
                },
                "legal_name": {
                  "type": "string"
                },
                "state": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "page": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/carrier": {
      "get": {
        "operationId": "lookupCarrier",
        "summary": "Look up a motor carrier by USDOT or MC number",
        "description": "Returns FMCSA status, operating authority with the date the current active stretch began, insurance on file vs required, safety rating and a rule-based verdict (ok / caution / stop / info). Results are cached up to 24 hours; source.datasets[].as_of and fetched_at say how fresh they are. Give exactly one of dot or mc.",
        "parameters": [
          {
            "name": "dot",
            "in": "query",
            "description": "USDOT number (1-8 digits)",
            "schema": {
              "type": "string",
              "pattern": "^\\d{1,8}$"
            },
            "example": "53467"
          },
          {
            "name": "mc",
            "in": "query",
            "description": "MC docket number; MX or FF prefixes are accepted (e.g. MX123456)",
            "schema": {
              "type": "string"
            },
            "example": "138328"
          }
        ],
        "responses": {
          "200": {
            "description": "Carrier found (or several matches for an MC)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Carrier"
                }
              }
            }
          },
          "400": {
            "description": "Bad input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key"
          },
          "404": {
            "description": "No carrier with that number"
          },
          "429": {
            "description": "Rate limited; see Retry-After"
          },
          "503": {
            "description": "FMCSA data source not answering"
          }
        }
      }
    }
  }
}