{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://artifacts.apis.io/entitylight/json-schema/entitylight-lookup-schema.json", "title": "Lookup", "x-generated": "2026-10-30", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/entitylight-openapi.json#/components/schemas/Lookup", "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" ] }, "businessName": { "description": "The name searched; null when the lookup searched a state ID", "type": [ "string", "null" ] }, "sosId": { "description": "The state ID searched; null when the lookup searched a name", "type": [ "string", "null" ] }, "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" ] }, "address": { "anyOf": [ { "type": "object", "properties": { "street": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] } }, "required": [ "street", "city", "zip" ], "additionalProperties": false }, { "type": "null" } ], "description": "The address sent to pick the business; null when none was sent" }, "watchId": { "anyOf": [ { "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)$" }, { "type": "null" } ], "description": "The watch whose check ran this lookup, or that was started from it; null otherwise" }, "watching": { "type": "boolean", "description": "watchId's watch is still active" }, "pickedFromLookupId": { "anyOf": [ { "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)$" }, { "type": "null" } ], "description": "The lookup that needed a pick and was picked into this one, or null" }, "pickedLookupId": { "anyOf": [ { "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)$" }, { "type": "null" } ], "description": "The newest lookup picked from this one's businessAlternatives, or null" }, "createdAt": { "type": "string", "description": "ISO 8601" }, "completedAt": { "description": "ISO 8601", "type": [ "string", "null" ] }, "coverage": { "type": "object", "properties": { "business": { "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 }, "businessPage": { "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": "Reading the business's own page on the state site: screenshot, documents and the fields the page shows" }, "ucc": { "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 }, "uccDetails": { "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": "Reading each UCC filing's details from the filing office (its own pages, or the data it publishes in CO and CT): party addresses and image links" }, "newYorkCourts": { "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 }, "miamiDadeCourts": { "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 }, "browardCourts": { "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 } }, "required": [ "business", "businessPage", "ucc", "uccDetails", "newYorkCourts", "miamiDadeCourts", "browardCourts" ], "additionalProperties": false, "description": "Per area: searched, not_covered, failed, or pending while the lookup runs. A failed area was not searched; it never means no records." }, "business": { "anyOf": [ { "type": "object", "properties": { "legalName": { "type": "string" }, "matchScore": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How closely legalName matches the name searched, 0 to 100, ignoring case, punctuation and legal suffixes. The business found is always 100: its name matches exactly, or it has the state ID searched" }, "state": { "type": "string" }, "sosId": { "description": "The state's own id for the business", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "statusDate": { "description": "YYYY-MM-DD. When the current status took effect, where the state publishes it", "type": [ "string", "null" ] }, "inactiveDate": { "description": "YYYY-MM-DD. When the business was dissolved or closed, where the state publishes it", "type": [ "string", "null" ] }, "entityType": { "description": "As the state records it", "type": [ "string", "null" ] }, "formationDate": { "description": "YYYY-MM-DD", "type": [ "string", "null" ] }, "stateOfFormation": { "type": [ "string", "null" ] }, "registeredAgent": { "type": [ "string", "null" ] }, "registeredAgentAddress": { "type": [ "string", "null" ] }, "serviceOfProcessName": { "description": "Who receives service of process, where the state lists it separately from the registered agent (New York, for example)", "type": [ "string", "null" ] }, "serviceOfProcessAddress": { "type": [ "string", "null" ] }, "principalAddress": { "type": [ "string", "null" ] }, "mailingAddress": { "type": [ "string", "null" ] }, "agentIsCommercial": { "description": "true when the state marks the registered agent as a commercial registered agent; null when it doesn't say", "type": [ "boolean", "null" ] }, "ein": { "description": "The federal EIN, where the state prints it", "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "industry": { "description": "As the state records it", "type": [ "string", "null" ] }, "lastAnnualReportYear": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "nextReportDue": { "description": "YYYY-MM-DD", "type": [ "string", "null" ] }, "officers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } }, "required": [ "name", "title", "address" ], "additionalProperties": false }, "description": "Officers, managers and directors as the state lists them" }, "filingHistory": { "type": "array", "items": { "type": "object", "properties": { "filingNumber": { "type": [ "string", "null" ] }, "filingType": { "type": [ "string", "null" ] }, "filedDate": { "description": "YYYY-MM-DD, or YYYY-MM or YYYY where the state publishes only the month or year", "type": [ "string", "null" ] }, "effectiveDate": { "description": "Same format as filedDate", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } }, "required": [ "filingNumber", "filingType", "filedDate", "effectiveDate", "status" ], "additionalProperties": false }, "description": "Filings on record with the state, newest first, where the state publishes them" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "filedDate": { "description": "YYYY-MM-DD", "type": [ "string", "null" ] }, "name": { "type": "string", "description": "The document name as the state prints it" }, "url": { "description": "The state's own link to the filed document", "type": [ "string", "null" ] } }, "required": [ "filedDate", "name", "url" ], "additionalProperties": false }, "description": "Filed documents the state's page lists, with links to them, in the page's order" }, "screenshotUrl": { "description": "A screenshot of the state's page for this business, taken when the lookup ran. Send your API key; the response redirects to the image", "type": [ "string", "null" ] }, "sourceUrl": { "type": [ "string", "null" ] }, "sourceAsOf": { "description": "ISO 8601. When the state data was published, for states read from a published data file; null when read live", "type": [ "string", "null" ] } }, "required": [ "legalName", "matchScore", "state", "sosId", "status", "statusDate", "inactiveDate", "entityType", "formationDate", "stateOfFormation", "registeredAgent", "registeredAgentAddress", "serviceOfProcessName", "serviceOfProcessAddress", "principalAddress", "mailingAddress", "agentIsCommercial", "ein", "email", "phone", "industry", "lastAnnualReportYear", "nextReportDue", "officers", "filingHistory", "documents", "screenshotUrl", "sourceUrl", "sourceAsOf" ], "additionalProperties": false }, { "type": "null" } ] }, "businessAlternatives": { "type": "array", "items": { "type": "object", "properties": { "legalName": { "type": "string", "description": "When sosId is null, send it to POST /lookups/{id}/pick to look this one up" }, "matchScore": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How closely legalName matches the name searched, 0 to 100, ignoring case, punctuation and legal suffixes. The business found is always 100: its name matches exactly, or it has the state ID searched" }, { "type": "null" } ], "description": "How closely legalName matches the name searched, 0 to 100, ignoring case, punctuation and legal suffixes; null when the lookup searched a state ID" }, "exactName": { "type": "boolean", "description": "legalName matches the name searched exactly, ignoring case, punctuation and legal suffixes" }, "sosId": { "description": "The state's own id for the registration. Send it to POST /lookups/{id}/pick to look this one up", "type": [ "string", "null" ] }, "state": { "type": "string" }, "status": { "description": "As the state records it; only for exact names", "type": [ "string", "null" ] }, "entityType": { "description": "As the state records it; only for exact names", "type": [ "string", "null" ] }, "formationDate": { "description": "YYYY-MM-DD; only for exact names", "type": [ "string", "null" ] }, "registeredAgent": { "description": "Only for exact names", "type": [ "string", "null" ] }, "principalAddress": { "description": "As the state prints it; only for exact names", "type": [ "string", "null" ] } }, "required": [ "legalName", "matchScore", "exactName", "sosId", "state", "status", "entityType", "formationDate", "registeredAgent", "principalAddress" ], "additionalProperties": false }, "description": "Registrations matching or close to the name searched, when the lookup needs a pick: exact names first, then highest matchScore. Pick one with POST /lookups/{id}/pick." }, "uccSummary": { "anyOf": [ { "type": "object", "properties": { "filingsRead": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "UCC filings read for this business; uccFilings lists them all" }, "activeFilings": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "truncated": { "type": "boolean", "description": "The filing office has more filings than one search reads. uccFilings holds the newest filingsRead of them" } }, "required": [ "filingsRead", "activeFilings", "truncated" ], "additionalProperties": false }, { "type": "null" } ] }, "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 } }, "courtCases": { "type": "array", "items": { "type": "object", "properties": { "coverageArea": { "type": "string", "enum": [ "newYorkCourts", "miamiDadeCourts", "browardCourts" ], "description": "The coverage area whose search found this case" }, "court": { "type": "string" }, "caseNumber": { "type": "string", "description": "The court's own case number" }, "stateCaseNumber": { "description": "Florida's uniform case number, where the court prints it", "type": [ "string", "null" ] }, "consolidatedCaseNumber": { "type": [ "string", "null" ] }, "judicialSection": { "type": [ "string", "null" ] }, "filingDate": { "description": "YYYY-MM-DD", "type": [ "string", "null" ] }, "caseType": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "plaintiffs": { "type": "array", "items": { "type": "string" }, "description": "Company plaintiffs as the court printed them; individuals are never returned" }, "defendants": { "type": "array", "items": { "type": "string" }, "description": "Company defendants as the court printed them; individuals are never returned" }, "sourceUrl": { "type": [ "string", "null" ] } }, "required": [ "coverageArea", "court", "caseNumber", "stateCaseNumber", "consolidatedCaseNumber", "judicialSection", "filingDate", "caseType", "status", "plaintiffs", "defendants", "sourceUrl" ], "additionalProperties": false } }, "watchCheck": { "anyOf": [ { "type": "object", "properties": { "isBaseline": { "type": "boolean", "description": "The watch's first check, which sets what later checks compare against" }, "hasChanges": { "type": "boolean" }, "highestSeverity": { "anyOf": [ { "type": "string", "enum": [ "high", "medium", "low" ] }, { "type": "null" } ] }, "changes": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "ucc_filing" }, "filingNumber": { "type": "string" }, "securedPartyName": { "type": "string" }, "filingDate": { "description": "YYYY-MM-DD", "type": [ "string", "null" ] } }, "required": [ "kind", "filingNumber", "securedPartyName", "filingDate" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "court_case" }, "court": { "type": "string" }, "caseNumber": { "type": "string" }, "plaintiffs": { "type": "array", "items": { "type": "string" } }, "filingDate": { "description": "YYYY-MM-DD", "type": [ "string", "null" ] } }, "required": [ "kind", "court", "caseNumber", "plaintiffs", "filingDate" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "business" }, "change": { "type": "object", "properties": { "field": { "type": "string" }, "action": { "type": "string", "enum": [ "changed", "added", "removed" ] }, "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "severity": { "type": "string", "enum": [ "high", "medium", "low" ] }, "category": { "type": "string", "enum": [ "name", "status", "entity", "agent", "address", "officers", "filings" ] } }, "required": [ "field", "action", "from", "to", "severity", "category" ], "additionalProperties": false } }, "required": [ "kind", "change" ], "additionalProperties": false } ] }, "description": "State record changes (highest severity first), then new lawsuits, then new UCC filings since the previous check" } }, "required": [ "isBaseline", "hasChanges", "highestSeverity", "changes" ], "additionalProperties": false }, { "type": "null" } ], "description": "What this lookup found changed, when it ran as a watch check; null otherwise" } }, "required": [ "id", "status", "businessName", "sosId", "state", "address", "watchId", "watching", "pickedFromLookupId", "pickedLookupId", "createdAt", "completedAt", "coverage", "business", "businessAlternatives", "uccSummary", "uccFilings", "courtCases", "watchCheck" ], "additionalProperties": false }