{ "openapi": "3.1.0", "info": { "title": "MyDotCheck public API", "version": "1.0.0", "summary": "Free, read-only DOT compliance data for any USDOT or MC number.", "description": "Read-only JSON API over public FMCSA data (Motor Carrier Census and Vehicle Inspection File). No API key and no sign-up. Rate limit: 60 requests per minute per IP, reported in RateLimit-* headers. Every endpoint is read-only, so it is safe to call against production; there is no separate sandbox. MyDotCheck is an independent service and is not affiliated with, endorsed by, or part of the U.S. Department of Transportation or FMCSA. Data comes from public FMCSA datasets and may lag official records by a day or more. Government filings can be made directly with FMCSA at no charge.", "contact": { "name": "MyDotCheck", "email": "hello@mydotcheck.com", "url": "https://mydotcheck.com/developers" }, "termsOfService": "https://mydotcheck.com/terms" }, "servers": [ { "url": "https://mydotcheck.com", "description": "Production (read-only, safe for testing)" } ], "externalDocs": { "url": "https://mydotcheck.com/developers", "description": "Developer guide" }, "security": [], "tags": [ { "name": "carriers" }, { "name": "rules" } ], "paths": { "/api/v1/carriers/{dot}": { "get": { "operationId": "getCarrier", "tags": [ "carriers" ], "summary": "DOT compliance check for one carrier", "description": "Census record, compliance checks (USDOT status, MCS-150, authority, safety rating, out-of-service rates, UCR) and a 24-month inspection summary. Example: 80806.", "parameters": [ { "name": "dot", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,8}$" }, "example": "80806" } ], "responses": { "200": { "description": "Carrier compliance check", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Carrier" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "FMCSA data temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/carriers/batch": { "post": { "operationId": "batchCarriers", "tags": [ "carriers" ], "summary": "Compliance checks for up to 100 USDOT numbers in one call", "description": "Synchronous bulk lookup. Each item succeeds or fails on its own (ok + carrier, or ok=false + error). Send Idempotency-Key to make retries safe: the same key and body replays the stored response with Idempotent-Replayed: true.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (e.g. a UUID). Retries with the same key and body return the original response; reusing a key with a different body returns 422. Keys are kept 24 hours.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DotList" }, "example": { "dots": [ "80806", "54283" ] } } } }, "responses": { "200": { "description": "Per-item results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResult" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused with a different body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/jobs": { "post": { "operationId": "createLookupJob", "tags": [ "carriers" ], "summary": "Async bulk lookup for up to 5000 USDOT numbers", "description": "Returns 202 Accepted with a job id, a Location header and status_url. Poll GET /api/v1/jobs/{id} until status is succeeded; results are kept for 1 hour.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (e.g. a UUID). Retries with the same key and body return the original response; reusing a key with a different body returns 422. Keys are kept 24 hours.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DotList" } } } }, "responses": { "202": { "description": "Job accepted", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused with a different body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/jobs/{id}": { "get": { "operationId": "getLookupJob", "tags": [ "carriers" ], "summary": "Poll a bulk lookup job", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job status (results included once succeeded)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/carriers": { "get": { "operationId": "searchCarriers", "tags": [ "carriers" ], "summary": "Search carriers by name, city or USDOT number", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 }, "example": "swift transportation" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } } ], "responses": { "200": { "description": "Matching carriers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResults" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "FMCSA data temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/mc/{mc}": { "get": { "operationId": "lookupMcNumber", "tags": [ "carriers" ], "summary": "Resolve an MC docket number to its USDOT number", "parameters": [ { "name": "mc", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,8}$" }, "example": "135797" } ], "responses": { "200": { "description": "USDOT number for the MC docket", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McLookup" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "FMCSA data temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/mcs150-due-date": { "get": { "operationId": "mcs150DueDate", "tags": [ "rules" ], "summary": "MCS-150 biennial update deadline for a USDOT number", "description": "Pure calculation from FMCSA's published schedule; no data lookup.", "parameters": [ { "name": "dot", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,8}$" }, "example": "1234567" } ], "responses": { "200": { "description": "Next deadline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mcs150" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/ucr-fee": { "get": { "operationId": "ucrFee", "tags": [ "rules" ], "summary": "Unified Carrier Registration fee for a fleet size", "parameters": [ { "name": "vehicles", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 0 }, "example": 4 }, { "name": "year", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 2027, 2026 ], "default": 2027 } } ], "responses": { "200": { "description": "Fee bracket and amount", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UcrFee" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_dot_number", "invalid_mc_number", "invalid_query", "invalid_vehicles", "invalid_year", "invalid_body", "too_many_items", "not_found", "job_not_found", "idempotency_key_reused", "rate_limited", "upstream_unavailable" ] }, "message": { "type": "string" } } } } }, "Check": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "state": { "type": "string", "enum": [ "ok", "warn", "bad", "info" ] }, "detail": { "type": "string" } } }, "Carrier": { "type": "object", "properties": { "dot": { "type": "string" }, "name": { "type": "string" }, "legal_name": { "type": "string" }, "dba_name": { "type": [ "string", "null" ] }, "city": { "type": "string" }, "state": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "operation": { "type": "string" }, "mc_number": { "type": [ "string", "null" ] }, "mc_active": { "type": [ "boolean", "null" ] }, "power_units": { "type": "integer" }, "drivers": { "type": "integer" }, "safety_rating": { "type": "string" }, "mcs150": { "type": "object", "properties": { "last_filed": { "type": [ "string", "null" ], "format": "date" }, "next_due": { "type": "string", "format": "date" }, "days_until_due": { "type": "integer" }, "state": { "type": "string", "enum": [ "overdue", "due-soon", "ok", "unknown" ] } } }, "inspections_24m": { "type": [ "object", "null" ] }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/Check" } }, "issues": { "type": "integer" }, "page_url": { "type": "string", "format": "uri" } } }, "SearchResults": { "type": "object", "properties": { "query": { "type": "string" }, "count": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "dot": { "type": "string" }, "name": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "power_units": { "type": "integer" }, "active": { "type": "boolean" }, "page_url": { "type": "string" } } } } } }, "DotList": { "type": "object", "required": [ "dots" ], "properties": { "dots": { "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^\\d{1,8}$" } } } }, "BatchResult": { "type": "object", "properties": { "count": { "type": "integer" }, "found": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "dot": { "type": "string" }, "ok": { "type": "boolean" }, "carrier": { "$ref": "#/components/schemas/Carrier" }, "error": { "$ref": "#/components/schemas/Error/properties/error" } } } } } }, "Job": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded" ] }, "total": { "type": "integer" }, "done": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "status_url": { "type": "string", "format": "uri" }, "results": { "type": "array", "items": { "type": "object" } } } }, "McLookup": { "type": "object", "properties": { "mc_number": { "type": "string" }, "dot": { "type": "string" }, "page_url": { "type": "string" }, "api_url": { "type": "string" } } }, "Mcs150": { "type": "object", "properties": { "dot": { "type": "string" }, "next_due": { "type": "string", "format": "date" }, "previous_due": { "type": [ "string", "null" ], "format": "date" }, "month": { "type": "string" }, "year_parity": { "type": "string", "enum": [ "odd", "even" ] }, "rule": { "type": "string" } } }, "UcrFee": { "type": "object", "properties": { "year": { "type": "integer" }, "vehicles": { "type": "integer" }, "bracket": { "type": "integer" }, "fee_usd": { "type": "integer" }, "brackets": { "type": "array", "items": { "type": "object" } }, "source": { "type": "string" } } } } } }