{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/entitylight/json-schema/entitylight-ucc-search-schema.json",
  "title": "UccSearch",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/entitylight-openapi.json#/components/schemas/UccSearch",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "status": {
      "type": "string",
      "enum": [
        "running",
        "completed"
      ]
    },
    "debtorName": {
      "type": "string",
      "description": "The debtor name searched"
    },
    "state": {
      "type": "string",
      "enum": [
        "AL",
        "AK",
        "AZ",
        "AR",
        "CA",
        "CO",
        "CT",
        "DE",
        "DC",
        "FL",
        "GA",
        "HI",
        "ID",
        "IL",
        "IN",
        "IA",
        "KS",
        "KY",
        "LA",
        "ME",
        "MD",
        "MA",
        "MI",
        "MN",
        "MS",
        "MO",
        "MT",
        "NE",
        "NV",
        "NH",
        "NJ",
        "NM",
        "NY",
        "NC",
        "ND",
        "OH",
        "OK",
        "OR",
        "PA",
        "RI",
        "SC",
        "SD",
        "TN",
        "TX",
        "UT",
        "VT",
        "VA",
        "WA",
        "WV",
        "WI",
        "WY"
      ]
    },
    "createdAt": {
      "type": "string",
      "description": "ISO 8601"
    },
    "completedAt": {
      "description": "ISO 8601",
      "type": [
        "string",
        "null"
      ]
    },
    "coverage": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "searched",
            "not_covered",
            "failed"
          ]
        },
        "reason": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "not_found",
                "ambiguous",
                "too_many_results",
                "not_run",
                "unavailable"
              ]
            },
            {
              "type": "null"
            }
          ],
          "description": "Set only when status is failed. not_found: no business is registered under that exact name in that state (see businessAlternatives). ambiguous: the name matches more than one registration, or only close ones; pick one from businessAlternatives with POST /lookups/{id}/pick. too_many_results: the court listed more cases than could be read; courtCases still holds the cases that were read, and older ones may be missing. not_run: the lookup ended before this source ran. unavailable: the source didn't answer after retries."
        }
      },
      "required": [
        "status",
        "reason"
      ],
      "additionalProperties": false,
      "description": "searched, not_covered, failed, or pending while the search runs. A failed search found nothing because nothing was searched; it never means no filings."
    },
    "filingsFound": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "Filings whose debtor matches debtorName exactly, ignoring case, punctuation and legal suffixes"
    },
    "totalOnSite": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "The result count the filing office printed, where it prints one; it can include other debtors' filings"
    },
    "truncated": {
      "type": "boolean",
      "description": "The filing office listed more pages than one search reads, so older filings may be missing"
    },
    "uccFilings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "state": {
            "type": "string"
          },
          "filingNumber": {
            "type": "string"
          },
          "filingType": {
            "type": [
              "string",
              "null"
            ]
          },
          "filingDate": {
            "description": "YYYY-MM-DD",
            "type": [
              "string",
              "null"
            ]
          },
          "lapseDate": {
            "description": "YYYY-MM-DD",
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": [
              "string",
              "null"
            ]
          },
          "debtorName": {
            "description": "The debtor as filed",
            "type": [
              "string",
              "null"
            ]
          },
          "securedPartyName": {
            "type": "string"
          },
          "securedPartyAddress": {
            "type": [
              "string",
              "null"
            ]
          },
          "collateralText": {
            "type": [
              "string",
              "null"
            ]
          },
          "imageUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "sourceUrl": {
            "description": "The filing's own page on the filing office's site, where the office gives each filing a plain link",
            "type": [
              "string",
              "null"
            ]
          },
          "throughRepresentative": {
            "type": "boolean",
            "description": "The secured party filed as a representative (a filing agent), so the actual lender isn't on the record"
          },
          "debtors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "As filed"
                },
                "address": {
                  "description": "As the filing office prints it; null where its free search doesn't show addresses",
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "name",
                "address"
              ],
              "additionalProperties": false
            },
            "description": "Every debtor on the filing, with addresses where the filing office's free search shows them"
          },
          "securedParties": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "As filed"
                },
                "address": {
                  "description": "As the filing office prints it; null where its free search doesn't show addresses",
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "name",
                "address"
              ],
              "additionalProperties": false
            },
            "description": "Every secured party on the filing, with addresses where the filing office's free search shows them"
          }
        },
        "required": [
          "state",
          "filingNumber",
          "filingType",
          "filingDate",
          "lapseDate",
          "status",
          "debtorName",
          "securedPartyName",
          "securedPartyAddress",
          "collateralText",
          "imageUrl",
          "sourceUrl",
          "throughRepresentative",
          "debtors",
          "securedParties"
        ],
        "additionalProperties": false
      },
      "description": "Newest first. Addresses and image links are read for the newest 30"
    }
  },
  "required": [
    "id",
    "status",
    "debtorName",
    "state",
    "createdAt",
    "completedAt",
    "coverage",
    "filingsFound",
    "totalOnSite",
    "truncated",
    "uccFilings"
  ],
  "additionalProperties": false
}