Explorium Businesses API
Match, fetch, stat, autocomplete, and event/enrollment operations over the Explorium business dataset (v1).
OpenAPI Specification
openapi: 3.2.0
info:
title: Partner Service Businesses API
version: 0.3.19
servers:
- url: https://api.explorium.ai
description: AgentSource Server
tags:
- name: Businesses
paths:
/v1/businesses/match:
post:
tags:
- Businesses
summary: Match Businesses
description: 'Match a list of businesses attributes to ids.
Returns a list of the same length and order as the input list, with the matched ids.'
operationId: match_businesses
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessesMatchRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessesMatchResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- APIKeyHeader: []
/v1/businesses:
post:
tags:
- Businesses
summary: Fetch Businesses
description: 'Filters businesses by country, company size, revenue, and more.
Returns minimal data needed for further filtering, deduplication, or record previews.'
operationId: fetch_businesses
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessesFetchRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/BusinessesFetchResponse'
- $ref: '#/components/schemas/BusinessesFetchResponseV2'
title: Response Fetch Businesses
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- APIKeyHeader: []
/v1/businesses/events:
post:
tags:
- Businesses
summary: Fetch Businesses Events
description: Create events and fetch for businesses.
operationId: fetch_businesses_events
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessesEventsRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- APIKeyHeader: []
/v1/businesses/autocomplete:
get:
tags:
- Businesses
summary: Autocomplete Businesses
description: Autocomplete businesses by field and query.
operationId: businesses_autocomplete
parameters:
- required: true
schema:
$ref: '#/components/schemas/AutocompleteType'
name: field
in: query
- required: false
schema:
type: string
title: Query
default: ''
name: query
in: query
- required: false
schema:
type: boolean
title: Semantic Search
default: false
name: semantic_search
in: query
responses:
'200':
description: Successful Response
content:
application/json:
schema:
items:
$ref: '#/components/schemas/AutoCompleteItem'
type: array
title: Response Businesses Autocomplete
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- APIKeyHeader: []
/v1/businesses/stats:
post:
tags:
- Businesses
summary: Fetch Stats
description: Fetch stats for businesses.
operationId: fetch_stats
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessesStatsRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessesStatsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- APIKeyHeader: []
/v1/businesses/events/enrollments:
get:
tags:
- Businesses
summary: Get Businesses Enrollments
description: Show businesses events enrollments records for user.
operationId: get_businesses_enrollments
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessesEnrollmentsGetResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- APIKeyHeader: []
post:
tags:
- Businesses
summary: Add Businesses Enrollments
description: Add enrollments for businesses
operationId: add_businesses_enrollments
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessesEnrollmentsAddRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessesEnrollmentsAddResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- APIKeyHeader: []
delete:
tags:
- Businesses
summary: Delete Businesses Enrollments
description: Delete events enrollments records
operationId: delete_businesses_enrollments
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessesEnrollmentsDeleteRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessesEnrollmentsDeleteResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- APIKeyHeader: []
patch:
tags:
- Businesses
summary: Update Businesses Enrollments
description: Update enrollments for businesses
operationId: update_businesses_enrollments
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessesEnrollmentsUpdateRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessesEnrollmentsUpdateResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- APIKeyHeader: []
components:
schemas:
BusinessesEnrollmentsDeleteRequest:
properties:
request_context:
type: object
title: Request Context
marked_for_null_replacement: true
nullable: true
enrollment_id:
type: string
title: Enrollment Id
additionalProperties: false
type: object
required:
- enrollment_id
title: BusinessesEnrollmentsDeleteRequest
IncludesFilter_RevenueRange_:
properties:
negate:
type: boolean
title: Negate
values:
items:
$ref: '#/components/schemas/RevenueRange'
type: array
additionalProperties: false
type: object
required:
- values
title: IncludesFilter[RevenueRange]
BusinessesEventIdentifier:
type: string
enum:
- ipo_announcement
- new_funding_round
- new_investment
- new_product
- new_office
- closing_office
- new_partnership
- increase_in_engineering_department
- increase_in_sales_department
- increase_in_marketing_department
- increase_in_operations_department
- increase_in_customer_service_department
- increase_in_all_departments
- decrease_in_engineering_department
- decrease_in_sales_department
- decrease_in_marketing_department
- decrease_in_operations_department
- decrease_in_customer_service_department
- decrease_in_all_departments
- employee_joined_company
- hiring_in_creative_department
- hiring_in_education_department
- hiring_in_engineering_department
- hiring_in_finance_department
- hiring_in_health_department
- hiring_in_human_resources_department
- hiring_in_legal_department
- hiring_in_marketing_department
- hiring_in_operations_department
- hiring_in_professional_service_department
- hiring_in_sales_department
- hiring_in_support_department
- hiring_in_trade_department
- hiring_in_unknown_department
- company_award
- outages_and_security_breaches
- cost_cutting
- merger_and_acquisitions
- lawsuits_and_legal_issues
title: BusinessesEventIdentifier
description: 'Enumeration of business-related event identifiers.
This enum defines various types of events associated with businesses, such as:
- Financial activities (e.g., IPO announcements, new funding rounds, new investments)
- Organizational changes (e.g., new offices, closing offices, mergers and acquisitions)
- Workforce trends (e.g., hiring in specific departments, increases or decreases in department sizes)
- Product and partnership updates (e.g., new products, new partnerships)
- Other significant events (e.g., company awards, outages, cost-cutting measures, legal issues)
These identifiers are used to categorize and track business events within the application.'
BaseFetchMode:
type: string
enum:
- full
- preview
title: BaseFetchMode
description: "The `BaseFetchMode` class is an enumeration that defines the modes for fetching data.\n\nThis enum is used to specify whether the fetch operation should retrieve the full data\nor just a preview of the data. It ensures consistent handling of fetch modes across\nthe application.\n\nAttributes:\n FULL: Fetch the complete data.\n PREVIEW: Fetch a preview or partial data."
CompanyAgeRange:
type: string
enum:
- 0-3
- 3-6
- 6-10
- 10-20
- 20+
title: CompanyAgeRange
description: '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.'
RequestStatus:
type: string
enum:
- success
- miss
- failure
title: RequestStatus
description: "The `RequestStatus` class is an enumeration that defines the possible statuses of a request.\n\nThis enum is used to indicate whether a request was successful, missed, or failed. It ensures\nconsistent handling of request statuses across the application.\n\nAttributes:\n SUCCESS: Indicates that the request was successfully processed.\n MISS: Indicates that the request did not find any matching data.\n FAILURE: Indicates that the request encountered an error or failure."
BusinessIntentTopicsIntentLevel:
enum:
- emerging_intent
- high_intent
- very_high_intent
title: BusinessIntentTopicsIntentLevel
description: An enumeration.
BusinessesFetchResponseV2:
properties:
response_context:
$ref: '#/components/schemas/ResponseContext'
data:
items:
$ref: '#/components/schemas/Business'
type: array
title: Data
description: List of businesses that match the filters.
default: []
total_results:
type: integer
minimum: 0.0
title: Total Results
description: The total number of businesses that match the filters.
default: 0
page:
allOf:
- $ref: '#/components/schemas/partner_service__models__services__requests__PageInfo'
title: Page
description: Page information including size and next cursor
type: object
required:
- response_context
- page
title: BusinessesFetchResponseV2
description: This is base response model for all responses in partner service.
IncludesFilter_StandardizedText_:
properties:
negate:
type: boolean
title: Negate
values:
items:
type: string
type: array
title: Values
additionalProperties: false
type: object
required:
- values
title: IncludesFilter[StandardizedText]
NumberOfLocations:
type: string
enum:
- 0-1
- 2-5
- 6-20
- 21-50
- 51-100
- 101-1000
- 1001+
title: NumberOfLocations
description: The `NumberOfLocations` class is an enumeration that represents predefined ranges
ExistsFilter:
properties:
negate:
type: boolean
title: Negate
value:
type: boolean
title: Value
additionalProperties: false
type: object
required:
- value
title: ExistsFilter
IncludesFilter_CompanyAgeRange_:
properties:
negate:
type: boolean
title: Negate
values:
items:
$ref: '#/components/schemas/CompanyAgeRange'
type: array
additionalProperties: false
type: object
required:
- values
title: IncludesFilter[CompanyAgeRange]
BusinessesEventsRequest:
properties:
request_context:
type: object
title: Request Context
marked_for_null_replacement: true
nullable: true
entity_type:
allOf:
- $ref: '#/components/schemas/EntityType'
default: business
event_types:
items:
$ref: '#/components/schemas/BusinessesEventIdentifier'
type: array
minItems: 1
timestamp_to:
anyOf:
- type: string
format: date-time
- type: string
title: Timestamp To
description: ISO format datetime string or date in format YYYY-MM-DD
marked_for_null_replacement: true
nullable: true
timestamp_from:
anyOf:
- type: string
format: date-time
- type: string
title: Timestamp From
description: ISO format datetime string or date in format YYYY-MM-DD
marked_for_null_replacement: true
nullable: true
business_ids:
items:
type: string
pattern: ^[a-f0-9]{32}$
type: array
maxItems: 40
minItems: 1
uniqueItems: true
title: Business Ids
additionalProperties: false
type: object
required:
- event_types
- business_ids
title: BusinessesEventsRequest
NumberOfEmployeesRange:
type: string
enum:
- 1-10
- 11-50
- 51-200
- 201-500
- 501-1000
- 1001-5000
- 5001-10000
- 10001+
title: NumberOfEmployeesRange
description: '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.'
RevenueRange:
type: string
enum:
- 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+
title: RevenueRange
description: The `RevenueRange` class is an enumeration that represents predefined ranges for the revenue of a company.
BusinessesEnrollmentsDeleteResponse:
properties:
response_context:
$ref: '#/components/schemas/ResponseContext'
status:
allOf:
- $ref: '#/components/schemas/RequestStatus'
default: success
type: object
required:
- response_context
title: BusinessesEnrollmentsDeleteResponse
description: This is base response model for all responses in partner service.
BusinessesStats:
properties:
business_categories_per_location:
type: object
title: Business Categories Per Location
revenue_per_category:
type: object
title: Revenue Per Category
number_of_employees_per_category:
type: object
title: Number Of Employees Per Category
type: object
title: BusinessesStats
BusinessesEnrollmentsGetResponse:
properties:
response_context:
$ref: '#/components/schemas/ResponseContext'
enrollments:
items:
$ref: '#/components/schemas/BusinessesEnrollment'
type: array
title: Enrollments
type: object
required:
- response_context
- enrollments
title: BusinessesEnrollmentsGetResponse
description: This is base response model for all responses in partner service.
BusinessesMatchRequest:
properties:
request_context:
type: object
title: Request Context
marked_for_null_replacement: true
nullable: true
businesses_to_match:
items:
$ref: '#/components/schemas/BusinessMatchInput'
type: array
maxItems: 50
minItems: 1
title: Businesses To Match
additionalProperties: false
type: object
required:
- businesses_to_match
title: BusinessesMatchRequest
BusinessesStatsResponse:
properties:
response_context:
$ref: '#/components/schemas/ResponseContext'
total_results:
type: integer
title: Total Results
stats:
$ref: '#/components/schemas/BusinessesStats'
type: object
required:
- response_context
- total_results
- stats
title: BusinessesStatsResponse
description: This is base response model for all responses in partner service.
BusinessMatchInput:
properties:
name:
type: string
maxLength: 256
title: Name
domain:
type: string
title: Domain
url:
type: string
title: Url
linkedin_url:
type: string
title: Linkedin Url
type: object
title: BusinessMatchInput
IncludesFilter_NAICS_:
properties:
negate:
type: boolean
title: Negate
values:
items:
type: string
pattern: ^\d{2,6}$
type: array
title: Values
additionalProperties: false
type: object
required:
- values
title: IncludesFilter[NAICS]
AutocompleteType:
enum:
- country
- country_code
- region_country_code
- google_category
- naics_category
- linkedin_category
- company_tech_stack_tech
- company_tech_stack_categories
- job_title
- company_size
- company_revenue
- number_of_locations
- company_age
- job_department
- job_level
- city_region_country
- company_name
- business_intent_topics
- city_region
- skills
- interests
title: AutocompleteType
description: Enum for autocomplete types.
partner_service__models__services__requests__PageInfo:
properties:
size:
type: integer
title: Size
description: Number of results in this page
next_cursor:
type: string
title: Next Cursor
description: Cursor for pagination. Use this value as cursor in the next request.
type: object
required:
- size
title: PageInfo
BusinessesEnrollmentsAddRequest:
properties:
request_context:
type: object
title: Request Context
marked_for_null_replacement: true
nullable: true
enrollment_key:
type: string
minLength: 4
title: Enrollment Key
event_types:
items:
$ref: '#/components/schemas/BusinessesEventIdentifier'
type: array
minItems: 1
business_ids:
items:
type: string
pattern: ^[a-f0-9]{32}$
type: array
maxItems: 20
minItems: 1
title: Business Ids
additionalProperties: false
type: object
required:
- enrollment_key
- event_types
- business_ids
title: BusinessesEnrollmentsAddRequest
BusinessesFetchResponse:
properties:
response_context:
$ref: '#/components/schemas/ResponseContext'
data:
items:
$ref: '#/components/schemas/Business'
type: array
title: Data
description: List of businesses that match the filters.
default: []
total_results:
type: integer
minimum: 0.0
title: Total Results
description: The total number of businesses that match the filters.
default: 0
page:
type: integer
minimum: 0.0
title: Page
description: The page number of the response.
default: 1
total_pages:
type: integer
minimum: 0.0
title: Total Pages
description: The total number of pages.
type: object
required:
- response_context
- total_pages
title: BusinessesFetchResponse
description: This is base response model for all responses in partner service.
BusinessesEnrollmentsUpdateResponse:
properties:
response_context:
$ref: '#/components/schemas/ResponseContext'
enrollment_key:
type: string
minLength: 4
title: Enrollment Key
enrollment_id:
type: string
title: Enrollment Id
type: object
required:
- response_context
- enrollment_key
- enrollment_id
title: BusinessesEnrollmentsUpdateResponse
description: This is base response model for all responses in partner service.
InternalEventIdentifier:
type: string
enum:
- prospect_changed_role
- prospect_changed_company
- prospect_job_start_anniversary
- ipo_announcement
- new_funding_round
- new_investment
- new_product
- new_office
- closing_office
- new_partnership
- merger_and_acquisitions
- hiring_in_creative_department
- hiring_in_education_department
- hiring_in_engineering_department
- hiring_in_finance_department
- hiring_in_health_department
- hiring_in_human_resources_department
- hiring_in_legal_department
- hiring_in_marketing_department
- hiring_in_operations_department
- hiring_in_professional_service_department
- hiring_in_sales_department
- hiring_in_support_department
- hiring_in_trade_department
- hiring_in_unknown_department
- increase_in_engineering_department
- increase_in_sales_department
- increase_in_marketing_department
- increase_in_operations_department
- increase_in_customer_service_department
- increase_in_all_departments
- decrease_in_engineering_department
- decrease_in_sales_department
- decrease_in_marketing_department
- decrease_in_operations_department
- decrease_in_customer_service_department
- decrease_in_all_departments
- employee_joined_company
- company_award
- outages_and_security_breaches
- cost_cutting
- lawsuits_and_legal_issues
title: InternalEventIdentifier
description: 'The `InternalEventIdentifier` class is an enumeration that defines internal event identifiers.
This enum is used to categorize and track internal events related to businesses and prospects.
All events are now handled internally through the event service.'
IncludesFilter_Text_:
properties:
negate:
type: boolean
title: Negate
values:
items:
type: string
type: array
title: Values
additionalProperties: false
type: object
required:
- values
title: IncludesFilter[Text]
BusinessesStatsRequest:
properties:
request_context:
type: object
title: Request Context
marked_for_null_replacement: true
nullable: true
filters:
$ref: '#/components/schemas/BusinessesFetchFilters'
additionalProperties: false
type: object
required:
- filters
title: BusinessesStatsRequest
BusinessesFetchFilters:
properties:
business_id:
allOf:
- $ref: '#/components/schemas/IncludesFilter_BusinessId_'
title: Business ID
description: Filter businesses by specific Explorium business IDs
example:
values:
- 8adce3ca1cef0c986b22310e369a0793
- 340c8040bd50cbab9c7df718bbe51cc9
nullable: true
country_code:
allOf:
- $ref: '#/components/schemas/IncludesFilter_CountryCodeAlpha2_'
title: Country Code
description: A two-letter country code (ISO Alpha-2 format).
example:
values:
- US
- CA
nullable: true
region_country_code:
allOf:
- $ref: '#/components/schemas/IncludesFilter_RegionCode_'
title: Region Country Code
description: 'Filter prospects by region using ISO 3166-2 codes. Example: [us-ut, us-ca].'
example:
values:
- US-CA
- IL-TA
nullable: true
company_size:
allOf:
- $ref: '#/components/schemas/IncludesFilter_NumberOfEmployeesRange_'
title: Company Size
description: 'Filter accounts by the number of employees at all company sites. Categories: [1-10, 11-50, ..., 10001+].'
example:
values:
- 1-10
- 11-50
- 51-200
- 201-500
- 501-1000
- 1001-5000
- 5001-10000
- 10001+
nullable: true
company_revenue:
allOf:
- $ref: '#/components/schemas/IncludesFilter_RevenueRange_'
title: Company Revenue
description: 'Filter by company’s annual revenue. Options: [0-500K, 500K-1M, ..., 10B-100B].'
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+
nullable: true
company_age:
allOf:
- $ref: '#/components/schemas/IncludesFilter_CompanyAgeRange_'
title: Company Age
description: 'Filter accounts by how many years since they were established. Categories: [0-3, 3-6, ..., 20+].'
example:
values:
- 0-3
- 3-6
- 6-10
- 10-20
- 20+
nullable: true
google_category:
allOf:
- $ref: '#/components/schemas/IncludesFilter_StandardizedText_'
title: Google Category
description: 'Filter by company’s Google business category. Example: [Paving contractor, Retail].'
example:
values:
- Retail
nullable: true
naics_category:
allOf:
- $ref: '#/components/schemas/IncludesFilter_NAICS_'
title: NAICS Category
description: 'Filter accounts by their 2017 NAICS industry code. Example: [23, 5611].'
example:
values:
- '541512'
nullable: true
linkedin_category:
allOf:
- $ref: '#/components/schemas/IncludesFilter_StandardizedText_'
title: LinkedIn Category
description: 'Filter accounts by their classified LinkedIn business category. Example: [software development, investment banking].'
example:
values:
- Market research
nullable: true
company_tech_stack_category:
allOf:
- $ref: '#/components/schemas/IncludesFilter_Text_'
title: Company Tech Stack Category
description: 'Filter accounts by the technology categories they use. Example: [Marketing, CRM, Cloud Services].'
example:
values:
- Business Intelligence And Analytics
- Devops And Development
nullable: true
company_tech_stack_tech:
allOf:
- $ref: '#/components/schemas/IncludesFilter_Text_'
title: Company Tech Stack Tech
description: 'Filter accounts by the specific technologies they use. Example: [JavaScript, HTML5, Apache].'
example:
values:
- JavaScript
- HTML5
- Apache
nullable: true
company_name:
allOf:
- $ref: '#/components/schemas/DynamicIncludesFilter_OrganizationName_'
title: Company Name
description: 'Filter accounts by specific company names. Example: [Microsoft, Walmart].'
example:
values:
- Microsoft
- Google
nullable: true
number_of_locations:
allOf:
- $ref: '#/components/schemas/IncludesFilter_NumberOfLocations_'
title: Number of Locations
description: 'Filter accounts by how many office locations they operate. Example: [1, 2-5, 6+].'
example:
values:
- 0-1
- 2-5
- 6-20
- 21-50
- 51-100
- 101-1000
- 1001+
nullable: true
city_region_country:
allOf:
- $ref: '#/components/schemas/IncludesFilter_Text_'
title: City Region Country
description: 'Filter accounts by geographic region, down to city-level granularity. Example: [San Francisco, CA, US].'
example:
values:
- Paris, FR
- Tel Aviv,
# --- truncated at 32 KB (140 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/explorium/refs/heads/main/openapi/explorium-businesses-api-openapi.yml