Company API

This page provides detailed information on how to retrieve company information through our 2 main API's the search: /api/company/search and export: /api/company/export endpoints. These endpoints allow you to retrieve, search, and export information about companies, with a variety of filtering options such as country, city, industry etc.

Company Search

Endpoint: /api/company/search

The /api/company/search endpoint allows users to search for companies based on various criteria. This endpoint returns a standard set of fields, including the company name and address.

Returned Fields

• ID: A unique identifier of the company, can be used to retrieve a full record.
• Company Name: The main name of the company.
• Country Name: The country of the company.

Note: it's possible to receive more fields on search, this can be requested via support.

Important Notes

• Purpose: This endpoint is primarily used to retrieve basic information such as the company name and address based on a search query. For instance in an autocomplete search.
• Filtering branches: In most cases, you'll want to add statusCode=0,1 to your query. This filters for single locations (0) and headquarters (1) only. Large companies often have many branches/subsidiaries in the database, which are typically not relevant for most use cases like lead generation or company lookup.

Example Request

curl -G https://app.companydata.com/api/company/search \
  -H "x-api-key: {ApiKey}" \
  -d "search=Example Company"

Additional Examples

1. Search for companies named Bolddata

curl -G https://app.companydata.com/api/company/search?page=1&pageSize=25&search=BoldData \
  -H "x-api-key: {ApiKey}"

2. Search for companies named Bolddata in The NETHERLANDS

curl -G https://app.companydata.com/api/company/search?page=1&pageSize=25&search=BoldData&countryCode=NL \
  -H "x-api-key: {ApiKey}"

3. Search by street address in Amsterdam

curl -G "https://app.companydata.com/api/company/search?page=1&pageSize=25&countryCode=NL&cityName=AMSTERDAM&streetName=Keizersgracht" \
  -H "x-api-key: {ApiKey}"

4. Search by city name

curl -G "https://app.companydata.com/api/company/search?page=1&pageSize=25&countryCode=NL&cityName=ROTTERDAM&statusCode=0,1" \
  -H "x-api-key: {ApiKey}"

5. Search by postal code and street

curl -G "https://app.companydata.com/api/company/search?page=1&pageSize=25&countryCode=NL&postalCode=1012AB&streetName=Dam" \
  -H "x-api-key: {ApiKey}"

Company Export

Endpoint: /api/company/export

The /api/company/export endpoint allows users to request a specific set of fields related to company data. The fields returned by this endpoint depend on the type of package purchased by the client.

Returned Fields

• The set of fields returned is determined by the client's subscription package. This could include detailed company information such as financial data, employee count, or contact information.

Important Notes

• Package-Dependent Fields: The fields returned by this endpoint are customized based on the client's purchased package. For more information contact support.
• Use Case: This endpoint is used for getting a full company profile, often used in CRM's or for purposing of contacting or researching a company.

Pagination

The /api/company/export endpoint supports two pagination methods to retrieve company data:

1. Standard Pagination

Standard pagination uses page and pageSize parameters and is suitable for most use cases.

Characteristics:

• Maximum of 10,000 records retrievable
• Simple page-based navigation
• Best for small to medium datasets
• Backwards compatible with existing implementations

Example:

curl -G https://app.companydata.com/api/company/export?page=1&pageSize=100&countryCode=NL \
  -H "x-api-key: {ApiKey}" \
  -d "export=true"

2. Scroll Pagination

Scroll pagination is designed for retrieving large datasets without record limits. It uses a cursor-based approach with a scrollId that tracks your position in the result set.

Characteristics:

• Unlimited records: No maximum record limit
• Cursor-based: Uses scrollId to track position
• Time-limited context: Scroll context expires after 8 minutes
• Efficient for large exports: Ideal for bulk data retrieval

How it works:

1. Initial Request: Set useScroll=true to start a scroll session
2. Subsequent Requests: Use the scrollId from the previous response to get the next batch
3. Continue until complete: Keep requesting with the latest scrollId until hasMoreRecords is false
4. Expiration: If more than 8 minutes pass between requests, the scroll context expires and you'll need to start a new scroll session

Important Notes:

• Always use the latest scrollId: Each response includes a new scrollId that must be used for the next request
• Scroll context expires after 8 minutes: If you don't make a request within 8 minutes, the scroll session expires
• Don't mix pagination methods: Once you start with scroll pagination, continue using scrollId until completion
• Backwards compatible: Standard pagination continues to work unchanged

Example - Initial Scroll Request:

curl -G https://app.companydata.com/api/company/export?useScroll=true&pageSize=1000&countryCode=NL \
  -H "x-api-key: {ApiKey}" \
  -d "export=true"

Example - Subsequent Scroll Requests:

curl -G https://app.companydata.com/api/company/export?useScroll=true&scrollId=abc123xyz&pageSize=1000 \
  -H "x-api-key: {ApiKey}" \
  -d "export=true"

Example - Complete Scroll Pagination Flow:

const axios = require('axios');

const apiKey = 'YOUR_API_KEY';
const url = 'https://app.companydata.com/api/company/export';

async function exportAllCompanies(filters) {
  let scrollId = null;
  let hasMoreRecords = true;
  let allRecords = [];
  let pageCount = 0;

  try {
    // Initial request
    let response = await axios.get(url, {
      headers: { 'x-api-key': apiKey },
      params: {
        useScroll: true,
        pageSize: 1000,
        ...filters,
        export: true
      }
    });

    while (hasMoreRecords) {
      const { data, scrollId: newScrollId, hasMoreRecords: more } = response.data;
      
      allRecords = allRecords.concat(data);
      pageCount++;
      console.log(`Page ${pageCount}: Retrieved ${data.length} records (Total: ${allRecords.length})`);
      
      hasMoreRecords = more;
      scrollId = newScrollId;

      if (hasMoreRecords) {
        // Wait a bit to avoid rate limiting
        await new Promise(resolve => setTimeout(resolve, 100));
        
        // Fetch next page with latest scrollId
        response = await axios.get(url, {
          headers: { 'x-api-key': apiKey },
          params: {
            useScroll: true,
            scrollId: scrollId,  // Use latest scrollId
            pageSize: 1000,
            ...filters,
            export: true
          }
        });
      }
    }

    console.log(`Export complete! Total records: ${allRecords.length}`);
    return allRecords;
  } catch (error) {
    console.error('Export error:', error);
    throw error;
  }
}

// Usage
exportAllCompanies({ countryCode: 'NL' })
  .then(records => {
    console.log(`Successfully exported ${records.length} companies`);
  });

Response Structure for Scroll Pagination:

When using scroll pagination, the response includes additional fields:

{
  "data": [
    {
      "ID": "12345",
      "Company Name": "Example Company",
      // ... other fields
    }
  ],
  "scrollId": "abc123xyz456",
  "hasMoreRecords": true,
  "pageSize": 1000,
  "totalRecords": null  // Not available in scroll mode
}

Response Fields:

• data: Array of company records
• scrollId: Unique identifier for the scroll session. Always use the latest scrollId from the most recent response
• hasMoreRecords: Boolean indicating if more records are available
• pageSize: Number of records in the current response

Example Request

Export the first 25 companies from Rotterdam, the Netherlands with the Sic Code 3221, for glassware.

curl -G https://app.companydata.com/api/company/export?page=1&pageSize=25&sic4Digits=3221&countryCode=NL&cityName=Rotterdam? \
  -H "x-api-key: {ApiKey}" \
  -d "export=true"

Query Parameters

Below is a list of query parameters that can be used to filter the results returned by this endpoint. Export and search support the same parameters.

Pagination Parameters

Filter Parameters

Address Search

The streetName parameter allows searching companies by street address. It supports partial matching, so you don't need to type the full street name.

Address Parameters

How streetName works

• Matches from the beginning of words in the address
• Case insensitive
• You can type a partial street name and it will match

Location names require exact values

Unlike streetName, the parameters cityName, provinceName, regionName, and countryName require exact values. City names, provinces, and regions do not have international standards or ISO codes, so spelling and formatting can vary between countries and languages (e.g. "Den Haag" vs "'s-Gravenhage", "Munich" vs "Munchen").

To get the correct value, use the lookup endpoints to search for the exact name as it exists in our database.

Lookup Endpoints

All lookup endpoints accept the same parameters:

The API returns a data array of matching values. Use these exact values in your search or export requests.

Lookup Examples

Look up a city name:

GET /api/cities?search=ams&countries=NL&limit=100
→ {"data": [{"cityName": "AMSTELVEEN", "countryCode": "NL"}, {"cityName": "AMSTERDAM", "countryCode": "NL"}, ...], "total": 9, "limit": 100}

Look up a province:

GET /api/provinces?search=Noord&countries=NL
→ {"data": [{"provinceName": "NOORD-BRABANT", "countryCode": "NL"}, {"provinceName": "NOORD-HOLLAND", "countryCode": "NL"}], ...}

Look up a region:

GET /api/regions?search=Bava&countries=DE
→ {"data": [{"regionName": "BAVARIA", "countryCode": "DE"}], ...}

Recommended usage

For best results, first look up the exact city name via the lookup endpoint, then combine it with streetName.

Step 1 — Find the city name:

GET /api/cities?search=Amster&countries=NL
→ {"data": [{"cityName": "AMSTERDAM", "countryCode": "NL"}, ...], ...}

Step 2 — Search with exact city + partial street:

GET /api/company/search?countryCode=NL&cityName=AMSTERDAM&streetName=Keizersgracht

More address search examples

Country + postal code + street:

GET /api/company/search?countryCode=NL&postalCode=1012AB&streetName=Dam

Country + postal code range + street (numeric range):

GET /api/company/search?countryCode=NL&postalCodeInteger[min]=1000&postalCodeInteger[max]=1099&streetName=Dam

Country + street only (broader search):

GET /api/company/search?countryCode=NL&streetName=Sumatra

Province + street + additional filters:

GET /api/company/search?countryCode=DE&provinceName=BAVARIA&streetName=Friedrich&hasEmail=true

Available on

• GET /api/company/search
• GET /api/company/export