{ "openapi": "3.0.3", "info": { "title": "CompanyData API", "version": "1.0.0", "description": "CompanyData API: search and export companies, plus lookup helpers for exact location names.\n\n**Authentication**: send your API key in the `x-api-key` header on every request.\n**Rate limit**: 50 requests per second (default). **Monthly quota**: 100,000 requests unless agreed otherwise with support.\n\nHuman-readable documentation: https://companydata.com/api-docs/ (see also returned-fields and pagination guides on the docs site).", "contact": { "name": "CompanyData", "url": "https://companydata.com/api-docs/" }, "license": { "name": "Commercial", "url": "https://companydata.com/business-data-api/" } }, "servers": [ { "url": "https://app.companydata.com", "description": "Production" } ], "tags": [ { "name": "Company", "description": "Company search and export" }, { "name": "Lookup", "description": "Autocomplete helpers for city, province, region, and country names" } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/api/company/search": { "get": { "operationId": "companySearch", "tags": [ "Company" ], "summary": "Company search", "description": "Search companies by name, address, and filters. Returns a lightweight default field set; additional search fields may be available per agreement with support. Uses **standard pagination only** (no scroll). Search defaults: pageSize 25 (max 50), maximum **50 total records** retrievable across pages.", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/ID" }, { "$ref": "#/components/parameters/search" }, { "$ref": "#/components/parameters/sic4Digits" }, { "$ref": "#/components/parameters/importExportCode" }, { "$ref": "#/components/parameters/legalStatus" }, { "$ref": "#/components/parameters/statusCode" }, { "$ref": "#/components/parameters/subsidiaryCode" }, { "$ref": "#/components/parameters/countryCode" }, { "$ref": "#/components/parameters/provinceName" }, { "$ref": "#/components/parameters/cityName" }, { "$ref": "#/components/parameters/streetName" }, { "$ref": "#/components/parameters/regionName" }, { "$ref": "#/components/parameters/countryName" }, { "$ref": "#/components/parameters/postalCode" }, { "$ref": "#/components/parameters/postalCodeIntegerMin" }, { "$ref": "#/components/parameters/postalCodeIntegerMax" }, { "$ref": "#/components/parameters/employeesHereMin" }, { "$ref": "#/components/parameters/employeesHereMax" }, { "$ref": "#/components/parameters/employeesTotalMin" }, { "$ref": "#/components/parameters/employeesTotalMax" }, { "$ref": "#/components/parameters/annualSalesMin" }, { "$ref": "#/components/parameters/annualSalesMax" }, { "$ref": "#/components/parameters/foundingYearsMin" }, { "$ref": "#/components/parameters/foundingYearsMax" }, { "$ref": "#/components/parameters/phoneNumber" }, { "$ref": "#/components/parameters/email" }, { "$ref": "#/components/parameters/worldwideHeadquarterID" }, { "$ref": "#/components/parameters/nationalId" }, { "$ref": "#/components/parameters/hasEmail" }, { "$ref": "#/components/parameters/hasMarketability" }, { "$ref": "#/components/parameters/hasPhone" }, { "$ref": "#/components/parameters/hasFax" }, { "$ref": "#/components/parameters/hasContactPerson" }, { "$ref": "#/components/parameters/hasWebsite" }, { "$ref": "#/components/parameters/hasNationalID" }, { "$ref": "#/components/parameters/hasBusinessName" }, { "$ref": "#/components/parameters/hasStreetAddress" }, { "$ref": "#/components/parameters/hasPostalCode" }, { "$ref": "#/components/parameters/hasCEOName" } ], "responses": { "200": { "description": "Standard pagination response. Records are under data.records; totalCount reflects the full result set size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardCompanyListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/company/export": { "get": { "operationId": "companyExport", "tags": [ "Company" ], "summary": "Company export", "description": "Export companies with the field set included in your subscription. Supports **standard pagination** (max 10,000 records) or **scroll pagination** (unlimited; scroll context expires after 8 minutes). Pass `export=true` as shown in the docs.", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/ID" }, { "$ref": "#/components/parameters/search" }, { "$ref": "#/components/parameters/sic4Digits" }, { "$ref": "#/components/parameters/importExportCode" }, { "$ref": "#/components/parameters/legalStatus" }, { "$ref": "#/components/parameters/statusCode" }, { "$ref": "#/components/parameters/subsidiaryCode" }, { "$ref": "#/components/parameters/countryCode" }, { "$ref": "#/components/parameters/provinceName" }, { "$ref": "#/components/parameters/cityName" }, { "$ref": "#/components/parameters/streetName" }, { "$ref": "#/components/parameters/regionName" }, { "$ref": "#/components/parameters/countryName" }, { "$ref": "#/components/parameters/postalCode" }, { "$ref": "#/components/parameters/postalCodeIntegerMin" }, { "$ref": "#/components/parameters/postalCodeIntegerMax" }, { "$ref": "#/components/parameters/employeesHereMin" }, { "$ref": "#/components/parameters/employeesHereMax" }, { "$ref": "#/components/parameters/employeesTotalMin" }, { "$ref": "#/components/parameters/employeesTotalMax" }, { "$ref": "#/components/parameters/annualSalesMin" }, { "$ref": "#/components/parameters/annualSalesMax" }, { "$ref": "#/components/parameters/foundingYearsMin" }, { "$ref": "#/components/parameters/foundingYearsMax" }, { "$ref": "#/components/parameters/phoneNumber" }, { "$ref": "#/components/parameters/email" }, { "$ref": "#/components/parameters/worldwideHeadquarterID" }, { "$ref": "#/components/parameters/nationalId" }, { "$ref": "#/components/parameters/hasEmail" }, { "$ref": "#/components/parameters/hasMarketability" }, { "$ref": "#/components/parameters/hasPhone" }, { "$ref": "#/components/parameters/hasFax" }, { "$ref": "#/components/parameters/hasContactPerson" }, { "$ref": "#/components/parameters/hasWebsite" }, { "$ref": "#/components/parameters/hasNationalID" }, { "$ref": "#/components/parameters/hasBusinessName" }, { "$ref": "#/components/parameters/hasStreetAddress" }, { "$ref": "#/components/parameters/hasPostalCode" }, { "$ref": "#/components/parameters/hasCEOName" }, { "$ref": "#/components/parameters/exportFlag" }, { "$ref": "#/components/parameters/useScroll" }, { "$ref": "#/components/parameters/scrollId" } ], "responses": { "200": { "description": "Either standard pagination (data.records) or scroll pagination (data as array). Inspect useScroll / scrollId usage to interpret the shape.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/StandardCompanyListResponse" }, { "$ref": "#/components/schemas/ScrollCompanyExportResponse" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/cities": { "get": { "operationId": "lookupCities", "tags": [ "Lookup" ], "summary": "Look up city names", "description": "Returns exact cityName values to use with company search/export (cityName requires an exact database value).", "parameters": [ { "$ref": "#/components/parameters/lookupSearch" }, { "$ref": "#/components/parameters/lookupCountries" }, { "$ref": "#/components/parameters/lookupLimit" } ], "responses": { "200": { "description": "List of matching cities.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Matching city entries with exact names for use in API filters.", "items": { "type": "object", "required": [ "cityName", "countryCode" ], "properties": { "cityName": { "type": "string", "description": "City name as stored in the database (use verbatim in cityName filter)." }, "countryCode": { "type": "string", "description": "ISO 2-letter country code for this city entry." } } } }, "total": { "type": "integer", "description": "Number of matching lookup results returned in this response." }, "limit": { "type": "integer", "description": "Effective limit applied to this lookup request (requested or default)." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/provinces": { "get": { "operationId": "lookupProvinces", "tags": [ "Lookup" ], "summary": "Look up province or district names", "description": "Returns exact provinceName values to use with company search/export (provinceName requires an exact database value).", "parameters": [ { "$ref": "#/components/parameters/lookupSearch" }, { "$ref": "#/components/parameters/lookupCountries" }, { "$ref": "#/components/parameters/lookupLimit" } ], "responses": { "200": { "description": "List of matching provinces.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Matching province entries with exact names for use in API filters.", "items": { "type": "object", "required": [ "provinceName", "countryCode" ], "properties": { "provinceName": { "type": "string", "description": "Province or district name as stored in the database (use verbatim in provinceName filter)." }, "countryCode": { "type": "string", "description": "ISO 2-letter country code for this province entry." } } } }, "total": { "type": "integer", "description": "Number of matching lookup results returned in this response." }, "limit": { "type": "integer", "description": "Effective limit applied to this lookup request (requested or default)." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/regions": { "get": { "operationId": "lookupRegions", "tags": [ "Lookup" ], "summary": "Look up region or state names", "description": "Returns exact regionName values to use with company search/export (regionName requires an exact database value).", "parameters": [ { "$ref": "#/components/parameters/lookupSearch" }, { "$ref": "#/components/parameters/lookupCountries" }, { "$ref": "#/components/parameters/lookupLimit" } ], "responses": { "200": { "description": "List of matching regions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Matching region entries with exact names for use in API filters.", "items": { "type": "object", "required": [ "regionName", "countryCode" ], "properties": { "regionName": { "type": "string", "description": "Region or state name as stored in the database (use verbatim in regionName filter)." }, "countryCode": { "type": "string", "description": "ISO 2-letter country code for this region entry." } } } }, "total": { "type": "integer", "description": "Number of matching lookup results returned in this response." }, "limit": { "type": "integer", "description": "Effective limit applied to this lookup request (requested or default)." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/countries": { "get": { "operationId": "lookupCountries", "tags": [ "Lookup" ], "summary": "Look up country names", "description": "Returns exact countryName values to use with company search/export (countryName requires an exact database value).", "parameters": [ { "$ref": "#/components/parameters/lookupSearch" }, { "$ref": "#/components/parameters/lookupCountries" }, { "$ref": "#/components/parameters/lookupLimit" } ], "responses": { "200": { "description": "List of matching countries.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Matching country entries; use returned names verbatim in countryName filter.", "items": { "type": "object", "required": [ "countryName", "countryCode" ], "properties": { "countryName": { "type": "string", "description": "Country name in English as stored in the database (use verbatim in countryName filter)." }, "countryCode": { "type": "string", "description": "ISO 2-letter country code for this country entry." } } } }, "total": { "type": "integer", "description": "Number of matching lookup results returned in this response." }, "limit": { "type": "integer", "description": "Effective limit applied to this lookup request (requested or default)." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "components": { "responses": { "Unauthorized": { "description": "Missing or invalid API key (x-api-key header).", "content": { "application/json": { "schema": { "type": "object", "description": "Error details; structure is implementation-defined.", "additionalProperties": true } } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key for the CompanyData API. Required on all endpoints." } }, "parameters": { "page": { "name": "page", "in": "query", "required": false, "description": "Page number for standard pagination (starts at 1). Defaults to 1 if omitted. Export: maximum 10,000 records total with standard pagination.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "pageSize": { "name": "pageSize", "in": "query", "required": false, "description": "Records per page. Search: defaults to 25, maximum 50; maximum 50 total records retrievable. Export: defaults to 25; recommended 100–1000 for standard pagination, 1000+ for scroll.", "schema": { "type": "integer", "minimum": 1 } }, "useScroll": { "name": "useScroll", "in": "query", "required": false, "description": "When true, enables scroll (cursor) pagination on export. Use scrollId from the previous response for subsequent requests. Export only.", "schema": { "type": "boolean" } }, "scrollId": { "name": "scrollId", "in": "query", "required": false, "description": "Scroll session identifier from the previous export response. Required for subsequent requests when useScroll is true. Scroll context expires after 8 minutes.", "schema": { "type": "string" } }, "exportFlag": { "name": "export", "in": "query", "required": false, "description": "Set to true on the export endpoint to receive the field set included in your subscription package.", "schema": { "type": "boolean" } }, "ID": { "name": "ID", "in": "query", "required": false, "description": "Filter by company ID.", "schema": { "type": "string" } }, "search": { "name": "search", "in": "query", "required": false, "description": "Search for company name (and related patterns per product behavior).", "schema": { "type": "string" } }, "sic4Digits": { "name": "sic4Digits", "in": "query", "required": false, "description": "4-digit SIC code filter. Comma-separated list supported (e.g. 0111,0115).", "schema": { "type": "string" } }, "importExportCode": { "name": "importExportCode", "in": "query", "required": false, "description": "Import/export activity codes: A, B, C, D, E, F, G, H. Comma-separated list supported.", "schema": { "type": "string" } }, "legalStatus": { "name": "legalStatus", "in": "query", "required": false, "description": "Legal status / business legal type codes (numeric). Comma-separated list supported. Maps to Business Legal Type in responses.", "schema": { "type": "string" } }, "statusCode": { "name": "statusCode", "in": "query", "required": false, "description": "Location type filter: 0 = single location, 1 = headquarter/parent, 2 = branch. Comma-separated list supported. Often use 0,1 to limit branches.", "schema": { "type": "string" } }, "subsidiaryCode": { "name": "subsidiaryCode", "in": "query", "required": false, "description": "Subsidiary filter: 0 = not a subsidiary, 3 = is a subsidiary. Comma-separated list supported.", "schema": { "type": "string" } }, "countryCode": { "name": "countryCode", "in": "query", "required": false, "description": "ISO 2-letter country code filter. Comma-separated list supported (e.g. AL,BY,NL).", "schema": { "type": "string" } }, "provinceName": { "name": "provinceName", "in": "query", "required": false, "description": "State/province name as stored in the database (exact match). Use /api/provinces lookup for valid values.", "schema": { "type": "string" } }, "cityName": { "name": "cityName", "in": "query", "required": false, "description": "City name as stored in the database (exact match). Use /api/cities lookup for valid values.", "schema": { "type": "string" } }, "streetName": { "name": "streetName", "in": "query", "required": false, "description": "Street address; supports prefix (partial) matching from the start of words.", "schema": { "type": "string" } }, "regionName": { "name": "regionName", "in": "query", "required": false, "description": "Region or state name as stored in the database (exact match). Use /api/regions lookup for valid values.", "schema": { "type": "string" } }, "countryName": { "name": "countryName", "in": "query", "required": false, "description": "Country name as stored in the database (exact match). Use /api/countries lookup for valid values.", "schema": { "type": "string" } }, "postalCode": { "name": "postalCode", "in": "query", "required": false, "description": "Postal code (exact string match).", "schema": { "type": "string" } }, "postalCodeIntegerMin": { "name": "postalCodeInteger[min]", "in": "query", "required": false, "description": "Minimum numeric postal code for range filtering (use with postalCodeInteger[max]).", "schema": { "type": "integer" } }, "postalCodeIntegerMax": { "name": "postalCodeInteger[max]", "in": "query", "required": false, "description": "Maximum numeric postal code for range filtering (use with postalCodeInteger[min]).", "schema": { "type": "integer" } }, "employeesHereMin": { "name": "employeesHere[min]", "in": "query", "required": false, "description": "Minimum employees at this location. Use with employeesHere[max].", "schema": { "type": "integer" } }, "employeesHereMax": { "name": "employeesHere[max]", "in": "query", "required": false, "description": "Maximum employees at this location. Use with employeesHere[min].", "schema": { "type": "integer" } }, "employeesTotalMin": { "name": "employeesTotal[min]", "in": "query", "required": false, "description": "Minimum total employees in the company. Use with employeesTotal[max].", "schema": { "type": "integer" } }, "employeesTotalMax": { "name": "employeesTotal[max]", "in": "query", "required": false, "description": "Maximum total employees in the company. Use with employeesTotal[min].", "schema": { "type": "integer" } }, "annualSalesMin": { "name": "annualSales[min]", "in": "query", "required": false, "description": "Minimum annual sales in U.S. dollars. Use with annualSales[max].", "schema": { "type": "integer" } }, "annualSalesMax": { "name": "annualSales[max]", "in": "query", "required": false, "description": "Maximum annual sales in U.S. dollars. Use with annualSales[min].", "schema": { "type": "integer" } }, "foundingYearsMin": { "name": "foundingYears[min]", "in": "query", "required": false, "description": "Minimum founding year (four-digit). Use with foundingYears[max].", "schema": { "type": "integer" } }, "foundingYearsMax": { "name": "foundingYears[max]", "in": "query", "required": false, "description": "Maximum founding year (four-digit). Use with foundingYears[min].", "schema": { "type": "integer" } }, "phoneNumber": { "name": "phoneNumber", "in": "query", "required": false, "description": "Full international phone number with + prefix (local formats not supported).", "schema": { "type": "string" } }, "email": { "name": "email", "in": "query", "required": false, "description": "Filter by email address or pattern (e.g. domain or full address).", "schema": { "type": "string" } }, "worldwideHeadquarterID": { "name": "worldwideHeadquarterID", "in": "query", "required": false, "description": "Filter by global headquarter ID to retrieve all entities in a corporate group.", "schema": { "type": "string" } }, "nationalId": { "name": "nationalId", "in": "query", "required": false, "description": "National company registration number; combine with countryCode when possible.", "schema": { "type": "string" } }, "hasEmail": { "name": "hasEmail", "in": "query", "required": false, "description": "If true, only companies with a non-empty Email field.", "schema": { "type": "boolean" } }, "hasMarketability": { "name": "hasMarketability", "in": "query", "required": false, "description": "If true, filters for records marked as marketable (internal flag; no direct response field).", "schema": { "type": "boolean" } }, "hasPhone": { "name": "hasPhone", "in": "query", "required": false, "description": "If true, only companies with a non-empty Phone Number.", "schema": { "type": "boolean" } }, "hasFax": { "name": "hasFax", "in": "query", "required": false, "description": "If true, only companies with a non-empty Fax Number.", "schema": { "type": "boolean" } }, "hasContactPerson": { "name": "hasContactPerson", "in": "query", "required": false, "description": "If true, only companies with a non-empty CEO Name.", "schema": { "type": "boolean" } }, "hasWebsite": { "name": "hasWebsite", "in": "query", "required": false, "description": "If true, only companies with a non-empty Website.", "schema": { "type": "boolean" } }, "hasNationalID": { "name": "hasNationalID", "in": "query", "required": false, "description": "If true, only companies with a Company Registration Number.", "schema": { "type": "boolean" } }, "hasBusinessName": { "name": "hasBusinessName", "in": "query", "required": false, "description": "If true, only companies with a non-empty Company Name.", "schema": { "type": "boolean" } }, "hasStreetAddress": { "name": "hasStreetAddress", "in": "query", "required": false, "description": "If true, only companies with a non-empty Address 1.", "schema": { "type": "boolean" } }, "hasPostalCode": { "name": "hasPostalCode", "in": "query", "required": false, "description": "If true, only companies with a non-empty Postal Code.", "schema": { "type": "boolean" } }, "hasCEOName": { "name": "hasCEOName", "in": "query", "required": false, "description": "If true, only companies with a non-empty CEO Name.", "schema": { "type": "boolean" } }, "lookupSearch": { "name": "search", "in": "query", "required": true, "description": "Search term for autocomplete-style lookup (partial input allowed).", "schema": { "type": "string" } }, "lookupCountries": { "name": "countries", "in": "query", "required": false, "description": "Optional ISO country code to restrict lookup results to one country.", "schema": { "type": "string" } }, "lookupLimit": { "name": "limit", "in": "query", "required": false, "description": "Maximum number of lookup results to return. Default 100.", "schema": { "type": "integer", "minimum": 1, "default": 100 } } }, "schemas": { "Executive": { "type": "object", "description": "One executive record. Only included if at least first name or last name is present. All properties may be null.", "properties": { "Position": { "type": "number", "nullable": true, "description": "Numeric rank of the executive within the company (1 = most senior)." }, "Title": { "type": "string", "nullable": true, "description": "Job title of the executive (e.g., \"CEO\", \"CFO\", \"Director\")." }, "Title Code": { "type": "string", "nullable": true, "description": "Standardized internal code representing the job title." }, "First Name": { "type": "string", "nullable": true, "description": "Executive's first name." }, "Last Name": { "type": "string", "nullable": true, "description": "Executive's last name." }, "Gender": { "type": "string", "nullable": true, "description": "Gender of the executive (\"Male\" or \"Female\")." }, "Language Preference": { "type": "string", "nullable": true, "description": "ISO locale code indicating the executive's preferred language (see Language Codes in human docs)." } } }, "CompanyRecord": { "type": "object", "description": "Single company record. Field availability depends on your package. Values are strings unless noted; many fields may be null or empty when unknown.", "additionalProperties": true, "properties": { "ID": { "type": "string", "nullable": true, "description": "Unique identifier for the company record. Store this to retrieve or reference the company in future requests without re-searching." }, "Company Name": { "type": "string", "nullable": true, "description": "Primary registered name of the company." }, "Trade Name": { "type": "string", "nullable": true, "description": "Alternative or \"doing business as\" (DBA) name the company may operate under." }, "Address Status": { "type": "string", "nullable": true, "description": "Indicates the address type on file. For European records, if only the registered address is available, it is used as the physical address and this field flags that." }, "Address 1": { "type": "string", "nullable": true, "description": "Primary street address (street name and building number)." }, "Address 2": { "type": "string", "nullable": true, "description": "Secondary address details (suite, floor, building name)." }, "City": { "type": "string", "nullable": true, "description": "City of the company location." }, "State/Province": { "type": "string", "nullable": true, "description": "State or province of the company location." }, "Country": { "type": "string", "nullable": true, "description": "Country name in English (e.g., \"Netherlands\", \"United States\")." }, "Postal Code": { "type": "string", "nullable": true, "description": "Postal or ZIP code. Always a string — may contain letters (e.g., \"1016 GC\"). Filter: postalCode (exact), postalCodeInteger (numeric range)." }, "Company Registration Number": { "type": "string", "nullable": true, "description": "Official national registration ID (e.g., Dutch KvK number, UK Companies House number). See Company Registration Type Code for which system applies. Filter: nationalId." }, "Company Registration Type Code": { "type": "string", "nullable": true, "description": "Code identifying the national registration system used (e.g., \"KVK\" for the Netherlands, \"CRO\" for the UK). Use this to determine how to validate or format Company Registration Number." }, "Country Phone Access Code": { "type": "string", "nullable": true, "description": "International dialing prefix without leading + or 00 (e.g., \"31\" for the Netherlands, \"1\" for the US)." }, "Phone Number": { "type": "string", "nullable": true, "description": "Company phone number. US numbers include area code with no punctuation. Filter: phoneNumber, hasPhone." }, "Cable Telex": { "type": "string", "nullable": true, "description": "Legacy cable or telex number. Rarely populated on modern records." }, "Fax Number": { "type": "string", "nullable": true, "description": "Company fax number. Filter: hasFax." }, "CEO Name": { "type": "string", "nullable": true, "description": "Name of the highest-ranking contact at this location. Also available as Position 1 in the Executives array when executive data is enabled on your account. Filter: hasCEOName, hasContactPerson." }, "CEO Title": { "type": "string", "nullable": true, "description": "Title of the CEO or top contact, possibly abbreviated (e.g., \"Pres\", \"Dir\", \"CEO\")." }, "Business Category": { "type": "string", "nullable": true, "description": "Plain-English description of the company's primary activity (e.g., \"Computer Programming Services\")." }, "Business Category Code 1": { "type": "string", "nullable": true, "description": "Primary 4-digit SIC code (1987 U.S. classification system). Filter: sic4Digits." }, "Business Category Code 1 - Description": { "type": "string", "nullable": true, "description": "Description of the primary SIC code (e.g., \"Computer Programming, Data Processing\")." }, "Founding Year": { "type": "string", "nullable": true, "description": "Four-digit year the current ownership took control, or the founding year if no change of control occurred. Not available for branch records. Filter: foundingYears[min] / foundingYears[max]." }, "Yearly Revenue Local Currency": { "type": "string", "nullable": true, "description": "Annual sales in the local currency. See Currency Code for the applicable currency." }, "Yearly Revenue Indicator": { "type": "string", "nullable": true, "description": "Data quality flag for Yearly Revenue Local Currency. \"0\" = actual figure, \"1\" = low-end range estimate, \"2\" = estimated (also used when the revenue value is zero), empty/null = not available." }, "Yearly Revenue in U.S. Dollars": { "type": "string", "nullable": true, "description": "Annual sales in USD. Exchange rate updated once per year. Filter: annualSales[min] / annualSales[max]." }, "Currency Code": { "type": "string", "nullable": true, "description": "ISO 4217 currency code for Yearly Revenue Local Currency (e.g., \"EUR\", \"USD\", \"GBP\")." }, "Employees On Site": { "type": "string", "nullable": true, "description": "Number of employees at this specific location. Available primarily for US and Canadian records. Filter: employeesHere[min] / employeesHere[max]." }, "Employees On Site Indicator": { "type": "string", "nullable": true, "description": "Data quality flag for Employees On Site. \"0\" = actual figure, \"1\" = low-end estimate, \"2\" = estimated (also used when the value is zero), empty/null = not available." }, "Employees Total": { "type": "string", "nullable": true, "description": "Total number of employees across the entire company. Filter: employeesTotal[min] / employeesTotal[max]." }, "Employees Total Indicator": { "type": "string", "nullable": true, "description": "Data quality flag for Employees Total. \"0\" = actual figure, \"1\" = low-end estimate, \"2\" = estimated (also used when the value is zero), empty/null = not available." }, "Include Principles Indicator": { "type": "string", "nullable": true, "description": "Whether business owners or partners are counted in Employees Total. \"Y\" = included, empty/null = not included or unknown. Available primarily on non-US records." }, "Import/Export Code": { "type": "string", "nullable": true, "description": "Trade activity of the company. \"A\" = imports, exports & agent, \"B\" = imports & exports, \"C\" = imports only, \"D\" = imports & agent, \"E\" = exports & agent, \"F\" = agent only (no inventory), \"G\" = none or not available, \"H\" = exports only, empty = not available. Filter: importExportCode." }, "Business Legal Type": { "type": "string", "nullable": true, "description": "Legal entity type code. \"1\" or \"13\" = proprietorship, \"2\" or \"7\" = partnership, \"3\" = corporation, \"8\" = joint venture, \"9\" = master limited partnership, \"10\" = general partnership, \"11\" = limited partnership, \"12\" = partnership (unknown type), \"14\" = limited liability, \"15\" = friendly society, \"0\" or empty = not available. Other values may exist. Filter: legalStatus." }, "Control Indicator": { "type": "string", "nullable": true, "description": "Reserved field, not currently in use." }, "Location Type": { "type": "string", "nullable": true, "description": "Company's role in its corporate hierarchy. \"0\" = single location (no entities report to it), \"1\" = headquarter/parent (branches and/or subsidiaries report to it), \"2\" = branch (secondary location of a headquarter), empty = not available. Filter: statusCode." }, "Subsidiary Code": { "type": "string", "nullable": true, "description": "Subsidiary status. \"0\" = not a subsidiary, \"3\" = is a subsidiary, empty = not linked. Populated on linked records only. Filter: subsidiaryCode." }, "Local Headquarter ID Number": { "type": "string", "nullable": true, "description": "ID of the immediate parent entity above this location. Pass this value as the ID filter to fetch that record. Empty if not linked." }, "Local Headquarter Company Name": { "type": "string", "nullable": true, "description": "Name of the immediate parent entity. Empty if not linked." }, "Local Headquarter Street Address": { "type": "string", "nullable": true, "description": "Street address of the immediate parent entity. Empty if not linked." }, "Local Headquarter City": { "type": "string", "nullable": true, "description": "City of the immediate parent entity. Empty if not linked." }, "Local Headquarter State/Province": { "type": "string", "nullable": true, "description": "State/province of the immediate parent entity. Empty if not linked." }, "Local Headquarter Country Name": { "type": "string", "nullable": true, "description": "Country name of the immediate parent entity. Empty if not linked." }, "National Headquarter ID Number": { "type": "string", "nullable": true, "description": "ID of the highest entity within the same country as this location. May equal this company's own ID if it is the national top." }, "National Headquarter Company Name": { "type": "string", "nullable": true, "description": "Name of the national-level parent. Empty if not linked." }, "National Headquarter Street Address": { "type": "string", "nullable": true, "description": "Street address of the national-level parent. Empty if not linked." }, "National Headquarter City Name": { "type": "string", "nullable": true, "description": "City of the national-level parent. Empty if not linked." }, "National Headquarter State/Province Name": { "type": "string", "nullable": true, "description": "State/province of the national-level parent. Empty if not linked." }, "Global Headquarter ID Number": { "type": "string", "nullable": true, "description": "ID of the ultimate worldwide parent of the corporate group. All companies in the group share this value. Pass this to the worldwideHeadquarterID filter to fetch all entities in the group." }, "Global Headquarter Company Name": { "type": "string", "nullable": true, "description": "Name of the ultimate worldwide parent. Empty if not linked." }, "Global Headquarter Street Address": { "type": "string", "nullable": true, "description": "Street address of the ultimate worldwide parent. Empty if not linked." }, "Global Headquarter City Name": { "type": "string", "nullable": true, "description": "City of the ultimate worldwide parent. Empty if not linked." }, "Global Headquarter State/Province": { "type": "string", "nullable": true, "description": "State/province of the ultimate worldwide parent. Empty if not linked." }, "Global Headquarter Country Name": { "type": "string", "nullable": true, "description": "Country name of the ultimate worldwide parent. Empty if not linked." }, "Number of Companies in Group": { "type": "string", "nullable": true, "description": "Total number of entities in the worldwide corporate group (HQ + all subsidiaries and branches). All group members share this count. Empty if not linked." }, "Website": { "type": "string", "nullable": true, "description": "Company website URL. Filter: hasWebsite." }, "Email": { "type": "string", "nullable": true, "description": "Company email address(es). May contain multiple addresses separated by commas. Filter: email, hasEmail." }, "Executives": { "type": "array", "nullable": true, "description": "Array of executive/management personnel objects (BETA). Up to 11 executives per company. Null if executive data is not enabled or not available.", "items": { "$ref": "#/components/schemas/Executive" } } } }, "StandardCompanyListResponse": { "type": "object", "description": "Standard paginated list of companies (search and export without scroll).", "required": [ "data", "page", "pageSize", "totalPages" ], "properties": { "data": { "type": "object", "description": "Wrapper containing the current page of records and total hit count.", "required": [ "records" ], "properties": { "records": { "type": "array", "description": "Company records for the requested page.", "items": { "$ref": "#/components/schemas/CompanyRecord" } }, "totalCount": { "type": "integer", "description": "Total number of records matching the query across all pages." } } }, "page": { "type": "integer", "description": "Current page number (1-based)." }, "pageSize": { "type": "integer", "description": "Number of records requested for this page." }, "totalPages": { "type": "integer", "description": "Total number of pages for this query at the given pageSize." } } }, "ScrollCompanyExportResponse": { "type": "object", "description": "Scroll-based export page. The records array is at the top-level data property (not data.records).", "required": [ "data", "hasMoreRecords", "pageSize" ], "properties": { "data": { "type": "array", "description": "Company records for this scroll page.", "items": { "$ref": "#/components/schemas/CompanyRecord" } }, "scrollId": { "type": "string", "description": "Opaque cursor for the next request. Always use the latest scrollId from the most recent response." }, "hasMoreRecords": { "type": "boolean", "description": "True if another page can be fetched with the latest scrollId." }, "pageSize": { "type": "integer", "description": "Number of records in this response." }, "totalRecords": { "type": "integer", "nullable": true, "description": "Not populated in scroll mode; human docs show null. May be omitted or null." } } } } } }