# Company Firmographics API - Business Data Search by Industry (`nabeelbaghoor/company-firmographics-api`) Actor

Search a global business firmographics database by industry code, country, region, employee count and revenue, and export company records with identifiers, addresses, industry codes and corporate linkage. Pay per result. Bring your own API key.

- **URL**: https://apify.com/nabeelbaghoor/company-firmographics-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Business, Developer tools, Lead generation
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$15.00 / 1,000 company results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Company Firmographics API - Business Data Search by Industry

Search a global business firmographics database and export structured company records: registered names, unique business identifiers, addresses, industry codes, employee counts, revenue and corporate linkage. You pay only for the records you actually receive.

This actor is built for building B2B target lists, cleaning and standardising an account database, supplier and vendor research, credit and risk screening, and any workflow that needs verified registered-business data rather than scraped web profiles.

### What you can do with it

- Build target lists of registered businesses that match an exact firmographic profile.
- Find every company in a country, region or city inside a set of SIC industry codes.
- Screen a market by employee count and annual revenue bands.
- Pull unique business identifiers so you can join the data to your CRM or ERP.
- Follow corporate linkage up to the global ultimate parent of each company.
- Export everything as JSON, CSV or Excel, or push it into your data warehouse.

### Features

- Firmographic filters: SIC industry codes, country, state or region, city, postal code.
- Size filters: minimum and maximum employee count, minimum and maximum yearly revenue.
- Quality filters: marketable records only, include or exclude out-of-business companies.
- Unique business identifier on every record, so results are joinable and de-duplicated.
- Corporate linkage: global ultimate parent identifier and name where available.
- Automatic page-based pagination up to your chosen maximum, with duplicate suppression.
- Advanced raw criteria passthrough for filters not exposed as form fields.
- Pay-per-result pricing with a hard result cap so a run can never surprise you.

### Input

Configure a run with these fields. Every field is optional; combine a search term with as many filters as you like to narrow the result set.

| Field | Type | Description |
| --- | --- | --- |
| `searchTerm` | string | Free-text term matched against company names and trade styles. |
| `primaryName` | string | Match on the registered primary company name. |
| `countryISOAlpha2Code` | string | Two-letter ISO country code, chosen from a dropdown. |
| `addressRegion` | string | State, province or region. |
| `addressLocality` | string | City. |
| `postalCode` | string | Postal or ZIP code. |
| `usSicV4` | string | Comma-separated four-digit SIC industry codes. |
| `employeesMin` / `employeesMax` | integer | Employee-count range. |
| `yearlyRevenueMin` / `yearlyRevenueMax` | number | Annual revenue range, in USD. |
| `isMarketable` | boolean | Return only records flagged as marketable. |
| `isOutOfBusiness` | boolean | Include companies flagged as out of business. |
| `rawCriteria` | object | Advanced JSON criteria merged over the fields above. |
| `maxResults` | integer | Stop after this many records (1 to 5,000). |
| `apiKey` | string | Your API key. Required, stored securely. |
| `apiSecret` | string | Your API secret. Required, stored securely. |

#### Advanced raw criteria

Criteria that are not exposed as dedicated fields can be passed through `rawCriteria` as a JSON object, merged over the built-in criteria verbatim. Pagination stays under the actor's control, so a raw object can never make a run loop. For example:

```json
{
  "isStandalone": true,
  "registrationNumbers": ["12345678"]
}
```

### Example output

Each dataset item is one company. Fields are populated where the provider has data, and the complete provider payload is kept under `raw`:

```json
{
  "duns": "804735132",
  "primaryName": "Acme Robotics Incorporated",
  "tradeStyleName": "Acme Robotics",
  "countryISOAlpha2Code": "US",
  "addressCountry": "United States",
  "addressRegion": "Texas",
  "addressLocality": "Austin",
  "streetAddress": "500 Congress Avenue",
  "postalCode": "78701",
  "telephone": "5125550100",
  "website": "acmerobotics.com",
  "primaryIndustryCode": "3559",
  "primaryIndustryDescription": "Special industry machinery",
  "numberOfEmployees": 180,
  "yearlyRevenue": 42000000,
  "isOutOfBusiness": false,
  "isMarketable": true,
  "operatingStatus": "Active",
  "globalUltimateDuns": "804735100",
  "globalUltimateName": "Acme Industrial Group Incorporated",
  "raw": { "organization": { "duns": "804735132" } }
}
```

### Pricing and the credit model

This actor uses pay-per-result pricing. You are charged a fixed price for each company record delivered to the dataset, and nothing for a run that returns no matches. Set `maxResults` to cap how many records a run can collect, and set a run spending limit as a second safety net. When the spending limit is reached the run stops early and keeps whatever it has already saved.

### Bring your own API key

This actor connects to a third-party business firmographics provider (Dun and Bradstreet Direct+) on your behalf and requires your own provider credentials. Enter your `apiKey` and `apiSecret` in the input. The actor exchanges them for a short-lived access token at the start of each run, refreshes the token automatically, and never ships with or shares credentials. Both values are stored securely and never logged.

### Frequently asked questions

#### What data does this actor return?

Registered-business firmographics: the primary company name and trade style, a unique business identifier, the primary address, telephone and website, SIC industry code and description, employee count, yearly revenue, operating status, and corporate linkage to the global ultimate parent. Every record also carries the complete raw provider payload.

#### How do I get an API key?

The underlying data API is a paid subscription product. Once your subscription is active the provider issues an API key and API secret, which you paste into the actor input. The actor never provides credentials of its own.

#### Which industry codes does it accept?

The `usSicV4` field accepts four-digit US SIC codes as a comma-separated list, for example `3661, 3663, 7372`. Companies matching any of the listed codes are returned.

#### How does pagination work?

Results are paged automatically at 50 records per page using page-based pagination, until your `maxResults` is reached or the provider returns a short page. Records are de-duplicated by their unique business identifier as they stream in.

#### How am I charged?

You pay a fixed price per company record returned to the dataset. A run that matches nothing costs nothing. Use `maxResults` and the run spending limit to control cost. Note that your provider subscription may separately meter the search calls the actor makes.

#### Can I filter on criteria that are not shown in the form?

Yes. Use the advanced `rawCriteria` JSON object to pass any additional criteria, which are merged over the built-in ones. This is the reliable route for account-specific criteria that your subscription enables.

#### What happens if the provider rate-limits my key?

The actor honours the retry-after signal, backs off exponentially and retries. If the limit is still in force it stops early and keeps everything already collected rather than failing the whole run.

#### What output formats are available?

The dataset can be exported as JSON, CSV, Excel, HTML or RSS, or read through the API for pushing into a CRM or warehouse.

### Keyword map

company firmographics, business data api, company search api, firmographic data, business identifier lookup, sic code search, company database, b2b company data, business registry data, company enrichment, employee count data, company revenue data, corporate linkage, ultimate parent company, account data cleansing, crm data enrichment, supplier data, vendor screening, market sizing, b2b prospecting data.

# Actor input Schema

## `searchTerm` (type: `string`):

Free-text term matched against company names and trade styles, e.g. `acme robotics`. Combine with the filters below to narrow the result set.

## `primaryName` (type: `string`):

Match on the registered primary company name, e.g. `Acme Robotics Inc`.

## `countryISOAlpha2Code` (type: `string`):

Restrict results to companies registered in this country. Uses two-letter ISO country codes.

## `addressRegion` (type: `string`):

Restrict results to this state, province or region, e.g. `California`, `Bavaria`.

## `addressLocality` (type: `string`):

Restrict results to this city, e.g. `Austin`, `London`.

## `postalCode` (type: `string`):

Restrict results to this postal or ZIP code, e.g. `94105`.

## `usSicV4` (type: `string`):

Comma-separated four-digit US SIC industry codes to match, e.g. `3661, 3663, 7372`. Companies in any of the listed industries are returned.

## `employeesMin` (type: `integer`):

Only companies with at least this many employees, e.g. `10`.

## `employeesMax` (type: `integer`):

Only companies with at most this many employees, e.g. `500`.

## `yearlyRevenueMin` (type: `number`):

Only companies with at least this much annual revenue, in USD, e.g. `1000000`.

## `yearlyRevenueMax` (type: `number`):

Only companies with at most this much annual revenue, in USD.

## `isMarketable` (type: `boolean`):

When enabled, return only records the provider flags as marketable, which filters out many incomplete entries.

## `isOutOfBusiness` (type: `boolean`):

When enabled, include companies flagged as out of business. Off by default.

## `rawCriteria` (type: `object`):

Power users: a JSON object of raw search criteria merged over the fields above, verbatim. Use this for criteria not exposed as fields, e.g. `{ "isStandalone": true, "registrationNumbers": ["12345678"] }`. Pagination stays under the actor's control.

## `maxResults` (type: `integer`):

Stop after this many company records (1-5,000). Paged automatically at 50 per page. You are charged per result returned.

## `apiKey` (type: `string`):

Your own API key for the data provider. Required. Used with the API secret below to obtain a short-lived access token. Stored securely and never logged.

## `apiSecret` (type: `string`):

Your own API secret for the data provider. Required. Stored securely and never logged.

## Actor input object example

```json
{
  "isMarketable": false,
  "isOutOfBusiness": false,
  "maxResults": 100
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "usSicV4": "",
    "maxResults": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/company-firmographics-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "usSicV4": "",
    "maxResults": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/company-firmographics-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "usSicV4": "",
  "maxResults": 100
}' |
apify call nabeelbaghoor/company-firmographics-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=nabeelbaghoor/company-firmographics-api",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/UZnjlZIM95vJvkrbo/builds/VVdqdyZf296TFnB9c/openapi.json