Fetch Businesses

Endpoint: `POST /v1/businesses`

Purpose:

Retrieves businesses based on filters such as country, industry, and company size.

Modes: full.

Request Schema:

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

Filters Object:

Filters are provided in the request body inside the filters key. Each filter has:

Type: the filter type (e.g., includes, exists, range, any_match).
Values or value: the value(s) to filter by.

Pagination Parameters:

Fetching data supports pagination.
Use the following parameters to control pagination:

Field	Type	Description
`size`	Number	Maximum number of results to return (up to 1000)
`page_size`	Number	Maximum number of records per page (up to 100)
`page`	Number	Page number to retrieve

Mode Parameter:

The fetch endpoints support a mode to define how much data to return:

Value	Description
`full`	Returns all available data for businesses

Business Filters:

Filter	Type	Description
`country_code`	String	Filters businesses by country (e.g., "us", "ca")
`region_country_code`	String	Filters businesses by specific regions within countries (e.g., "us-ca")
`company_size`	String	Filters by number of employees (e.g., "11-50", "51-200", "1001+")
`company_revenue`	String	Filters by annual revenue (e.g., "1M-5M", "10B-100B")
`company_age`	String	Filters by years since establishment (e.g., "0-3", "20+")
`google_category`	String	Filters by Google’s classification (e.g., "retail", "consulting")
`naics_category`	String	Filters by NAICS industry classification (e.g., "23", "5611")
`linkedin_category`	String	Filters by LinkedIn industry classification (e.g., "software development")

Example Request (cURL):

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": {
        "type": "includes",
        "values": ["us"]
      },
      "company_size": {
        "type": "includes",
        "values": ["11-50", "51-200"]
      }
    },
    "request_context": {}
  }'

Example Request (Python):

import requests

url = "https://api.explorium.ai/v1/businesses"
headers = {
    "API_KEY": "your_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "mode": "full",
    "size": 10000,	
    "page_size": 100,
    "page": 1,
    "exclude": ["1234", "5678"],
    "filters": {
        "country_code": {
            "type": "includes",
            "values": ["us"]
        },
        "company_size": {
            "type": "includes",
            "values": ["11-50", "51-200"]
        }
    },
    "request_context": {}
}

resp = requests.post(url, headers=headers, json=payload)
print(resp.json())

Response Examples: Mode = full:

{
  "total_results": 2,
  "page": 1,
  "total_pages": 10,
  "data": [
    {
      "name": "apple inc",
      "domain": "apple.com",
      "logo": "logo url",
      "country": "us",
      "number_of_employees": "+10001",
      "yearly_revenue": "+10B",
      "business_id": "kj23hy8472348723h234234",
      ...
    },
    {
      "name": "microsoft",
      "domain": "microsoft.com",
      "logo": "logo url",
      "country": "us",
      "number_of_employees": "+10001",
      "yearly_revenue": "+10B",
      "business_id": "hp09sdf97s988723h239343",
      ...
    }
  ]
}

Endpoint: POST /v1/businesses