{
  "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"
          }
        }
      }
    }
  }
}