{ "openapi": "3.1.0", "info": { "title": "MOTUS Data Studio API", "version": "2026-09-21", "description": "Live paid Motus v2 surface. Sandbox keys hit a 50-DOT fixture allowlist on GET /v2/profile and GET /v2/profile-lite only (30 req/min). Paid mca_live_ keys are unlimited on all routes ($500/mo, 60 req/min). See https://mds.motorcarrier.ai/docs for full field-by-field documentation. Contact Data (phone, cell_phone, email, contact_name, officer names) is returned by default to paid keys; include=contacts remains accepted as a compatibility no-op.", "termsOfService": "https://mds.motorcarrier.ai/docs/terms", "contact": { "url": "https://mds.motorcarrier.ai/docs" } }, "servers": [{ "url": "https://mds.motorcarrier.ai" }], "security": [{ "bearerAuth": [] }], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer YOUR_API_KEY" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] }, "ProfileCandidate": { "type": "object", "properties": { "dot": { "type": "string" }, "mc": { "type": ["string", "null"] }, "name": { "type": ["string", "null"] } }, "required": ["dot", "mc", "name"] }, "AmbiguousMatchError": { "type": "object", "properties": { "error": { "type": "string" }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileCandidate" } } }, "required": ["error", "candidates"] }, "QuotaFields": { "type": "object", "description": "Quota metadata included on successful responses that expose lookup balance.", "properties": { "lookups_remaining": { "type": "integer", "description": "Metered balance after this request. This may remain 0 for unlimited keys." }, "unlimited": { "type": "boolean", "description": "True when unlimited_pulls is true on the authorizing key; false for metered and sandbox keys." } }, "required": ["lookups_remaining", "unlimited"] }, "Contacts": { "type": "object", "additionalProperties": false, "required": ["phone", "cell_phone", "email", "contact_name"], "description": "Contact Data returned by default to paid keys. Values the subject has opted out of are returned as null. A per-DOT all_contact_data suppression also blanks officers, contact history, and physical/mailing street addresses.", "properties": { "phone": { "type": ["string", "null"], "description": "Primary business phone on file" }, "cell_phone": { "type": ["string", "null"], "description": "Cell phone on file; returned independently even when it equals phone" }, "email": { "type": ["string", "null"], "description": "Primary email on file" }, "contact_name": { "type": ["string", "null"], "description": "Primary contact or officer name on file" } } } }, "parameters": { "profileDot": { "name": "dot", "in": "query", "schema": { "type": "string" }, "description": "USDOT; exactly one of dot, mc, name, vin, phone, or email is required" }, "profileMc": { "name": "mc", "in": "query", "schema": { "type": "string" }, "description": "MC/MX docket, e.g. MC136818; exactly one of dot, mc, name, vin, phone, or email is required" }, "profileName": { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Legal or DBA name contains, 2+ characters; exactly one of dot, mc, name, vin, phone, or email is required; 409 if it matches more than one carrier" }, "profileVin": { "name": "vin", "in": "query", "schema": { "type": "string" }, "description": "VIN from stored MCMIS inspection units; exactly 17 characters after trim/uppercase (A-H, J-N, P, R-Z, 0-9); exactly one of dot, mc, name, vin, phone, or email is required; 409 if it matches more than one carrier" }, "profilePhone": { "name": "phone", "in": "query", "schema": { "type": "string" }, "description": "Exact stored business or cell phone; common punctuation and optional leading +1 normalize to 10 digits; exactly one of dot, mc, name, vin, phone, or email is required; 409 if it matches more than one carrier" }, "profileEmail": { "name": "email", "in": "query", "schema": { "type": "string", "format": "email", "maxLength": 254 }, "description": "Exact stored business email; surrounding whitespace is trimmed and case is normalized to lowercase; exactly one of dot, mc, name, vin, phone, or email is required; 409 if it matches more than one carrier" }, "include": { "name": "include", "in": "query", "required": false, "description": "Compatibility parameter. The only value is contacts (comma-separated or repeated); it is accepted as a no-op because paid responses already include Contact Data by default. Any other value is 400 code invalid_include.", "schema": { "type": "string", "examples": ["contacts"] } } }, "responses": { "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid Bearer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Paid monthly API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409ambiguous": { "description": "mc/name/vin/phone/email matched more than one carrier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmbiguousMatchError" } } } }, "429": { "description": "Too many requests. Sandbox 30/min, paid 60/min.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503contacts": { "description": "The current contact-data suppression check could not run (code contacts_unavailable). Fails closed; no lookup is consumed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": ["contacts_unavailable"] } }, "required": ["error"] } } } } } }, "paths": { "/v2/profile": { "get": { "summary": "Fat warehouse dossier for one carrier", "description": "identity through as-of in a single GET. Provide exactly one of dot, mc, name, vin, phone, or email. Contact Data (contacts, identity.officers and contact rows of contact_history) is returned by default for paid keys; include=contacts is a compatibility no-op.", "parameters": [ { "$ref": "#/components/parameters/profileDot" }, { "$ref": "#/components/parameters/profileMc" }, { "$ref": "#/components/parameters/profileName" }, { "$ref": "#/components/parameters/profileVin" }, { "$ref": "#/components/parameters/profilePhone" }, { "$ref": "#/components/parameters/profileEmail" }, { "$ref": "#/components/parameters/include" } ], "responses": { "200": { "description": "Profile dossier", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QuotaFields" }, { "type": "object", "properties": { "carrier": { "type": "object", "properties": { "authority": { "type": "object", "required": ["current", "operating_authorities", "events", "history"], "properties": { "current": { "type": ["object", "null"], "description": "Current authority snapshot. property_authority is retained for backward compatibility as the primary Motus Carrier file type, preferring Motor Carrier of Property (Except Household Goods) or Motor Carrier of Property when multiple types exist; when operating_authorities is non-empty, that list is authoritative.", "properties": { "property_authority": { "type": ["string", "null"], "description": "Backward-compatible primary operating-authority type from the Motus Carrier file. Prefers Motor Carrier of Property (Except Household Goods) or Motor Carrier of Property when multiple types exist. When operating_authorities is non-empty, use that list as authoritative." } } }, "operating_authorities": { "type": "array", "description": "Authoritative Motus operating-authority list when non-empty, ordered deterministically by payload_order with Motor Carrier of Property (Except Household Goods) or Motor Carrier of Property first, then type, docket number, and status. Empty when no Motus carrier-detail observation is stored.", "items": { "type": "object", "additionalProperties": false, "required": ["operating_authority_type", "docket_number", "operating_authority_status", "payload_order"], "properties": { "operating_authority_type": { "type": "string" }, "docket_number": { "type": "string" }, "operating_authority_status": { "type": "string" }, "payload_order": { "type": "integer", "minimum": 0 } } } }, "events": { "type": "array", "items": { "type": "object" } }, "history": { "type": "array", "items": { "type": "object" } } } }, "insurance": { "type": "array", "description": "Insurance filings on file (all sources). Each filing carries an ESTIMATED expiration: FMCSA filings stay in force until cancelled and no source reports a policy term, so estimated_expiration_date is never a verified expiration date.", "items": { "type": "object", "required": ["id", "estimated_expiration_date", "expiration_basis", "expiration_verified", "renewal_confidence"], "properties": { "id": { "type": "string" }, "docket_number": { "type": ["string", "null"] }, "insurance_type": { "type": ["string", "null"], "description": "Source encoding, e.g. BIPD/Primary, 1 (BIPD), 2 (cargo), 3 (bond), CARGO, SURETY" }, "insurance_class": { "type": ["string", "null"] }, "form_code": { "type": ["string", "null"], "description": "e.g. 91X, BMC-91X, 34, 84" }, "company_name": { "type": ["string", "null"] }, "policy_number": { "type": ["string", "null"] }, "underlying_limit": { "type": ["string", "null"] }, "max_coverage_amount": { "type": ["string", "null"] }, "transaction_date": { "type": ["string", "null"], "format": "date" }, "effective_date": { "type": ["string", "null"], "format": "date" }, "cancel_effective_date": { "type": ["string", "null"], "format": "date", "description": "Cancellation filed with FMCSA, when one is on file" }, "source": { "type": ["string", "null"] }, "estimated_expiration_date": { "type": ["string", "null"], "format": "date", "description": "ESTIMATE, never verified. Next expected expiration of this primary BIPD filing (form 91/91X, BMC-91/91X) as of the renewal index's current as-of date (the America/New_York date; between midnight ET and the nightly refresh, the previous day), from the same rules as the renewal index: a cancellation or replacement filed within 366 days, else a later filing already on file, else the effective-date anniversary rolled forward. null for cargo, bond, excess, surety and cancelled filings." }, "expiration_basis": { "type": ["string", "null"], "enum": ["cancellation_filed", "replacement_filed", "future_policy_effective", "anniversary", "anniversary_rolled", null], "description": "Why the estimate has this date. cancellation_filed / replacement_filed: an explicit future cancellation on file (replacement when another filing starts within a day of it). future_policy_effective: a later filing is already on file. anniversary: effective date + 1 year. anniversary_rolled: an older effective date rolled forward to its next anniversary. null when estimated_expiration_date is null." }, "expiration_verified": { "type": "boolean", "const": false, "description": "Always false: no source reports a policy expiration date." }, "renewal_confidence": { "type": ["string", "null"], "enum": ["event", "modeled", null], "description": "event when the date comes from a filing on record (cancellation, replacement or later filing); modeled when it is an anniversary assumption." } } } }, "contacts": { "$ref": "#/components/schemas/Contacts" }, "identity": { "type": "object", "description": "Carrier identity (more fields than listed here; see /docs).", "properties": { "officers": { "type": "array", "items": { "type": "string" }, "description": "Officer names. Contact Data returned by default for paid keys, regardless of carrier country, unless contact suppression applies." } } }, "contact_history": { "type": "array", "description": "Field-change history. legal_name, dba_name and address rows are returned alongside phone, cell_phone, email and officer rows by default for paid keys, regardless of carrier country; opted-out values are removed. Empty (with officers []) for a carrier whose Contact Data is suppressed as a whole.", "items": { "type": "object" } } } } } } ] } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409ambiguous" }, "429": { "$ref": "#/components/responses/429" }, "503": { "$ref": "#/components/responses/503contacts" } } } }, "/v2/profile-lite": { "get": { "summary": "Lean official identity, address, and fleet after typeahead", "description": "No full dossier, no scores added. Provide exactly one of dot, mc, name, vin, phone, or email.", "parameters": [ { "$ref": "#/components/parameters/profileDot" }, { "$ref": "#/components/parameters/profileMc" }, { "$ref": "#/components/parameters/profileName" }, { "$ref": "#/components/parameters/profileVin" }, { "$ref": "#/components/parameters/profilePhone" }, { "$ref": "#/components/parameters/profileEmail" } ], "responses": { "200": { "description": "Lean carrier profile", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/QuotaFields" }] } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409ambiguous" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v2/carriers": { "get": { "summary": "Paid lean hits for daily lead ingest", "description": "Every carrier with a current primary BIPD filing from any insurance source (FMCSA portal snapshot, Motus active feed, Motus portal), filtered by power units, estimated expiration window (renewal_days_* or renewal_date_*), physical state, operating status, FMCSA authority and MC number. Sorted by estimated_expiration_date asc, then DOT asc. Dates are Otto estimates (expiration_verified is always false). operating_authority_type is the nullable primary type from the Motus Carrier file, prefers Motor Carrier of Property (Except Household Goods) or Motor Carrier of Property when multiple types exist, never emits legacy Y/N flags, and is never inferred from common/contract/broker status. Until the first nightly index refresh succeeds the list is served from the previous Motus observation set (meta.source); the authority filter needs the index and returns 503 filter_unavailable until then. Each hit includes a contacts object by default for paid keys; include=contacts is a compatibility no-op. Requires a paid mca_live_ key.", "parameters": [ { "name": "power_units_min", "in": "query", "schema": { "type": "integer", "default": 11, "minimum": 0, "maximum": 1000000 } }, { "name": "renewal_days_min", "in": "query", "schema": { "type": "integer", "default": 85, "minimum": 0, "maximum": 365 }, "description": "Inclusive days from the current UTC date, applied to estimated_expiration_date. Cannot be combined with renewal_date_min/renewal_date_max." }, { "name": "renewal_days_max", "in": "query", "schema": { "type": "integer", "default": 95, "minimum": 0, "maximum": 365 }, "description": "Inclusive days from the current UTC date, applied to estimated_expiration_date. Cannot be combined with renewal_date_min/renewal_date_max." }, { "name": "renewal_date_min", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Inclusive ISO date (UTC today..today+365) applied to estimated_expiration_date. Send with renewal_date_max instead of renewal_days_min/renewal_days_max (400 if combined)." }, { "name": "renewal_date_max", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Inclusive ISO date (UTC today..today+365), on or after renewal_date_min." }, { "name": "state", "in": "query", "schema": { "type": "string", "example": "TX,OH" }, "description": "Comma-separated 2-letter physical_state codes to include (case-insensitive, max 60). Codes FMCSA does not use are a 400. Cannot be combined with exclude_state or lower48." }, { "name": "exclude_state", "in": "query", "schema": { "type": "string", "example": "NY,MA" }, "description": "Comma-separated 2-letter physical_state codes to exclude (max 60); carriers with no physical state are excluded too. With lower48=true, removes those codes from the lower-48 set." }, { "name": "lower48", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "true limits to the 48 contiguous states plus DC (DC is included; no AK, HI, territories, Canada or Mexico)." }, { "name": "operating_status", "in": "query", "schema": { "type": "string", "enum": ["any", "active"], "default": "any" }, "description": "Default any keeps every carrier regardless of census status_code; active keeps status_code A (active USDOT registration)." }, { "name": "authority", "in": "query", "schema": { "type": "string", "enum": ["any", "common", "contract", "broker", "any_active", "none"], "default": "any" }, "description": "FMCSA operating authority status is Active: common, contract or broker (broker authority counts as an authority, including for any_active and none); any_active = at least one of the three Active; none = none Active, including carriers with no authority record." }, { "name": "has_mc", "in": "query", "schema": { "type": "boolean" }, "description": "true keeps carriers with an MC number, false keeps carriers without one; omit for both." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque next_cursor from a prior response; it fixes every filter, so send no filter parameters with it (400). A blank value (e.g. state=) counts as omitted, with or without a cursor. A cursor issued by the pre-index observation list returns 400 cursor_expired once the index is live; restart without cursor." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500 } }, { "$ref": "#/components/parameters/include" } ], "responses": { "200": { "description": "Carrier list page", "content": { "application/json": { "schema": { "type": "object", "required": ["carriers", "pagination", "meta"], "properties": { "carriers": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["dot", "name", "power_units", "inferred_renewal_date", "days_to_renewal", "state", "mc_number", "status_code", "estimated_expiration_date", "expiration_basis", "renewal_confidence", "expiration_verified", "bipd_sources", "insurer", "latest_effective_date", "operating_authority_type"], "properties": { "dot": { "type": "string" }, "name": { "type": ["string", "null"] }, "power_units": { "type": ["integer", "null"] }, "inferred_renewal_date": { "type": "string", "format": "date", "deprecated": true, "description": "Deprecated alias of estimated_expiration_date, kept for existing integrations" }, "days_to_renewal": { "type": "integer", "description": "estimated_expiration_date minus the current UTC date, computed per request" }, "state": { "type": ["string", "null"] }, "mc_number": { "type": ["string", "null"] }, "status_code": { "type": ["string", "null"], "description": "Census operating status (A, I, P)" }, "estimated_expiration_date": { "type": "string", "format": "date", "description": "Otto estimate of the next BIPD expiration; not an FMCSA-filed date" }, "expiration_basis": { "type": "string", "enum": ["cancellation_filed", "replacement_filed", "future_policy_effective", "anniversary", "anniversary_rolled"], "description": "cancellation_filed / replacement_filed: an explicit future cancellation; future_policy_effective: a newer filing already on file; anniversary: one year after the latest effective date; anniversary_rolled: a later anniversary of an older effective date" }, "renewal_confidence": { "type": "string", "enum": ["event", "modeled"], "description": "event for filed cancellations and future filings; modeled for anniversaries" }, "expiration_verified": { "type": "boolean", "const": false, "description": "Always false: no source reports a policy term" }, "bipd_sources": { "type": "array", "items": { "type": "string" }, "description": "Insurance sources reporting the carrier's current BIPD filings" }, "insurer": { "type": ["string", "null"] }, "latest_effective_date": { "type": ["string", "null"], "format": "date", "description": "Latest in-force BIPD effective date" }, "operating_authority_type": { "type": ["string", "null"], "description": "Primary operating-authority type from the Motus Carrier file; null when Motus has no type or stored a legacy Y/N flag. Prefers Motor Carrier of Property (Except Household Goods) or Motor Carrier of Property when multiple types exist. Never inferred from common/contract/broker status." }, "contacts": { "$ref": "#/components/schemas/Contacts", "description": "Returned by default to paid keys; include=contacts is a compatibility no-op" } } } }, "pagination": { "type": "object", "required": ["limit", "total", "next_cursor"], "properties": { "limit": { "type": "integer" }, "total": { "type": "integer", "description": "Fixed from the first page" }, "next_cursor": { "type": ["string", "null"], "description": "Pass as cursor; null is the stop condition" } } }, "meta": { "type": "object", "required": ["source", "as_of_date"], "properties": { "source": { "type": "string", "enum": ["carrier_renewal_index", "insurance_renewal_observations"] }, "as_of_date": { "type": ["string", "null"], "format": "date", "description": "Date of the index refresh that produced the estimates; null on the observation fallback" } } } } } } } }, "400": { "description": "Invalid filter value (unknown state code, conflicting filters, out-of-range date or number), filters sent with a cursor, or an invalid cursor; code cursor_expired means restart without cursor. include values other than contacts: code invalid_include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": ["cursor_expired"] } }, "required": ["error"] } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "description": "Paid monthly API key required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/429" }, "503": { "description": "Temporarily unavailable, retry later; code filter_unavailable means the authority filter is waiting for the first all-source index refresh; code contacts_unavailable means the contact-data suppression check could not run (fails closed, uncharged)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": ["filter_unavailable", "contacts_unavailable"] } }, "required": ["error"] } } } } } } }, "/v2/exports": { "post": { "summary": "Export: enqueue", "description": "Queues an async CSV export over the same all-source universe, filters, and order as GET /v2/carriers, up to 10,000 rows. Takes the GET /v2/carriers filter names in a JSON body; booleans as JSON true/false or the strings true/false and integers as JSON integers or digit strings are accepted. Max 3 queued/building exports per owner and one paid lookup on enqueue. CSVs append operating_authority_type (the nullable primary Motus Carrier file type, with legacy Y/N flags emitted as null) and include phone, cell_phone, email and contact_name by default; include=contacts is accepted as a no-op. Contact values are suppression-filtered during the build and rechecked through the authenticated download before serving. authority (other than any) returns 503 filter_unavailable until the first all-source index refresh.", "parameters": [{ "$ref": "#/components/parameters/include" }], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "power_units_min": { "type": "integer", "default": 11, "minimum": 0, "maximum": 1000000, "description": "Integer or digit string" }, "renewal_days_min": { "type": "integer", "default": 85, "minimum": 0, "maximum": 365, "description": "Integer or digit string" }, "renewal_days_max": { "type": "integer", "default": 95, "minimum": 0, "maximum": 365, "description": "Integer or digit string" }, "renewal_date_min": { "type": "string", "format": "date", "description": "Same as GET /v2/carriers renewal_date_min" }, "renewal_date_max": { "type": "string", "format": "date", "description": "Same as GET /v2/carriers renewal_date_max" }, "state": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }], "description": "Codes to include, e.g. \"TX,OH\" or [\"TX\", \"OH\"]" }, "exclude_state": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }], "description": "Codes to exclude, e.g. [\"NY\", \"MA\"]" }, "lower48": { "type": "boolean", "default": false, "description": "48 contiguous states plus DC (DC is included). true/false or \"true\"/\"false\"" }, "operating_status": { "type": "string", "enum": ["any", "active"], "default": "any", "description": "Default any keeps every carrier regardless of census status_code; active keeps status_code A" }, "authority": { "type": "string", "enum": ["any", "common", "contract", "broker", "any_active", "none"], "default": "any", "description": "Active FMCSA authority; broker counts as an authority (also for any_active and none); none includes carriers with no authority record. Other than any: 503 filter_unavailable, uncharged, until the first index refresh" }, "has_mc": { "type": "boolean", "description": "true/false or \"true\"/\"false\"; omit for both" }, "email_when_ready": { "type": "boolean", "default": false, "description": "Best-effort email when the CSV is ready" }, "include": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }], "description": "Same as the include query parameter: \"contacts\" or [\"contacts\"]" } } } } } }, "responses": { "201": { "description": "Export queued", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QuotaFields" }, { "type": "object", "required": ["id", "state", "include_contacts"], "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": ["queued", "building", "ready", "failed", "expired"] }, "include_contacts": { "type": "boolean", "description": "true for paid exports, which include contact columns by default" } } } ] } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "description": "Paid monthly API key required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "You already have 3 exports in progress", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": ["error"] } } } }, "429": { "$ref": "#/components/responses/429" }, "502": { "description": "Export service temporarily unavailable, retry later" }, "503": { "description": "Temporarily unavailable, retry later; code filter_unavailable means the authority filter is waiting for the first all-source index refresh; code contacts_unavailable means a contact-data suppression check failed closed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": ["filter_unavailable", "contacts_unavailable"] } }, "required": ["error"] } } } } } } }, "/v2/exports/{id}": { "get": { "summary": "Export: status", "description": "Polls an owned export job. url is a short-lived signed CSV link, present only when state is ready; request status again for a fresh link. Does not consume a lookup.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Export job id from the enqueue response" } ], "responses": { "200": { "description": "Export status", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QuotaFields" }, { "type": "object", "required": ["id", "state", "url", "error", "row_count", "include_contacts"], "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": ["queued", "building", "ready", "failed", "expired"] }, "url": { "type": ["string", "null"], "format": "uri", "description": "Absolute short-lived signed CSV URL; request status again for a fresh link" }, "error": { "type": ["string", "null"] }, "row_count": { "type": ["integer", "null"] }, "include_contacts": { "type": "boolean", "description": "true when the export includes the contact columns (include=contacts)" } } } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "502": { "description": "Export service temporarily unavailable, retry later" } } } }, "/v2/autocomplete": { "get": { "summary": "Paid typeahead over DOT, MC, legal name, or DBA", "description": "Lean hits, no risk claim. Requires a paid mca_live_ key.", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 }, "description": "Accepts DOT, MC, legal name, or DBA name" } ], "responses": { "200": { "description": "Autocomplete hits", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/QuotaFields" }] } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v2/monitoring": { "get": { "summary": "Monitoring: list", "description": "Lists DOTs your paid key monitors — identity from the stored watch snapshot, not a fresh dossier pull.", "responses": { "200": { "description": "Watch list", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/QuotaFields" }] } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" } } }, "post": { "summary": "Monitoring: add", "description": "Adds a DOT to the paid monitoring list — seeds a full snapshot when available, with a partial census snapshot for very large carriers. 201 newly watched; 200 already on list; 404 not in warehouse; 409 at capacity.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dot_number": { "type": "string", "description": "USDOT (or use dot alias)" }, "dot": { "type": "string", "description": "Accepted alias for dot_number" } } } } } }, "responses": { "200": { "description": "Already on list", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/QuotaFields" }] } } } }, "201": { "description": "Newly watched", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/QuotaFields" }] } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Monitoring list is at capacity" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v2/monitoring/{dot}": { "delete": { "summary": "Monitoring: remove", "description": "Removes a DOT from the paid monitoring list. 404 if not currently on the list.", "parameters": [ { "name": "dot", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/QuotaFields" }] } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v2/monitoring/events": { "get": { "summary": "Monitoring: events", "description": "Cursor-paged change feed for watched DOTs — honest warehouse fields only, areas limited to authority, insurance, and safety.", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor from a prior response's next_cursor" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 } } ], "responses": { "200": { "description": "Change feed page", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/QuotaFields" }] } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v2/monitoring/webhooks": { "get": { "summary": "Webhooks: list", "description": "Lists active webhook registrations for the key's account — no secrets returned.", "responses": { "200": { "description": "Webhook list", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" } } }, "post": { "summary": "Webhooks: register", "description": "Registers an https:// endpoint to receive signed POSTs for new monitoring events instead of polling. The secret is returned once at creation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "https:// endpoint" } }, "required": ["url"] } } } }, "responses": { "201": { "description": "Webhook registered", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v2/monitoring/webhooks/{id}": { "delete": { "summary": "Webhooks: revoke", "description": "Revokes a webhook — delivery stops immediately. 404 if the id isn't an active webhook owned by this key's account.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook id from register/list" } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/api/privacy/opt-out": { "post": { "summary": "Contact opt-out: request", "description": "Public, no API key. Starts a contact opt-out for an email address, with an optional phone number and USDOT number. We email a one-time confirmation link (valid 24 hours) to that address; the opt-out takes effect only after the person opens the link and presses Confirm. Once confirmed, the email is returned as null on GET /v2/profile, GET /v2/carriers, exports and Studio, and is skipped by outreach. The phone is suppressed (for that carrier only) when it is on file with the verified email for that USDOT number; otherwise our team reviews it within 10 business days. The response is identical whether or not we hold the address. Limited per IP, per email address (3 a day) and overall. Human page: https://mds.motorcarrier.ai/opt-out. Privacy email: privacy@motorcarrier.ai.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["email"], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254, "description": "Required. Trimmed and lowercased." }, "phone": { "type": "string", "maxLength": 40, "description": "Optional. 10-digit US number or E.164." }, "dot_number": { "type": "string", "pattern": "^[0-9]{1,8}$", "description": "Optional. The phone is suppressed for this carrier when it and the verified email are both on file for it; otherwise it is reviewed within 10 business days." } } } } } }, "responses": { "202": { "description": "Accepted. Same body for every valid request.", "content": { "application/json": { "schema": { "type": "object", "required": ["ok", "message"], "properties": { "ok": { "type": "boolean", "const": true }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid email, phone or dot_number (field names which)" }, "429": { "description": "Too many requests from this IP or for this email; retry in an hour" }, "502": { "description": "Confirmation email could not be sent; retry later" }, "503": { "description": "Temporarily unavailable; retry later" } } } } } }