{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/companydata-com/json-schema/companydata-com-standard-company-list-response-schema.json",
  "title": "StandardCompanyListResponse",
  "description": "Standard paginated list of companies (search, and export without scroll). Pagination details live under meta; records under data.records.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/companydata-com-openapi.yml#/components/schemas/StandardCompanyListResponse",
  "type": "object",
  "required": [
    "meta",
    "data"
  ],
  "properties": {
    "meta": {
      "$ref": "#/$defs/ListMeta"
    },
    "data": {
      "type": "object",
      "description": "Wrapper containing the current page of records.",
      "required": [
        "records"
      ],
      "properties": {
        "records": {
          "type": "array",
          "description": "Company records for the requested page.",
          "items": {
            "$ref": "#/$defs/CompanyRecord"
          }
        }
      }
    }
  },
  "$defs": {
    "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",
            "null"
          ],
          "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",
            "null"
          ],
          "description": "Primary registered name of the company."
        },
        "Trade Name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Alternative or \"doing business as\" (DBA) name the company may operate under."
        },
        "Address Status": {
          "type": [
            "string",
            "null"
          ],
          "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",
            "null"
          ],
          "description": "Primary street address (street name and building number)."
        },
        "Address 2": {
          "type": [
            "string",
            "null"
          ],
          "description": "Secondary address details (suite, floor, building name)."
        },
        "City": {
          "type": [
            "string",
            "null"
          ],
          "description": "City of the company location."
        },
        "State/Province": {
          "type": [
            "string",
            "null"
          ],
          "description": "State or province of the company location."
        },
        "Country": {
          "type": [
            "string",
            "null"
          ],
          "description": "Country name in English (e.g., \"Netherlands\", \"United States\")."
        },
        "Postal Code": {
          "type": [
            "string",
            "null"
          ],
          "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",
            "null"
          ],
          "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",
            "null"
          ],
          "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",
            "null"
          ],
          "description": "International dialing prefix without leading + or 00 (e.g., \"31\" for the Netherlands, \"1\" for the US)."
        },
        "Phone Number": {
          "type": [
            "string",
            "null"
          ],
          "description": "Company phone number. US numbers include area code with no punctuation. Filter: phoneNumber, hasPhone."
        },
        "Cable Telex": {
          "type": [
            "string",
            "null"
          ],
          "description": "Legacy cable or telex number. Rarely populated on modern records."
        },
        "Fax Number": {
          "type": [
            "string",
            "null"
          ],
          "description": "Company fax number. Filter: hasFax."
        },
        "CEO Name": {
          "type": [
            "string",
            "null"
          ],
          "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",
            "null"
          ],
          "description": "Title of the CEO or top contact, possibly abbreviated (e.g., \"Pres\", \"Dir\", \"CEO\")."
        },
        "Business Category": {
          "type": [
            "string",
            "null"
          ],
          "description": "Plain-English description of the company's primary activity (e.g., \"Computer Programming Services\")."
        },
        "Business Category Code 1": {
          "type": [
            "string",
            "null"
          ],
          "description": "Primary 4-digit SIC code (1987 U.S. classification system). Filter: sic4Digits."
        },
        "Business Category Code 1 - Description": {
          "type": [
            "string",
            "null"
          ],
          "description": "Description of the primary SIC code (e.g., \"Computer Programming, Data Processing\")."
        },
        "Founding Year": {
          "type": [
            "string",
            "null"
          ],
          "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",
            "null"
          ],
          "description": "Annual sales in the local currency. See Currency Code for the applicable currency."
        },
        "Yearly Revenue Indicator": {
          "type": [
            "string",
            "null"
          ],
          "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",
            "null"
          ],
          "description": "Annual sales in USD. Exchange rate updated once per year. Filter: annualSales[min] / annualSales[max]."
        },
        "Currency Code": {
          "type": [
            "string",
            "null"
          ],
          "description": "ISO 4217 currency code for Yearly Revenue Local Currency (e.g., \"EUR\", \"USD\", \"GBP\")."
        },
        "Employees On Site": {
          "type": [
            "string",
            "null"
          ],
          "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",
            "null"
          ],
          "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",
            "null"
          ],
          "description": "Total number of employees across the entire company. Filter: employeesTotal[min] / employeesTotal[max]."
        },
        "Employees Total Indicator": {
          "type": [
            "string",
            "null"
          ],
          "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",
            "null"
          ],
          "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",
            "null"
          ],
          "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",
            "null"
          ],
          "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",
            "null"
          ],
          "description": "Reserved field, not currently in use."
        },
        "Location Type": {
          "type": [
            "string",
            "null"
          ],
          "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",
            "null"
          ],
          "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",
            "null"
          ],
          "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",
            "null"
          ],
          "description": "Name of the immediate parent entity. Empty if not linked."
        },
        "Local Headquarter Street Address": {
          "type": [
            "string",
            "null"
          ],
          "description": "Street address of the immediate parent entity. Empty if not linked."
        },
        "Local Headquarter City": {
          "type": [
            "string",
            "null"
          ],
          "description": "City of the immediate parent entity. Empty if not linked."
        },
        "Local Headquarter State/Province": {
          "type": [
            "string",
            "null"
          ],
          "description": "State/province of the immediate parent entity. Empty if not linked."
        },
        "Local Headquarter Country Name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Country name of the immediate parent entity. Empty if not linked."
        },
        "National Headquarter ID Number": {
          "type": [
            "string",
            "null"
          ],
          "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",
            "null"
          ],
          "description": "Name of the national-level parent. Empty if not linked."
        },
        "National Headquarter Street Address": {
          "type": [
            "string",
            "null"
          ],
          "description": "Street address of the national-level parent. Empty if not linked."
        },
        "National Headquarter City Name": {
          "type": [
            "string",
            "null"
          ],
          "description": "City of the national-level parent. Empty if not linked."
        },
        "National Headquarter State/Province Name": {
          "type": [
            "string",
            "null"
          ],
          "description": "State/province of the national-level parent. Empty if not linked."
        },
        "Global Headquarter ID Number": {
          "type": [
            "string",
            "null"
          ],
          "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",
            "null"
          ],
          "description": "Name of the ultimate worldwide parent. Empty if not linked."
        },
        "Global Headquarter Street Address": {
          "type": [
            "string",
            "null"
          ],
          "description": "Street address of the ultimate worldwide parent. Empty if not linked."
        },
        "Global Headquarter City Name": {
          "type": [
            "string",
            "null"
          ],
          "description": "City of the ultimate worldwide parent. Empty if not linked."
        },
        "Global Headquarter State/Province": {
          "type": [
            "string",
            "null"
          ],
          "description": "State/province of the ultimate worldwide parent. Empty if not linked."
        },
        "Global Headquarter Country Name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Country name of the ultimate worldwide parent. Empty if not linked."
        },
        "Number of Companies in Group": {
          "type": [
            "string",
            "null"
          ],
          "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",
            "null"
          ],
          "description": "Company website URL. Filter: hasWebsite."
        },
        "Email": {
          "type": [
            "string",
            "null"
          ],
          "description": "Company email address(es). May contain multiple addresses separated by commas. Filter: email, hasEmail."
        },
        "Executives": {
          "type": [
            "array",
            "null"
          ],
          "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": "#/$defs/Executive"
          }
        }
      }
    },
    "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",
            "null"
          ],
          "description": "Numeric rank of the executive within the company (1 = most senior)."
        },
        "Title": {
          "type": [
            "string",
            "null"
          ],
          "description": "Job title of the executive (e.g., \"CEO\", \"CFO\", \"Director\")."
        },
        "Title Code": {
          "type": [
            "string",
            "null"
          ],
          "description": "Standardized internal code representing the job title."
        },
        "First Name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Executive's first name."
        },
        "Last Name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Executive's last name."
        },
        "Gender": {
          "type": [
            "string",
            "null"
          ],
          "description": "Gender of the executive (\"Male\" or \"Female\")."
        },
        "Language Preference": {
          "type": [
            "string",
            "null"
          ],
          "description": "ISO locale code indicating the executive's preferred language (see Language Codes in human docs)."
        }
      }
    },
    "ListMeta": {
      "type": "object",
      "description": "Pagination details of a standard (page + pageSize) response.",
      "required": [
        "totalCount",
        "currentPage",
        "totalPages",
        "pageSize"
      ],
      "properties": {
        "totalCount": {
          "type": "integer",
          "description": "Total number of records matching the query across all pages."
        },
        "currentPage": {
          "type": "integer",
          "description": "Page number that was returned (1-based)."
        },
        "totalPages": {
          "type": "integer",
          "description": "Total number of pages for this query at the given pageSize (ceil(totalCount / pageSize))."
        },
        "pageSize": {
          "type": "integer",
          "description": "Page size that was applied (the requested pageSize, capped by the endpoint maximum)."
        },
        "warnings": {
          "$ref": "#/$defs/RequestWarnings"
        }
      }
    },
    "RequestWarnings": {
      "type": "array",
      "description": "Present only when something about the request is worth knowing: a value was normalised before the lookup, a filter was not applied, or the name search found nothing and another field answered instead. Warnings never mean the request failed, and the rows in data are always real results.",
      "items": {
        "type": "object",
        "required": [
          "code",
          "parameter",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "UNKNOWN_PARAMETER",
              "PARAMETER_NOT_APPLIED",
              "COUNTRY_CODE_NORMALISED",
              "COUNTRY_CODE_UNRECOGNISED",
              "NATIONAL_ID_NORMALISED",
              "SEARCH_LOOKS_LIKE_DOMAIN",
              "SEARCH_LOOKS_LIKE_REGISTRATION_NUMBER",
              "SEARCH_NON_LATIN_SCRIPT",
              "SEARCH_MATCHED_ANY_ORDER",
              "SEARCH_MATCHED_CORE_NAME",
              "SEARCH_MATCHED_FUZZY",
              "SEARCH_MATCHED_OTHER_COUNTRY"
            ],
            "description": "UNKNOWN_PARAMETER: the parameter is not part of this endpoint and was ignored. PARAMETER_NOT_APPLIED: the parameter is accepted but does not filter anything on this index. COUNTRY_CODE_NORMALISED / NATIONAL_ID_NORMALISED: the value was rewritten to the stored form before the lookup. COUNTRY_CODE_UNRECOGNISED: the value is not a country code, so it matches nothing; it is kept rather than dropped, so the count stays honest. SEARCH_LOOKS_LIKE_DOMAIN / SEARCH_LOOKS_LIKE_REGISTRATION_NUMBER: no company carries that name, so website or nationalId was searched instead and those are the rows you received. SEARCH_NON_LATIN_SCRIPT: names are stored in the Latin alphabet. SEARCH_MATCHED_ANY_ORDER / SEARCH_MATCHED_CORE_NAME / SEARCH_MATCHED_FUZZY / SEARCH_MATCHED_OTHER_COUNTRY: the exact name search found nothing, so the rows you received come from a relaxed retry - all words in any order, the name without its legal form, the closest spelling, or (only with strictCountry=false) the same name in another country. Each is only used when it returns a small result set, and each one is worth verifying before you rely on it."
          },
          "parameter": {
            "type": "string",
            "description": "The request parameter the warning is about."
          },
          "message": {
            "type": "string",
            "description": "What happened, in one sentence."
          },
          "hint": {
            "type": "string",
            "description": "What to send instead, when there is a better way to ask."
          }
        }
      }
    }
  }
}