{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/carrierscrub-com/json-schema/carrierscrub-com-verdict-schema.json",
  "title": "Verdict",
  "x-generated": "2026-11-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/carrierscrub-com-openapi.json#/components/schemas/Verdict",
  "type": "object",
  "required": [
    "dot_number",
    "verdict",
    "reasons",
    "data_as_of",
    "record_source",
    "record_as_of"
  ],
  "properties": {
    "dot_number": {
      "type": "string"
    },
    "legal_name": {
      "type": [
        "string",
        "null"
      ]
    },
    "location": {
      "type": [
        "string",
        "null"
      ]
    },
    "verdict": {
      "type": "string",
      "enum": [
        "GO",
        "CAUTION",
        "STOP"
      ]
    },
    "reasons": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "code",
          "detail"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "A reason code, e.g. OUT_OF_SERVICE_ORDER."
          },
          "detail": {
            "type": "string",
            "description": "Plain-language statement of the dated FMCSA fact."
          }
        }
      }
    },
    "days_until_suspension": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Days until an already-served revocation takes effect, when dated."
    },
    "data_as_of": {
      "type": "string",
      "description": "When CarrierScrub read this record."
    },
    "record_source": {
      "type": "string",
      "enum": [
        "motus",
        "legacy"
      ],
      "description": "Which FMCSA record the verdict rests on."
    },
    "record_as_of": {
      "type": "string",
      "format": "date",
      "description": "That record's date. A legacy record is as of 2026-05-14 at the latest."
    },
    "freshness": {
      "type": "object",
      "description": "How current this answer is. Check it before relying on a GO: a stored answer is CarrierScrub's saved record, with FMCSA's out-of-service orders and current authority, insurance and suspension notices re-checked on their own (see reasons).",
      "properties": {
        "source": {
          "type": "string",
          "enum": [
            "live",
            "stored"
          ],
          "description": "live: read from FMCSA for this request. stored: a saved answer."
        },
        "stale": {
          "type": "boolean",
          "description": "Part of the answer is not current: a stored answer more than 24 hours old, or the safety record could not be read."
        },
        "live_check_failed": {
          "type": "boolean",
          "description": "A live check was tried and FMCSA did not answer, so this is the stored answer."
        }
      }
    },
    "safety": {
      "type": [
        "object",
        "null"
      ],
      "description": "FMCSA safety rating with its date, 24-month roadside inspection and out-of-service counts, crash counts, and any acute or critical investigation finding, dated to the SMS snapshot (as_of). Most carriers have never been rated; that is not a finding."
    },
    "authority_granted_on": {
      "type": [
        "string",
        "null"
      ],
      "format": "date"
    },
    "authority_reinstated_on": {
      "type": [
        "string",
        "null"
      ],
      "format": "date"
    },
    "record_changes": {
      "type": [
        "object",
        "null"
      ],
      "description": "What changed on the carrier's FMCSA record and the day CarrierScrub's daily archive saw it, newest first. A fact beside the verdict, never a reason. null until the archive has a complete baseline; an empty events list means none seen since `since`. A phone is shown by its last four digits, an email by its domain, an address by its city and state. `control_notice` may also be set; see below.",
      "properties": {
        "since": {
          "type": "string",
          "format": "date"
        },
        "events": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "seen",
              "source",
              "text"
            ],
            "properties": {
              "seen": {
                "type": "string",
                "format": "date"
              },
              "source": {
                "type": "string",
                "enum": [
                  "census",
                  "motus"
                ]
              },
              "text": {
                "type": "string"
              },
              "filed": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date",
                "description": "The MCS-150 filing that came with a census change."
              }
            }
          }
        },
        "control_notice": {
          "type": [
            "object",
            "null"
          ],
          "description": "Set when an established carrier (registered with FMCSA three or more years) had its company officers and a phone, email or address change within a week of each other, in the last 30 days. A notice to confirm who you are dealing with: never a reason code, and it does not change the verdict. Most carriers it appears on have done nothing wrong; a sale or a retirement looks the same on FMCSA's record. null when there is none.",
          "properties": {
            "seen": {
              "type": "string",
              "format": "date"
            },
            "text": {
              "type": "string"
            }
          },
          "required": [
            "seen",
            "text"
          ]
        }
      }
    }
  }
}