Quickstart

This guide walks you through your first successful GET /api/company/search in about five minutes. You need a CompanyData account and an API key.

Comparing B2B data APIs? See Choosing a company data API before you integrate.

For machine-readable API definitions (OpenAPI 3.0), use the spec at /openapi.json.

1. Get your API key

1. Create an account and pick a plan (trial included on signup).
2. Open your dashboard and copy your API key.

2. Set your API key

Store the key in your environment. Every request sends it in the x-api-key header (see Authentication).

export COMPANYDATA_API_KEY="your_key_here"

COMPANYDATA_API_KEY=your_key_here

3. Search companies (first request)

This example searches companies in the Netherlands (countryCode=NL) matching Heineken.

Recommended: npm SDK

Use the official JavaScript/TypeScript package @companydata/protool-sdk:

npm install @companydata/protool-sdk

import { ApiClient } from '@companydata/protool-sdk'

const client = new ApiClient({
  baseUrl: 'https://app.companydata.com',
  auth: { type: 'apiKey', apiKey: process.env.COMPANYDATA_API_KEY ?? '' },
})

const result = await client.company.search({
  countryCode: 'NL',
  search: 'Heineken',
  page: 1,
  pageSize: 25,
})

console.log(result.data)

Or use any HTTP client. See the JavaScript SDK for retries, timeouts, and export helpers.

cURL / HTTP

curl -G "https://app.companydata.com/api/company/search" \
  --data-urlencode "countryCode=NL" \
  --data-urlencode "search=Heineken" \
  -H "x-api-key: $COMPANYDATA_API_KEY"

4. Confirm it worked

A successful search returns HTTP 200 with records under data.records and page details under meta:

{
  "meta": {
    "totalCount": 3,
    "currentPage": 1,
    "totalPages": 1,
    "pageSize": 25
  },
  "data": {
    "records": [
      {
        "ID": "330114331",
        "Company Name": "Heineken N.V.",
        "Country": "Netherlands",
        "City": "AMSTERDAM"
      }
    ]
  }
}

Search uses standard pagination (default pageSize 25; up to 50 records total across pages). See Company search & export and Pagination.

Common errors

Every failure is signalled by the HTTP status code; the body is JSON with an error string. No failure is ever reported inside a 200 response.

• 400 Bad Request - no query parameters at all. The body reuses the list envelope with meta.totalCount = -1 and the reason in meta.message.
• 401 Unauthorized - invalid x-api-key. Check the key and Authentication.
• 403 Forbidden - the key is disabled or the subscription is inactive (subscriptionStatus names the state).
• 405 Method Not Allowed - only GET is accepted.
• 429 Too Many Requests - a quota is exhausted (monthly searches, request allowance, or the per-second rate limit). The body may add searchesUsed / searchesLimit or requestsUsed / requestsLimit.
• 500 Internal Server Error - the search failed; safe to retry with backoff.
• 503 Service Unavailable - no search index is selected on the server, typically during an index switch; retry later.

The full list with example bodies is in the OpenAPI specification.

5. Next steps