Fetch Businesses

Description

The Fetch Businesses endpoint allows users to retrieve business records based on filters such as country, industry, company size, and revenue. It returns a structured dataset optimized for further filtering, deduplication, or previewing records before enrichment. This enables precise data-driven decision-making and lead generation. It is designed to help users efficiently find relevant businesses based on their specific criteria.

Coverage

80M+ businesses across 150+ countries.
Advanced filtering options for precise data extraction.
Optimized for efficiency, returning only the minimal data needed for further processing.

How It Works

Input: Define filter parameters such as country, industry, revenue range, and company size.
Processing: The system searches across multiple datasets to retrieve businesses that meet the criteria.
Output: A structured response containing business records for further analysis or enrichment.

Request Schema

JSON

{
  "filters": {
    "country_code": {
      "values": ["us", "ca"]
    },
    "company_size": {
      "values": ["11-50", "51-200"]
    }
  }
}

Pagination, Filtering & Modes Parameters

Data Fetching: Pagination, Filtering & Modes

The API supports flexible data fetching through pagination, filtering, and optional modes to customize the amount and structure of the returned data.

Pagination

To efficiently retrieve large datasets, use the following parameters to paginate the results:

Parameter	Type	Description
`size`	Number	The total maximum number of records to return across all pages. Must be ≤ 60,000.
`page_size`	Number	Number of records to return per page. Maximum value: 100.
`page`	Number	The page number to retrieve (1-based index). Defaults to 1 if not specified.

Behavior Notes

If size is smaller than page_size * page, the last page may contain fewer records or be empty.
If pagination parameters are omitted, the API may return a default page size (implementation-specific).

Filtering

Filters allow you to narrow down results based on specific field values. All filters must be included in the request body under the "filters" key, as a JSON object.Each filter field accepts:

values: for multiple possible matches (e.g. "values": ["11-50", "51-200"])

Example Request Body

JSON

{
    "filters": {
        "company_size": {
            "values": ["11-50", "51-200"]
    }
  }
}

Filter Matching Logic

Fields using values are matched using an OR condition.
Filters are combined using an AND across different fields.

Mode Parameter

The optional mode parameter defines the level of detail in the returned data.

Mode	Description
`full`	Returns the complete data object for each prospect. Use this when full detail is required for processing or display.

Best Practices

Always use page_size to control payload size for better performance.
Use size to set an upper limit and avoid unintentionally requesting large datasets.
Apply filters whenever possible to reduce response size and processing time.

Note on Filter Usage

Only one category filter can be used per request: choose from either Google category, LinkedIn industry, or NAICS code. Combining them is not supported.

Business Filters

Parameter	Description	Notes / Best Practices
`country_code`	Filter accounts by their HQ’s country using alpha-2 country codes. Example: `["us", "ca"]`	- Use autocomplete to search by country name and select the correct two-letter code. - Uses a list of `values`. - Logic checks whether the country code matches the account location.
`region_country_code`	Filter accounts by their HQ’s region using ISO 3166-2 country-subdivision codes. Example: `["us-ut", "us-ca"]`	- Use autocomplete to search for a region after selecting a country. Format will automatically apply as `country-region` (e.g., `us-ca`). - Uses multiple `values`. - Logic verifies if the region code matches the structured field.
`city_region_country`	Filter accounts by geographic region, down to city-level granularity. Example: `["San Francisco, CA, US"]`	- Use autocomplete with cascading dropdowns (country → region → city). - Accepts a list of full location strings. - Logic checks address fields for match.
`company_size`	Filter accounts by the number of employees at all company sites. Categories: `["1-10", "11-50", ..., "10001+"]`	- Use autocomplete to search and select a size bracket from the predefined list. - Uses multiple `values`. - Logic maps input values to normalized size brackets.
`company_revenue`	Filter accounts by annual revenue generated at all company sites. Categories: `["0-500K", ..., "10B-100B"]`	- Use autocomplete to search and select a revenue range from the predefined list. - Accepts a list of `values`. - Logic compares revenue input against company revenue fields.
`company_age`	Filter accounts by how many years since they were established. Categories: `["0-3", "3-6", ..., "20+"]`	- Use autocomplete to select a range representing company age. - Accepts multiple `values`. - Logic compares establishment year against current date to determine match.
`google_category`	Filter accounts by their classified Google business category. Example: `["Paving contractor", "Retail"]`	- Use autocomplete to search and select from Google’s list of business categories. - Accepts `values`. - Logic filters companies based on Google’s classification field.
`naics_category`	Filter accounts by their 2017 NAICS industry code. Example: `["23", "5611"]`	- Use autocomplete to search and select valid NAICS industry codes. - Uses multiple `values`. - Logic matches selected code to structured industry metadata.
`linkedin_category`	Filter accounts by their classified LinkedIn® business category. Example: `["software development", "investment banking"]`	- Use autocomplete to search and select from LinkedIn® list of industry categories. - Accepts a list of `values`. - Logic filters based on LinkedIn® business category field.
`company_tech_stack_category`	Filter accounts by the technology categories they use. Example: `["Marketing", "CRM", "Cloud Services"]`	- Use autocomplete to search and select technology categories from a predefined list. - Uses multiple `values`. - Logic checks whether the account is associated with technologies in those categories.
`company_tech_stack_tech`	Filter accounts by the specific technologies they use. Example: `["JavaScript", "HTML5", "Apache"]`	- Use autocomplete to search and select specific technologies from the available list. - Accepts a list of `values`. - Logic checks for presence of selected technologies in the company’s tech stack.
`company_name`	Filter accounts by specific company names. Example: `["Google", "Walmart"]`	- Use autocomplete to search and select company names. - Accepts one or more `values`. - Logic performs exact or fuzzy match depending on configuration.
`number_of_locations`	Filter accounts by how many office locations they operate. Example: `["1", "2-5", "6+"]`	- Use autocomplete to select location range. - Accepts a list of `values`. - Logic checks for company location count metadata.
`website_keywords`	Filter accounts by specific keywords mentioned on their websites. Example: `["sustainability", "machine learning"]`	- Use keyword search to find companies mentioning certain terms. - Accepts free-text keywords or predefined tags. - Logic performs keyword match in indexed website content.
`topics`	Filters businesses based on active research around specific intent topics, returning`business_id` values of companies demonstrating relevant interest. Example: `["machine learning & artificial intelligence: openai", "technology: iphone"]`	- Accepts one or more topic strings following Bombora’s taxonomy. - Returns businesses with a composite score >60 for at least one matching topic. - Recommended for pre-filtering businesses prior to enrichment or campaign targeting - Use the autocomplete endpoint with `business_intent_topics` — and with`semantic_search=true` — to discover broader and smarter intent-topic suggestions. Enabling semantic search helps surface wider contextual topics that users are actively researching, ensuring more accurate and effective filtering.

Targeting Mid-Sized B2B Software Companies in California for CRM Sales

Use Case:A CRM software vendor wants to sell customer relationship management tools to mid-sized software companies in California. The filters ensure that companies already use CRM tools but may be looking for an upgrade.

Filters:

Country: ["us"]
Region (State): ["us-ca"]
Company Size: ["201-500"]
Company Revenue: ["10M-25M"]
LinkedIn® category: ["software development"]
Company Tech Stack Category: ["CRM"]

Finding Large Public Healthcare Companies in Texas for IT Security Solutions

Use Case:A cybersecurity provider wants to target large, publicly traded healthcare companies in Texas that use cloud services and have significant revenue, indicating budget availability for IT security improvements.

Filters:

Country: ["us"]
Region (State): ["us-tx"]
Company Size: ["1001-5000", "5001-10000", "10001+"]
Company Revenue: ["200M-500M", "500M-1B", "1B-10B", "10B-100B"]
NAICS Category: ["62"] (Healthcare & Social Assistance)
Company Tech Stack Category: ["Cloud Services", "Cybersecurity"]

Example Request (cURL)

Bash

curl -X POST \
  "https://api.explorium.ai/v1/businesses" \
  -H "API_KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "full",
    "size": 10000,
    "page_size": 100,
    "page": 1,
    "exclude": ["00000230f8f8d86e167e189c7c3b4bd6"],
    "filters": {
      "country_code": {
        "values": ["us"]
      },
      "company_size": {
        "values": ["11-50", "51-200"]
      }
    },
    "request_context": {}
  }'

For detailed endpoint explanations, request examples, and integration tips, explore the documentation sections above.

Body Params - Try Me Example

mode: full
size: 10000
page_size: 100
page: 1
Filters:
  country_code: us
  company_size: 11-50, 51-200

Authorizations

api_key

string

header

required

Body

application/json

mode

enum<string>

required

The mode of fetching businesses.

Available options:

full,

preview

Example:

"full"

size

integer

required

The number of businesses to fetch.

Required range: 1 <= x <= 60000

Example:

3

page_size

integer

required

The maximum number of businesses to fetch.

Required range: 1 <= x <= 500

Example:

3

request_context

Request Context · object

Example:

null

page

integer | null

default:1

The page number to fetch.

Required range: x >= 1

Example:

1

exclude

string[] | null

List of business ids to exclude from the response.

Maximum array length: 1000

Example:

null

filters

Filters · object

Show child attributes

filters.country_code

Country Code · object

A two-letter country code (ISO Alpha-2 format).

Show child attributes

filters.country_code.values

string[]

required

filters.country_code.negate

boolean

Example:

{ "values": ["US", "CA"] }

filters.region_country_code

Region Country Code · object

Filter prospects by region using ISO 3166-2 codes. Example: [us-ut, us-ca].

Show child attributes

filters.region_country_code.values

string[]

required

filters.region_country_code.negate

boolean

Example:

{ "values": ["US-CA", "IL-TA"] }

filters.company_size

Company Size · object

Filter accounts by the number of employees at all company sites. Categories: [1-10, 11-50, ..., 10001+].

Show child attributes

filters.company_size.values

enum<string>[]

required

The NumberOfEmployeesRange class is an enumeration that represents predefined ranges for the number of employees in a company. These ranges are used for filtering and categorizing companies based on their workforce size.

Available options:

1-10,

11-50,

51-200,

201-500,

501-1000,

1001-5000,

5001-10000,

10001+

filters.company_size.negate

boolean

Example:

{
  "values": [
    "1-10",
    "11-50",
    "51-200",
    "201-500",
    "501-1000",
    "1001-5000",
    "5001-10000",
    "10001+"
  ]
}

filters.company_revenue

Company Revenue · object

Filter by company’s annual revenue. Options: [0-500K, 500K-1M, ..., 10B-100B].

Show child attributes

filters.company_revenue.values

enum<string>[]

required

The RevenueRange class is an enumeration that represents predefined ranges for the revenue of a company.

Available options:

0-500K,

500K-1M,

1M-5M,

5M-10M,

10M-25M,

25M-75M,

75M-200M,

200M-500M,

500M-1B,

1B-10B,

10B-100B,

100B-1T,

1T-10T,

10T+

filters.company_revenue.negate

boolean

Example:

{
  "values": [
    "0-500K",
    "500K-1M",
    "1M-5M",
    "5M-10M",
    "10M-25M",
    "25M-75M",
    "75M-200M",
    "200M-500M",
    "500M-1B",
    "1B-10B",
    "10B-100B",
    "100B-1T",
    "1T-10T",
    "10T+"
  ]
}

filters.company_age

Company Age · object

Filter accounts by how many years since they were established. Categories: [0-3, 3-6, ..., 20+].

Show child attributes

filters.company_age.values

enum<string>[]

required

The CompanyAgeRange class is an enumeration that inherits from BaseFilterEnum.

It represents predefined ranges for the age of a company, such as "0-3 years" or "20+ years". This enum is used to categorize companies based on their age, ensuring consistent filtering and comparison across the application. Each range is defined as a string value for easy conversion and usage.

Available options:

0-3,

3-6,

6-10,

10-20,

20+

filters.company_age.negate

boolean

Example:

{
  "values": ["0-3", "3-6", "6-10", "10-20", "20+"]
}

filters.google_category

Google Category · object

Filter by company’s Google business category. Example: [Paving contractor, Retail].

Show child attributes

filters.google_category.values

string[]

required

filters.google_category.negate

boolean

Example:

{ "values": ["Retail"] }

filters.naics_category

NAICS Category · object

Filter accounts by their 2017 NAICS industry code. Example: [23, 5611].

Show child attributes

filters.naics_category.values

string[]

required

filters.naics_category.negate

boolean

Example:

{ "values": ["541512"] }

filters.linkedin_category

LinkedIn Category · object

Filter accounts by their classified LinkedIn business category. Example: [software development, investment banking].

Show child attributes

filters.linkedin_category.values

string[]

required

filters.linkedin_category.negate

boolean

Example:

{ "values": ["Market research"] }

filters.company_tech_stack_category

Company Tech Stack Category · object

Filter accounts by the technology categories they use. Example: [Marketing, CRM, Cloud Services].

Show child attributes

filters.company_tech_stack_category.values

string[]

required

filters.company_tech_stack_category.negate

boolean

Example:

{
  "values": [
    "Business Intelligence And Analytics",
    "Devops And Development"
  ]
}

filters.company_tech_stack_tech

Company Tech Stack Tech · object

Filter accounts by the specific technologies they use. Example: [JavaScript, HTML5, Apache].

Show child attributes

filters.company_tech_stack_tech.values

string[]

required

filters.company_tech_stack_tech.negate

boolean

Example:

{
  "values": ["JavaScript", "HTML5", "Apache"]
}

filters.company_name

Company Name · object

Filter accounts by specific company names. Example: [Microsoft, Walmart].

Show child attributes

filters.company_name.values

string[]

required

Maximum string length: 256

filters.company_name.negate

boolean

Example:

{ "values": ["Microsoft", "Google"] }

filters.number_of_locations

Number of Locations · object

Filter accounts by how many office locations they operate. Example: [1, 2-5, 6+].

Show child attributes

filters.number_of_locations.values

enum<string>[]

required

The NumberOfLocations class is an enumeration that represents predefined ranges

Available options:

0-1,

2-5,

6-20,

21-50,

51-100,

101-1000,

1001+

filters.number_of_locations.negate

boolean

Example:

{
  "values": [
    "0-1",
    "2-5",
    "6-20",
    "21-50",
    "51-100",
    "101-1000",
    "1001+"
  ]
}

filters.city_region_country

City Region Country · object

Filter accounts by geographic region, down to city-level granularity. Example: [San Francisco, CA, US].

Show child attributes

filters.city_region_country.values

string[]

required

filters.city_region_country.negate

boolean

Example:

{
  "values": [
    "Paris, FR",
    "Tel Aviv, IL",
    "Miami, FL, US"
  ]
}

filters.website_keywords

Website Keywords · object

Filter accounts by exact phrases mentioned on their websites. Example: [summer camp, machine learning]

Show child attributes

filters.website_keywords.values

string[]

required

filters.website_keywords.negate

boolean

Example:

{
  "values": ["summer camp", "machine learning"]
}

filters.business_intent_topics

Business Intent Topics · object

Filter accounts by intent data topics with composite score levels. Automatically expands to include bucket suffixes (_low, _medium, _high).

Show child attributes

filters.business_intent_topics.topics

string[]

required

filters.business_intent_topics.negate

boolean

filters.business_intent_topics.topic_intent_level

enum<string>

An enumeration.

Available options:

emerging_intent,

high_intent,

very_high_intent

Example:

{
  "topics": [
    "Security:Cloud Security",
    "HR:Employee Benefits",
    "Smartphones:iPhone"
  ],
  "topic_intent_level": "high_intent"
}

Example:

{}

next_cursor

string | null

The sort values from the last document returned by the previous page. If provided, cursor pagination is used instead of page-based pagination. send "null" to start with next_cursor pagination from the beginning.

Example:

null

Response

Successful Response

BusinessesFetchResponse
BusinessesFetchResponseV2

This is base response model for all responses in partner service.

response_context

ResponseContext · object

required

Show child attributes

response_context.correlation_id

string

required

response_context.request_status

enum<string>

required

The RequestStatus class is an enumeration that defines the possible statuses of a request.

This enum is used to indicate whether a request was successful, missed, or failed. It ensures consistent handling of request statuses across the application.

Attributes: SUCCESS: Indicates that the request was successfully processed. MISS: Indicates that the request did not find any matching data. FAILURE: Indicates that the request encountered an error or failure.

Available options:

success,

miss,

failure

response_context.time_took_in_seconds

number

required

total_pages

integer

required

The total number of pages.

Required range: x >= 0

data

Business · object[]

List of businesses that match the filters.

Show child attributes

data.business_id

string

required

data.name

string

required

Maximum string length: 256

data.domain

string

Maximum string length: 2048

data.logo

string

data.country_name

string

data.number_of_employees_range

enum<string>

Available options:

1-10,

11-50,

51-200,

201-500,

501-1000,

1001-5000,

5001-10000,

10001+

data.yearly_revenue_range

enum<string>

The RevenueRange class is an enumeration that represents predefined ranges for the revenue of a company.

Available options:

0-500K,

500K-1M,

1M-5M,

5M-10M,

10M-25M,

25M-75M,

75M-200M,

200M-500M,

500M-1B,

1B-10B,

10B-100B,

100B-1T,

1T-10T,

10T+

data.website

string

data.business_description

string

data.region

string

data.naics

integer

data.naics_description

string

data.sic_code

string

data.sic_code_description

string

data.business_intent_topics

Business Intent Topics · object[]

total_results

integer

default:0

The total number of businesses that match the filters.

Required range: x >= 0

page

integer

default:1

The page number of the response.

Required range: x >= 0

Explorium AgentSource

Partners

Description

Targeting Mid-Sized B2B Software Companies in California for CRM Sales

Use Case:A CRM software vendor wants to sell customer relationship management tools to mid-sized software companies in California. The filters ensure that companies already use CRM tools but may be looking for an upgrade.

Filters:

Finding Large Public Healthcare Companies in Texas for IT Security Solutions

Use Case:A cybersecurity provider wants to target large, publicly traded healthcare companies in Texas that use cloud services and have significant revenue, indicating budget availability for IT security improvements.

Filters:

Body Params - Try Me Example

Authorizations

Body

Response

Explorium AgentSource

Partners

​Description

​Data Fetching: Pagination, Filtering & Modes

​Pagination

​Behavior Notes

​Filtering

​Example Request Body

​Filter Matching Logic

​Mode Parameter

​Best Practices

​ Note on Filter Usage

​ Targeting Mid-Sized B2B Software Companies in California for CRM Sales

​ Use Case:A CRM software vendor wants to sell customer relationship management tools to mid-sized software companies in California. The filters ensure that companies already use CRM tools but may be looking for an upgrade.

​ Filters:

​ Finding Large Public Healthcare Companies in Texas for IT Security Solutions

​ Use Case:A cybersecurity provider wants to target large, publicly traded healthcare companies in Texas that use cloud services and have significant revenue, indicating budget availability for IT security improvements.

​ Filters:

​Body Params - Try Me Example

Authorizations

Body

Response

Description

Data Fetching: Pagination, Filtering & Modes

Pagination

Behavior Notes

Filtering

Example Request Body

Filter Matching Logic

Mode Parameter

Best Practices

Note on Filter Usage

Targeting Mid-Sized B2B Software Companies in California for CRM Sales

Use Case:A CRM software vendor wants to sell customer relationship management tools to mid-sized software companies in California. The filters ensure that companies already use CRM tools but may be looking for an upgrade.

Filters:

Finding Large Public Healthcare Companies in Texas for IT Security Solutions

Use Case:A cybersecurity provider wants to target large, publicly traded healthcare companies in Texas that use cloud services and have significant revenue, indicating budget availability for IT security improvements.

Filters:

Body Params - Try Me Example