{ "openapi": "3.1.0", "info": { "title": "govfiles Corporate Entity API", "version": "0.2.0", "description": "Search US business entity records and resolve physical local businesses to their legal operators and published principals." }, "servers": [ { "url": "https://api.govfiles.dev" } ], "paths": { "/v2/jurisdictions": { "get": { "tags": [ "Companies" ], "summary": "List supported jurisdictions", "description": "List the jurisdiction codes currently loaded and queryable in the API.", "operationId": "listJurisdictionsV2", "responses": { "200": { "description": "Jurisdiction codes currently loaded and queryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JurisdictionsResponse" } } } }, "401": { "description": "Missing or invalid API key." }, "422": { "description": "Validation error." } }, "security": [ { "ApiKeyAuth": [] } ], "parameters": [] } }, "/v2/credits": { "get": { "tags": [ "Account" ], "summary": "Check remaining credits", "description": "Return the remaining API credit balance for the account tied to the API key.", "operationId": "getCreditsV2", "responses": { "200": { "description": "Remaining credit balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditBalanceResponse" } } } }, "401": { "description": "Missing or invalid API key." }, "422": { "description": "Validation error." } }, "security": [ { "ApiKeyAuth": [] } ], "parameters": [] } }, "/v2/companies/search": { "post": { "tags": [ "Companies" ], "summary": "Search companies", "description": "Search US companies across 85 million+ company records.", "operationId": "searchCompaniesV2", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySearchRequestV2" } } }, "required": true }, "responses": { "200": { "description": "Successful search response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponseV2" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Malformed query syntax. The detail field describes the specific rule violated." }, "401": { "description": "Missing or invalid API key." }, "402": { "description": "Insufficient credits." } }, "security": [ { "ApiKeyAuth": [] } ], "parameters": [] } }, "/v2/officers/search": { "post": { "tags": [ "Officers" ], "summary": "Search officers", "description": "Search company officers, directors, members, agents, and shareholders by name across US corporate records.", "operationId": "searchOfficersV2", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfficerSearchRequestV2" } } }, "required": true }, "responses": { "200": { "description": "Successful search response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfficerSearchResponseV2" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Malformed query syntax or unknown jurisdiction. The detail field describes the specific rule violated." }, "401": { "description": "Missing or invalid API key." }, "402": { "description": "Insufficient credits." } }, "security": [ { "ApiKeyAuth": [] } ], "parameters": [] } }, "/v2/companies/{jurisdiction_code}/{company_number}": { "get": { "tags": [ "Companies" ], "summary": "Get a company", "description": "Retrieve a single company by its jurisdiction code and registry company number.", "operationId": "getCompanyV2", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "jurisdiction_code", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Jurisdiction code, e.g. `us_de` or `us_ca`." }, { "name": "company_number", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Registry-assigned entity number." } ], "responses": { "200": { "description": "Company entity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCompanyEntity" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "description": "Missing or invalid API key." }, "402": { "description": "Insufficient credits." }, "404": { "description": "Entity record not found." } } } }, "/v2/local-businesses/batches": { "post": { "tags": [ "Local Businesses" ], "summary": "Start an ownership search", "operationId": "createLocalBusinessBatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocalBusinessBatchRequest" } } }, "required": true }, "responses": { "202": { "description": "Batch accepted and queued for asynchronous processing.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/QueuedLocalBusinessBatch", "title": "Queued" }, { "$ref": "#/components/schemas/RunningLocalBusinessBatch", "title": "Running" }, { "$ref": "#/components/schemas/SucceededLocalBusinessBatch", "title": "Succeeded" }, { "$ref": "#/components/schemas/FailedLocalBusinessBatch", "title": "Failed" } ], "discriminator": { "propertyName": "status", "mapping": { "queued": "#/components/schemas/QueuedLocalBusinessBatch", "running": "#/components/schemas/RunningLocalBusinessBatch", "succeeded": "#/components/schemas/SucceededLocalBusinessBatch", "failed": "#/components/schemas/FailedLocalBusinessBatch" } } } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "description": "Missing or invalid API key." }, "402": { "description": "Insufficient credits." }, "503": { "description": "The batch request could not be stored or queued." } }, "security": [ { "ApiKeyAuth": [] } ], "parameters": [] } }, "/v2/local-businesses/batches/{batch_id}": { "get": { "tags": [ "Local Businesses" ], "summary": "Get ownership search results", "operationId": "getLocalBusinessBatch", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 7, "maxLength": 200, "pattern": "^batch_[0-9a-f]+$" }, "description": "Batch identifier returned by the create endpoint." } ], "responses": { "200": { "description": "Current batch state.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/QueuedLocalBusinessBatch", "title": "Queued" }, { "$ref": "#/components/schemas/RunningLocalBusinessBatch", "title": "Running" }, { "$ref": "#/components/schemas/SucceededLocalBusinessBatch", "title": "Succeeded" }, { "$ref": "#/components/schemas/FailedLocalBusinessBatch", "title": "Failed" } ], "discriminator": { "propertyName": "status", "mapping": { "queued": "#/components/schemas/QueuedLocalBusinessBatch", "running": "#/components/schemas/RunningLocalBusinessBatch", "succeeded": "#/components/schemas/SucceededLocalBusinessBatch", "failed": "#/components/schemas/FailedLocalBusinessBatch" } } } } } }, "502": { "description": "The completed result could not be loaded or validated." }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "description": "Missing or invalid API key." }, "404": { "description": "Batch not found or not owned by the authenticated account." } } } } }, "components": { "schemas": { "Address": { "properties": { "line1": { "type": "string" }, "line2": { "type": [ "string", "null" ] }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string", "default": "US" } }, "additionalProperties": false, "type": "object", "required": [ "line1", "city", "state", "postal_code" ], "description": "Source address text without formatting or length requirements." }, "BusinessRegistration": { "properties": { "jurisdiction": { "type": "string" }, "registration_number": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "incorporated_on": { "type": [ "string", "null" ], "format": "date" }, "dissolved_on": { "type": [ "string", "null" ], "format": "date" } }, "additionalProperties": false, "type": "object", "required": [ "jurisdiction" ] }, "CompanySearchRequestV2": { "properties": { "q": { "type": "string", "description": "Search query. Supports Google-style syntax: AND/OR, parentheses, quoted phrases, and prefix wildcards.", "examples": [ "acme" ], "example": "acme" }, "match_alternative_names": { "type": "boolean", "description": "Also match against DBAs, trade names, and other alternative names.", "default": true }, "match_previous_names": { "type": "boolean", "description": "Also match against historical legal names.", "default": true }, "jurisdictions": { "type": "string", "description": "Either 'all' or a comma-separated list of jurisdiction codes (e.g. 'us_de,us_ca').", "default": "all" }, "status": { "type": "string", "enum": [ "active", "inactive", "unknown", "any" ], "description": "Filter by registry status. 'active' and 'inactive' also include records with no published status; 'unknown' matches only those records; 'any' disables the filter.", "default": "any" }, "order_by": { "type": "string", "enum": [ "jurisdiction", "relevance" ], "description": "Result ordering. 'jurisdiction' orders by jurisdiction code then company number. 'relevance' orders by match quality: companies whose name is exactly the query rank first, then descending full-text rank with current-name matches weighted above alternative and previous names.", "default": "jurisdiction" }, "limit": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "description": "Results per page, 1 to 100.", "default": 100 }, "page": { "type": "integer", "minimum": 1.0, "description": "1-based page number.", "default": 1 } }, "type": "object", "required": [ "q" ] }, "Contact": { "properties": { "websites": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "phone": { "type": [ "string", "null" ] }, "fax": { "type": [ "string", "null" ] } }, "type": "object" }, "CorporateParent": { "properties": { "legal_name": { "type": "string" } }, "additionalProperties": false, "type": "object", "required": [ "legal_name" ], "description": "The legal name of a company principal associated with the operator." }, "CreditBalanceResponse": { "properties": { "balance": { "type": "integer", "description": "Remaining API credits for the account tied to this API key.", "examples": [ 1000 ], "example": 1000 }, "overage_enabled": { "type": "boolean", "description": "Whether the account may continue using credits below zero." }, "overage_amount": { "description": "How far below zero the balance may fall, or null when overage is disabled.", "examples": [ 10000 ], "type": [ "integer", "null" ], "example": 10000 }, "auto_topup_enabled": { "type": "boolean", "description": "Whether automatic credit top-ups are enabled for the account." }, "auto_topup_threshold_credits": { "description": "Balance that triggers an auto top-up, or null when auto top-up is disabled.", "examples": [ 5000 ], "type": [ "integer", "null" ], "example": 5000 }, "auto_topup_target_credits": { "description": "Balance restored by an auto top-up, or null when auto top-up is disabled.", "examples": [ 15000 ], "type": [ "integer", "null" ], "example": 15000 } }, "type": "object", "required": [ "balance", "overage_enabled", "overage_amount", "auto_topup_enabled", "auto_topup_threshold_credits", "auto_topup_target_credits" ] }, "Domicile": { "type": "string", "enum": [ "domestic", "foreign", "unknown" ] }, "EntityFiling": { "properties": { "id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "filed_on": { "type": "string", "format": "date" }, "type": { "anyOf": [ { "$ref": "#/components/schemas/FilingType" }, { "type": "null" } ] }, "url": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] } }, "type": "object", "required": [ "filed_on" ] }, "EntityName": { "properties": { "name": { "type": "string", "minLength": 1 }, "kind": { "$ref": "#/components/schemas/NameKind" }, "started_on": { "type": [ "string", "null" ], "format": "date" }, "ended_on": { "type": [ "string", "null" ], "format": "date" } }, "type": "object", "required": [ "name", "kind" ] }, "EntityRef": { "properties": { "name": { "type": [ "string", "null" ] }, "jurisdiction_code": { "type": [ "string", "null" ] }, "entity_number": { "type": [ "string", "null" ] } }, "type": "object" }, "EntityRelationship": { "properties": { "kind": { "$ref": "#/components/schemas/RelationshipKind" }, "entity": { "$ref": "#/components/schemas/EntityRef" }, "effective_date": { "type": [ "string", "null" ], "format": "date" } }, "type": "object", "required": [ "kind", "entity" ] }, "EntityStatusKind": { "type": "string", "enum": [ "active", "inactive", "dissolved", "suspended", "merged", "withdrawn", "unknown" ] }, "FailedLocalBusinessBatch": { "properties": { "batch_id": { "type": "string", "maxLength": 200, "minLength": 7, "pattern": "^batch_[0-9A-Za-z]+$" }, "type": { "type": "string", "const": "local_business_batch", "default": "local_business_batch" }, "location_count": { "type": "integer", "maximum": 500.0, "minimum": 1.0 }, "created_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "const": "failed" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "type": "object", "required": [ "batch_id", "location_count", "created_at", "status", "completed_at" ] }, "FilingType": { "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "type": "object" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array" } }, "type": "object" }, "Identifier": { "properties": { "scheme": { "type": "string" }, "value": { "type": "string", "minLength": 1 } }, "type": "object", "required": [ "scheme", "value" ] }, "IndustryCode": { "properties": { "code": { "type": "string", "minLength": 1 }, "scheme": { "type": "string" }, "description": { "type": [ "string", "null" ] } }, "type": "object", "required": [ "code", "scheme" ] }, "JurisdictionsResponse": { "properties": { "jurisdictions": { "items": { "type": "string" }, "type": "array", "description": "Jurisdiction codes currently loaded and queryable in the API, sorted alphabetically.", "examples": [ [ "us_ca", "us_de", "us_ny" ] ], "example": [ "us_ca", "us_de", "us_ny" ] } }, "type": "object", "required": [ "jurisdictions" ] }, "LabeledAddress": { "properties": { "line1": { "type": "string" }, "line2": { "type": [ "string", "null" ] }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string", "default": "US" }, "type": { "type": "string" } }, "additionalProperties": false, "type": "object", "required": [ "line1", "city", "state", "postal_code", "type" ] }, "LegalForm": { "type": "string", "enum": [ "llc", "corporation", "nonprofit", "limited_partnership", "limited_liability_partnership", "partnership", "trust", "other", "unknown" ] }, "LocalBusinessBatchRequest": { "properties": { "locations": { "items": { "$ref": "#/components/schemas/LocalBusinessInput" }, "type": "array", "maxItems": 500, "minItems": 1 } }, "additionalProperties": false, "type": "object", "required": [ "locations" ] }, "LocalBusinessBatchResultDocument": { "properties": { "batch_id": { "type": "string", "maxLength": 200, "minLength": 7, "pattern": "^batch_[0-9A-Za-z]+$" }, "status": { "type": "string", "const": "completed" }, "summary": { "$ref": "#/components/schemas/LocalBusinessBatchSummary" }, "credits_charged": { "type": "integer", "minimum": 0.0 }, "results": { "items": { "oneOf": [ { "$ref": "#/components/schemas/MatchedLocalBusinessResult" }, { "$ref": "#/components/schemas/UnmatchedLocalBusinessResult" } ] }, "type": "array" } }, "additionalProperties": false, "type": "object", "required": [ "batch_id", "status", "summary", "credits_charged", "results" ] }, "LocalBusinessBatchSummary": { "properties": { "submitted": { "type": "integer", "minimum": 1.0 }, "matched": { "type": "integer", "minimum": 0.0 }, "unmatched": { "type": "integer", "minimum": 0.0 } }, "additionalProperties": false, "type": "object", "required": [ "submitted", "matched", "unmatched" ] }, "LocalBusinessInput": { "properties": { "customer_record_id": { "type": [ "string", "null" ], "maxLength": 200, "minLength": 1 }, "name": { "type": "string", "maxLength": 300, "minLength": 1 }, "address": { "type": "string", "maxLength": 1000, "minLength": 1 }, "phone": { "type": [ "string", "null" ], "maxLength": 50, "minLength": 1 }, "email": { "type": [ "string", "null" ], "maxLength": 320, "minLength": 3 }, "website": { "type": [ "string", "null" ], "maxLength": 2048, "minLength": 1 } }, "additionalProperties": false, "type": "object", "required": [ "name", "address" ] }, "Location": { "properties": { "name": { "type": "string" }, "phone": { "type": [ "string", "null" ], "maxLength": 16, "minLength": 3, "pattern": "^\\+[1-9][0-9]{1,14}$", "description": "Phone number normalized to E.164 format." }, "email": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "address": { "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "required": [ "name" ] }, "MatchInfo": { "properties": { "matched_field": { "type": "string", "enum": [ "name", "alternative_names", "previous_names" ], "description": "Which field on the Company record matched the query: `name`, `alternative_names`, or `previous_names`. When more than one field matches, `name` takes precedence, then `alternative_names`, then `previous_names`.", "examples": [ "name" ], "example": "name" }, "matched_value": { "type": "string", "description": "The actual value pulled from the matched field." } }, "type": "object", "required": [ "matched_field", "matched_value" ] }, "MatchedLocalBusinessResult": { "properties": { "customer_record_id": { "type": "string", "maxLength": 200, "minLength": 1 }, "enriched_at": { "type": "string", "format": "date" }, "match": { "$ref": "#/components/schemas/MatchedMatch" }, "location": { "$ref": "#/components/schemas/Location" }, "operator": { "$ref": "#/components/schemas/Operator" }, "people": { "items": { "$ref": "#/components/schemas/Person" }, "type": "array" } }, "additionalProperties": false, "type": "object", "required": [ "customer_record_id", "enriched_at", "match", "location", "operator" ] }, "MatchedMatch": { "properties": { "status": { "type": "string", "const": "matched" }, "relationship_status": { "$ref": "#/components/schemas/RelationshipStatus", "default": "current" } }, "additionalProperties": false, "type": "object", "required": [ "status" ] }, "NameKind": { "type": "string", "enum": [ "previous_legal", "trading", "alias" ] }, "OfficerMatchInfoV2": { "properties": { "matched_field": { "type": "string", "const": "officer_name", "description": "Always `officer_name`: officer search matches against the officer's name.", "examples": [ "officer_name" ], "example": "officer_name" } }, "type": "object", "required": [ "matched_field" ] }, "OfficerSearchRequestEchoV2": { "properties": { "query": { "type": "string", "description": "The `q` string as submitted in the request." }, "role": { "anyOf": [ { "$ref": "#/components/schemas/PartyRoleKind" }, { "type": "null" } ], "description": "Echo of the requested role filter, or null." }, "zip_code": { "description": "Echo of the requested ZIP code filter, or null.", "type": [ "string", "null" ] }, "jurisdictions": { "type": "string", "description": "Echo of the request `jurisdictions` string ('all' or comma-separated codes)." } }, "type": "object", "required": [ "query", "role", "zip_code", "jurisdictions" ] }, "OfficerSearchRequestV2": { "properties": { "q": { "type": "string", "description": "Search query over officer names. Supports Google-style syntax: AND/OR, parentheses, quoted phrases, and prefix wildcards.", "examples": [ "john smith" ], "example": "john smith" }, "role": { "anyOf": [ { "$ref": "#/components/schemas/PartyRoleKind" }, { "type": "null" } ], "description": "Optional exact filter on the officer's normalized role kind (e.g. 'officer', 'registered_agent'). Officers whose role kind differs are excluded.", "examples": [ "officer" ], "example": "officer" }, "zip_code": { "description": "Optional five-digit ZIP code filter on the officer's address. Officers without a matching address are excluded.", "examples": [ "19801" ], "type": [ "string", "null" ], "pattern": "^\\d{5}$", "example": "19801" }, "jurisdictions": { "type": "string", "description": "Either 'all' or a comma-separated list of jurisdiction codes (e.g. 'us_de,us_ca').", "default": "all" }, "limit": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "description": "Results per page, 1 to 100.", "default": 100 }, "page": { "type": "integer", "minimum": 1.0, "description": "1-based page number.", "default": 1 } }, "type": "object", "required": [ "q" ] }, "OfficerSearchResponseV2": { "properties": { "page": { "type": "integer", "description": "1-based page number of this response." }, "request": { "$ref": "#/components/schemas/OfficerSearchRequestEchoV2", "description": "Echo of the request as resolved by the server." }, "summary": { "$ref": "#/components/schemas/SearchSummary", "description": "Aggregate match counts and pagination cursor." }, "results": { "items": { "$ref": "#/components/schemas/OfficerSearchResultV2" }, "type": "array", "description": "Matching officers, ordered by jurisdiction code then company number. Each entry is one matched officer, so a company appears once per matching officer." } }, "type": "object", "required": [ "page", "request", "summary", "results" ] }, "OfficerSearchResultV2": { "properties": { "match": { "$ref": "#/components/schemas/OfficerMatchInfoV2" }, "officer": { "$ref": "#/components/schemas/PublicParty", "description": "The matched officer (officer, director, member, agent, or shareholder) from the company's parties list." }, "company": { "$ref": "#/components/schemas/PublicCompanyEntity", "description": "The company entity the matched officer belongs to. See the company schema page for the field-by-field reference." } }, "type": "object", "required": [ "match", "officer", "company" ] }, "Operator": { "properties": { "legal_name": { "type": "string" }, "entity_type": { "type": [ "string", "null" ] }, "business_registration": { "anyOf": [ { "$ref": "#/components/schemas/BusinessRegistration" }, { "type": "null" } ] }, "addresses": { "items": { "$ref": "#/components/schemas/LabeledAddress" }, "type": "array" }, "last_updated_at": { "type": [ "string", "null" ], "format": "date" }, "corporate_parent": { "anyOf": [ { "$ref": "#/components/schemas/CorporateParent" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "required": [ "legal_name" ] }, "PartyRoleKind": { "type": "string", "enum": [ "registered_agent", "officer", "manager", "member", "governor", "owner", "incorporator", "shareholder", "other", "unknown" ] }, "Person": { "properties": { "name": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "role": { "type": [ "string", "null" ] }, "address": { "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "required": [ "name" ], "description": "A human party published for the matched operator." }, "PublicCompanyEntity": { "properties": { "kind": { "type": "string", "const": "company", "default": "company" }, "jurisdiction_code": { "type": "string", "maxLength": 5, "minLength": 2 }, "entity_number": { "type": "string", "minLength": 1 }, "legal_name": { "type": "string", "minLength": 1 }, "status": { "$ref": "#/components/schemas/EntityStatusKind" }, "status_raw": { "type": [ "string", "null" ] }, "legal_form": { "$ref": "#/components/schemas/LegalForm" }, "legal_form_raw": { "type": [ "string", "null" ] }, "domicile": { "$ref": "#/components/schemas/Domicile" }, "formed_on": { "type": [ "string", "null" ], "format": "date" }, "dissolved_on": { "type": [ "string", "null" ], "format": "date" }, "addresses": { "anyOf": [ { "$ref": "#/components/schemas/PublicEntityAddresses" }, { "type": "null" } ] }, "names": { "items": { "$ref": "#/components/schemas/EntityName" }, "type": [ "array", "null" ] }, "parties": { "items": { "$ref": "#/components/schemas/PublicParty" }, "type": [ "array", "null" ] }, "filings": { "items": { "$ref": "#/components/schemas/EntityFiling" }, "type": [ "array", "null" ] }, "relationships": { "items": { "$ref": "#/components/schemas/EntityRelationship" }, "type": [ "array", "null" ] }, "contact": { "anyOf": [ { "$ref": "#/components/schemas/Contact" }, { "type": "null" } ] }, "industry_codes": { "items": { "$ref": "#/components/schemas/IndustryCode" }, "type": [ "array", "null" ] }, "identifiers": { "items": { "$ref": "#/components/schemas/Identifier" }, "type": [ "array", "null" ] }, "entity_url": { "type": [ "string", "null" ] }, "search_url": { "type": "string" }, "as_of": { "type": "string", "format": "date" } }, "type": "object", "required": [ "jurisdiction_code", "entity_number", "legal_name", "status", "legal_form", "domicile", "search_url", "as_of" ] }, "PublicEntityAddress": { "properties": { "raw": { "type": [ "string", "null" ] }, "street_address": { "type": [ "string", "null" ] }, "street_address_2": { "type": [ "string", "null" ] }, "locality": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] } }, "type": "object" }, "PublicEntityAddresses": { "properties": { "registered": { "anyOf": [ { "$ref": "#/components/schemas/PublicEntityAddress" }, { "type": "null" } ] }, "headquarters": { "anyOf": [ { "$ref": "#/components/schemas/PublicEntityAddress" }, { "type": "null" } ] }, "mailing": { "anyOf": [ { "$ref": "#/components/schemas/PublicEntityAddress" }, { "type": "null" } ] } }, "type": "object" }, "PublicParty": { "properties": { "type": { "$ref": "#/components/schemas/PublicPartyType" }, "name": { "type": "string", "minLength": 1 }, "roles": { "items": { "$ref": "#/components/schemas/PublicRole" }, "type": "array" }, "address": { "anyOf": [ { "$ref": "#/components/schemas/PublicEntityAddress" }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "name" ] }, "PublicPartyType": { "type": "string", "enum": [ "company", "person", "unknown" ] }, "PublicRole": { "properties": { "kind": { "$ref": "#/components/schemas/PartyRoleKind" }, "title": { "type": [ "string", "null" ] }, "ownership_percentage": { "type": [ "number", "null" ] }, "started_on": { "type": [ "string", "null" ], "format": "date" }, "ended_on": { "type": [ "string", "null" ], "format": "date" } }, "type": "object", "required": [ "kind" ] }, "QueuedLocalBusinessBatch": { "properties": { "batch_id": { "type": "string", "maxLength": 200, "minLength": 7, "pattern": "^batch_[0-9A-Za-z]+$" }, "type": { "type": "string", "const": "local_business_batch", "default": "local_business_batch" }, "location_count": { "type": "integer", "maximum": 500.0, "minimum": 1.0 }, "created_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "const": "queued" } }, "additionalProperties": false, "type": "object", "required": [ "batch_id", "location_count", "created_at", "status" ] }, "RelationshipKind": { "type": "string", "enum": [ "merged_into", "home_entity", "subsequent_registration", "alternate_registration" ] }, "RelationshipStatus": { "type": "string", "enum": [ "current", "historical" ] }, "RunningLocalBusinessBatch": { "properties": { "batch_id": { "type": "string", "maxLength": 200, "minLength": 7, "pattern": "^batch_[0-9A-Za-z]+$" }, "type": { "type": "string", "const": "local_business_batch", "default": "local_business_batch" }, "location_count": { "type": "integer", "maximum": 500.0, "minimum": 1.0 }, "created_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "const": "running" }, "started_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "type": "object", "required": [ "batch_id", "location_count", "created_at", "status", "started_at" ] }, "SearchRequestEchoV2": { "properties": { "query": { "type": "string", "description": "The `q` string as submitted in the request." }, "match_alternative_names": { "type": "boolean", "description": "Echo of the request flag." }, "match_previous_names": { "type": "boolean", "description": "Echo of the request flag." }, "jurisdictions": { "type": "string", "description": "Echo of the request `jurisdictions` string ('all' or comma-separated codes)." }, "status": { "type": "string", "enum": [ "active", "inactive", "unknown", "any" ], "description": "Echo of the requested status filter.", "examples": [ "any" ], "example": "any" }, "order_by": { "type": "string", "enum": [ "jurisdiction", "relevance" ], "description": "Echo of the requested result ordering.", "examples": [ "jurisdiction" ], "example": "jurisdiction" } }, "type": "object", "required": [ "query", "match_alternative_names", "match_previous_names", "jurisdictions", "status", "order_by" ] }, "SearchResponseV2": { "properties": { "page": { "type": "integer", "description": "1-based page number of this response." }, "request": { "$ref": "#/components/schemas/SearchRequestEchoV2", "description": "Echo of the request as resolved by the server." }, "summary": { "$ref": "#/components/schemas/SearchSummary", "description": "Aggregate match counts and pagination cursor." }, "results": { "items": { "$ref": "#/components/schemas/SearchResultV2" }, "type": "array", "description": "Matching companies, ordered according to the request's `order_by`. Empty when nothing matched." } }, "type": "object", "required": [ "page", "request", "summary", "results" ] }, "SearchResultV2": { "properties": { "match": { "$ref": "#/components/schemas/MatchInfo" }, "company": { "$ref": "#/components/schemas/PublicCompanyEntity", "description": "The full company entity. See the company schema page for the field-by-field reference." } }, "type": "object", "required": [ "match", "company" ] }, "SearchSummary": { "properties": { "total_matches": { "type": "integer", "description": "Number of companies matching the query, counted up to a cap of 10,000. When `total_is_capped` is true there are at least this many matches and possibly more; use `next_page` to page through all of them." }, "total_is_capped": { "type": "boolean", "description": "True when `total_matches` hit the 10,000 cap and the real total is higher. Paginate with `next_page` to retrieve results beyond the cap." }, "returned": { "type": "integer", "description": "Number of results in this response.", "examples": [ 10 ], "example": 10 }, "next_page": { "description": "1-based page number to fetch next, or `null` if this is the last page. Derived from whether a full page of results was returned, so it remains correct past the 10,000 count cap.", "type": [ "integer", "null" ] }, "jurisdictions_searched": { "items": { "type": "string" }, "type": "array", "description": "Resolved list of jurisdiction codes actually searched. Expanded when the request used `'all'`; normalized otherwise." } }, "type": "object", "required": [ "total_matches", "total_is_capped", "returned", "next_page", "jurisdictions_searched" ] }, "SucceededLocalBusinessBatch": { "properties": { "batch_id": { "type": "string", "maxLength": 200, "minLength": 7, "pattern": "^batch_[0-9A-Za-z]+$" }, "type": { "type": "string", "const": "local_business_batch", "default": "local_business_batch" }, "location_count": { "type": "integer", "maximum": 500.0, "minimum": 1.0 }, "created_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "const": "succeeded" }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "result": { "$ref": "#/components/schemas/LocalBusinessBatchResultDocument" } }, "additionalProperties": false, "type": "object", "required": [ "batch_id", "location_count", "created_at", "status", "started_at", "completed_at", "result" ] }, "UnmatchedLocalBusinessResult": { "properties": { "customer_record_id": { "type": "string", "maxLength": 200, "minLength": 1 }, "enriched_at": { "type": "string", "format": "date" }, "match": { "$ref": "#/components/schemas/UnmatchedMatch" }, "location": { "$ref": "#/components/schemas/Location" }, "operator": { "type": "null" }, "people": { "items": { "$ref": "#/components/schemas/Person" }, "type": "array", "maxItems": 0 } }, "additionalProperties": false, "type": "object", "required": [ "customer_record_id", "enriched_at", "match", "location" ] }, "UnmatchedMatch": { "properties": { "status": { "type": "string", "const": "unmatched" } }, "additionalProperties": false, "type": "object", "required": [ "status" ] }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array" }, "msg": { "type": "string" }, "type": { "type": "string" }, "input": {}, "ctx": { "type": "object" } }, "type": "object", "required": [ "loc", "msg", "type" ] } }, "securitySchemes": { "APIKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } } }, "tags": [ { "name": "Health", "description": "Service health checks." }, { "name": "Companies", "description": "Corporate entity search and lookup endpoints." }, { "name": "Officers", "description": "Officer, director, and agent search endpoints." }, { "name": "Local Businesses", "description": "Asynchronous matching of physical businesses to their legal operators and published principals." }, { "name": "Account", "description": "Account and billing endpoints." } ] }