CompanyData Lookup API

openapi: 3.2.0
info:
  title: Companydata Com Lookup API
  version: 1.0.0
  contact:
    name: CompanyData
    url: https://companydata.com/api-docs/
  license:
    name: Commercial
    url: https://companydata.com/company-data-api/
  description: 'Operations tagged Lookup across 2 of this provider''s published API definitions: companydata-com-openapi.json, companydata-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://app.companydata.com
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Lookup
  description: City name autocomplete via GET /api/cities. Province and region names are exact-match filters on search/export (provinceName, regionName); use values as stored in the database.
paths:
  /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).
              example:
                data:
                - cityName: AMSTERDAM
                  countryCode: NL
                - cityName: AMSTELVEEN
                  countryCode: NL
                total: 2
                limit: 100
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-codeSamples:
      - lang: curl
        label: Look up city names in the Netherlands
        source: "curl -G \"https://app.companydata.com/api/cities\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  --data-urlencode \"search=Amster\" \\\n  --data-urlencode \"countries=NL\" \\\n  --data-urlencode \"limit=100\""
    servers:
    - url: https://app.companydata.com
      description: Production
components:
  parameters:
    lookupLimit:
      name: limit
      in: query
      required: false
      description: Maximum number of lookup results to return. Default 100.
      schema:
        type: integer
        minimum: 1
        default: 100
    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
  schemas:
    ErrorResponse:
      type: object
      description: Error body of every failure status except the empty-query 400 and export 500s. error is a human-readable reason; some failures add context fields (subscriptionStatus, searchesUsed / searchesLimit, requestsUsed / requestsLimit, paginationMessage, visitor).
      required:
      - error
      additionalProperties: true
      properties:
        error:
          type: string
          description: Human-readable reason for the failure.
        subscriptionStatus:
          type: string
          description: Present on 403 when the subscription is inactive (PAYMENT_FAILED, CANCELED or EXPIRED).
        searchesUsed:
          type: integer
          description: Present on 429 when the monthly search allowance is used up.
        searchesLimit:
          type: integer
          description: Present on 429 when the monthly search allowance is used up.
        requestsUsed:
          type: integer
          description: Present on 429 for manually invoiced keys.
        requestsLimit:
          type: integer
          description: Present on 429 for manually invoiced keys.
        paginationMessage:
          type: string
          description: Present on the browser-only PAGINATION_LIMIT 403.
        unknownParameters:
          type: array
          items:
            type: string
          description: 'Present on the unknown-parameter 400: the parameter names this endpoint does not have.'
        didYouMean:
          type: object
          additionalProperties:
            type: string
          description: 'Present on the unknown-parameter 400: each unknown name mapped to the parameter you probably meant.'
        documentation:
          type: string
          format: uri
          description: 'Present on the unknown-parameter 400: where the full parameter list lives.'
  responses:
    Unauthorized:
      description: The x-api-key header does not match an existing key (search and export), or no key and no browser session was sent (export). Search without any key or session answers 403 instead.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalidApiKey:
              summary: Unknown API key
              value:
                error: Invalid API key
            missingCredentials:
              summary: No API key and no session (export only)
              value:
                error: 'Unauthorized: No token or user found. '
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for the CompanyData API. Required on all endpoints.
x-refined-from:
- companydata-com-openapi.json
- companydata-com-openapi.yml