Explorium Prospects API
Match, fetch, stat, autocomplete, and event/enrollment operations over the Explorium prospect dataset (v1).
OpenAPI Specification
openapi: 3.2.0
info:
title: Partner Service Prospects API
version: 0.3.19
servers:
- url: https://api.explorium.ai
description: AgentSource Server
tags:
- name: Prospects
paths:
/v1/prospects/match:
post:
tags:
- Prospects
summary: Match Prospects
description: 'Match a list of prospects attributes to ids.
Returns a list of the same length and order as the input list, with the matched ids.'
operationId: match_prospects
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProspectsMatchRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ProspectsMatchResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- APIKeyHeader: []
/v1/prospects:
post:
tags:
- Prospects
summary: Fetch Prospects
operationId: fetch_prospects
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProspectsFetchRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/ProspectsFetchResponse'
- $ref: '#/components/schemas/ProspectsFetchResponseV2'
title: Response Fetch Prospects
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- APIKeyHeader: []
/v1/prospects/stats:
post:
tags:
- Prospects
summary: Prospect Fetch Stats
description: Fetch stats for businesses.
operationId: prospect_fetch_stats
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProspectsStatsRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ProspectsStatsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- APIKeyHeader: []
/v1/prospects/events:
post:
tags:
- Prospects
summary: Fetch Prospects Events
description: Create events and fetch for prospects.
operationId: fetch_prospects_events
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProspectsEventsRequest'
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/prospects/autocomplete:
get:
tags:
- Prospects
summary: Autocomplete Prospects
description: Autocomplete prospects fields values by field name.
operationId: prospects_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 Prospects Autocomplete
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- APIKeyHeader: []
/v1/prospects/events/enrollments:
get:
tags:
- Prospects
summary: Get Prospects Enrollments
description: Show prospects events enrollments records for user.
operationId: get_prospects_enrollments
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ProspectsEnrollmentsGetResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- APIKeyHeader: []
post:
tags:
- Prospects
summary: Add Prospects Enrollments
description: Add enrollments for prospects
operationId: add_prospects_enrollments
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProspectsEnrollmentsAddRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ProspectsEnrollmentsAddResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- APIKeyHeader: []
delete:
tags:
- Prospects
summary: Delete Prospects Enrollments
description: Delete events enrollments records
operationId: delete_prospects_enrollments
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProspectsEnrollmentsDeleteRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ProspectsEnrollmentsDeleteResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- APIKeyHeader: []
patch:
tags:
- Prospects
summary: Update Prospects Enrollments
description: Update enrollments for prospects
operationId: update_prospects_enrollments
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProspectsEnrollmentsUpdateRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ProspectsEnrollmentsUpdateResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- APIKeyHeader: []
components:
schemas:
RangeFilter_Int_:
properties:
negate:
type: boolean
title: Negate
gte:
type: integer
title: Gte
lte:
type: integer
title: Lte
additionalProperties: false
type: object
title: RangeFilter[Int]
ContactDetailsFilter:
properties:
value:
$ref: '#/components/schemas/ContactDetailsFilterValue'
negate:
type: boolean
title: Negate
additionalProperties: false
type: object
required:
- value
title: ContactDetailsFilter
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."
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
JobSeniorityLevel:
type: string
enum:
- owner
- c-suite
- vice president
- director
- senior non-managerial
- manager
- partner
- non-managerial
- junior
- president
- senior manager
- advisor
- freelancer
- board member
- founder
- training
- unpaid
title: JobSeniorityLevel
description: 'The `JobSeniorityLevel` class is an enumeration that represents various levels of job seniority.
This enum is used to categorize jobs based on their seniority levels, such as:
- Entry-level positions
- Managerial roles
- Executive roles (e.g., C-Suite, VP)
These categories ensure consistent filtering and classification of job-related data across the application.'
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."
ProspectsEnrollmentsUpdateRequest:
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/ProspectsEventIdentifier'
type: array
minItems: 1
enrollment_id:
type: string
title: Enrollment Id
prospect_ids:
items:
type: string
pattern: ^[a-f0-9]{40}$
type: array
maxItems: 20
minItems: 1
title: Prospect Ids
additionalProperties: false
type: object
required:
- enrollment_key
- event_types
- enrollment_id
- prospect_ids
title: ProspectsEnrollmentsUpdateRequest
ProspectMatchOutput:
properties:
input:
$ref: '#/components/schemas/ProspectMatchInput'
prospect_id:
type: string
pattern: ^[a-f0-9]{40}$
title: Prospect Id
type: object
required:
- input
title: ProspectMatchOutput
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
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]
ExistsFilter:
properties:
negate:
type: boolean
title: Negate
value:
type: boolean
title: Value
additionalProperties: false
type: object
required:
- value
title: ExistsFilter
ContactDetailsFilterValue:
type: string
enum:
- email
- phone
- email_or_phone
- email_and_phone
title: ContactDetailsFilterValue
description: An enumeration.
JobTitleFilter:
properties:
negate:
type: boolean
title: Negate
values:
items:
type: string
type: array
maxItems: 300
title: Job Titles
description: List of job titles to filter by. Maximum 300 items allowed.
example:
- Software Engineer
- Data Scientist
operator:
type: string
enum:
- or
- and
title: Operator
default: or
include_related_job_titles:
type: boolean
title: Include Related Job Titles
description: When set to true, includes related job titles in the search.
example: false
nullable: true
additionalProperties: false
type: object
required:
- values
title: JobTitleFilter
ProspectsEnrollmentsDeleteResponse:
properties:
response_context:
$ref: '#/components/schemas/ResponseContext'
status:
allOf:
- $ref: '#/components/schemas/RequestStatus'
default: success
type: object
required:
- response_context
title: ProspectsEnrollmentsDeleteResponse
description: This is base response model for all responses in partner service.
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]
ProspectsFetchResponse:
properties:
response_context:
$ref: '#/components/schemas/ResponseContext'
data:
items:
$ref: '#/components/schemas/Prospect'
type: array
title: Data
description: List of prospects that match the filters.
default: []
total_results:
type: integer
minimum: 0.0
title: Total Results
description: The total number of Prospects 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: ProspectsFetchResponse
description: This is base response model for all responses in partner service.
ProspectsFetchResponseV2:
properties:
response_context:
$ref: '#/components/schemas/ResponseContext'
data:
items:
$ref: '#/components/schemas/Prospect'
type: array
title: Data
description: List of prospects that match the filters.
default: []
total_results:
type: integer
minimum: 0.0
title: Total Results
description: The total number of prospects that match the filters.
default: 0
page:
allOf:
- $ref: '#/components/schemas/partner_service__models__prospects__requests__PageInfo'
title: Page
description: Page information including size and next cursor
type: object
required:
- response_context
- page
title: ProspectsFetchResponseV2
description: This is base response model for all responses in partner service.
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.'
ProspectsMatchRequest:
properties:
request_context:
type: object
title: Request Context
marked_for_null_replacement: true
nullable: true
prospects_to_match:
items:
$ref: '#/components/schemas/ProspectMatchInput'
type: array
maxItems: 50
minItems: 1
title: Prospects To Match
additionalProperties: false
type: object
required:
- prospects_to_match
title: ProspectsMatchRequest
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.
ProspectMatchInput:
properties:
business_id:
type: string
title: Business Id
description: Explorium business id
marked_for_null_replacement: true
nullable: true
full_name:
type: string
title: Full Name
description: Full name of the person
marked_for_null_replacement: true
nullable: true
company_name:
type: string
title: Company Name
description: Company name
marked_for_null_replacement: true
nullable: true
email:
type: string
title: Email
description: Email address
marked_for_null_replacement: true
nullable: true
phone_number:
type: string
title: Phone Number
description: Phone number
marked_for_null_replacement: true
nullable: true
linkedin:
type: string
title: Linkedin
description: LinkedIn URL
marked_for_null_replacement: true
nullable: true
type: object
title: ProspectMatchInput
ProspectsStatsRequest:
properties:
request_context:
type: object
title: Request Context
marked_for_null_replacement: true
nullable: true
filters:
$ref: '#/components/schemas/ProspectsFetchFilters'
additionalProperties: false
type: object
required:
- filters
title: ProspectsStatsRequest
JobDepartment:
type: string
enum:
- administration
- real estate
- healthcare
- partnerships
- c-suite
- design
- human resources
- engineering
- education
- strategy
- product
- sales
- r&d
- retail
- customer success
- security
- public service
- creative
- it
- support
- marketing
- trade
- legal
- operations
- procurement
- data
- manufacturing
- logistics
- finance
title: JobDepartment
description: 'The `JobDepartment` class is an enumeration that represents various job departments.
This enum is used to categorize jobs based on their associated departments, such as:
- Engineering
- Marketing
- Sales
- Legal
- Customer Service
These categories ensure consistent filtering and classification of job-related data across the application.'
ProspectsEnrollmentsUpdateResponse:
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: ProspectsEnrollmentsUpdateResponse
description: This is base response model for all responses in partner service.
IncludesFilter_ProspectId_:
properties:
negate:
type: boolean
title: Negate
values:
items:
type: string
pattern: ^[a-f0-9]{40}$
type: array
title: Values
additionalProperties: false
type: object
required:
- values
title: IncludesFilter[ProspectId]
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]
ProspectsEnrollmentsAddResponse:
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: ProspectsEnrollmentsAddResponse
description: This is base response model for all responses in partner service.
partner_service__models__prospects__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
ProspectsEventsRequest:
properties:
request_context:
type: object
title: Request Context
marked_for_null_replacement: true
nullable: true
entity_type:
allOf:
- $ref: '#/components/schemas/EntityType'
default: prospect
event_types:
items:
$ref: '#/components/schemas/ProspectsEventIdentifier'
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
prospect_ids:
items:
type: string
pattern: ^[a-f0-9]{40}$
type: array
maxItems: 40
minItems: 1
uniqueItems: true
title: Prospect Ids
additionalProperties: false
type: object
required:
- event_types
- prospect_ids
title: ProspectsEventsRequest
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.
ResponseContext:
properties:
correlation_id:
type: string
title: Correlation Id
request_status:
$ref: '#/components/schemas/RequestStatus'
time_took_in_seconds:
type: number
title: Time Took In Seconds
type: object
required:
- correlation_id
- request_status
- time_took_in_seconds
title: ResponseContext
AnyMatchFilter_OrganizationName_:
properties:
negate:
type: boolean
title: Negate
values:
items:
type: string
maxLength: 256
type: array
title: Values
additionalProperties: false
type: object
required:
- values
title: AnyMatchFilter[OrganizationName]
ProspectsEnrollmentsDeleteRequest:
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: ProspectsEnrollmentsDeleteRequest
ProspectsStats:
properties:
job_departments_per_location:
type: object
title: Job Departments Per Location
total_per_location:
type: object
title: Total Per Location
type: object
title: ProspectsStats
ProspectsEnrollmentsAddRequest:
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/ProspectsEventIdentifier'
type: array
minItems: 1
prospect_ids:
items:
type: string
pattern: ^[a-f0-9]{40}$
type: array
maxItems: 20
minItems: 1
title: Prospect Ids
additionalProperties: false
type: object
required:
- enrollment_key
- event_types
- prospect_ids
title: ProspectsEnrollmentsAddRequest
ProspectsEventIdentifier:
type: string
enum:
- prospect_changed_role
- prospect_changed_company
- prospect_job_start_anniversary
title: ProspectsEventIdentifier
description: 'The `ProspectsEventIdentifier` class is an enumeration that defines event identifiers related to prospects.
This enum is used to categorize and track events associated with prospects, such as:
- Role changes (e.g., when a prospect changes their role within a company)
- Company changes (e.g., when a prospect moves to a new company)
- Job anniversaries (e.g., celebrating the anniversary of a prospect''s job start date)
These identifiers ensure consistent handling and classification of prospect-related events across the application.'
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.'
ProspectsStatsResponse:
properties:
response_context:
$ref: '#/components/schemas/ResponseContext'
total_results:
type: integer
title: Total Results
stats:
$ref: '#/components/schemas/ProspectsStats'
type: object
required:
- response_context
- total_results
- stats
title: ProspectsStatsResponse
description: This is base response model for all responses in partner service.
ProspectsEnrollment:
properties:
enrollment_id:
type: string
title: Enrollment Id
enrollment_key:
type: string
minLength: 4
title: Enrollment Key
event_types:
items:
anyOf:
- $ref: '#/components/schemas/EventName'
- $ref: '#/components/schemas/InternalEventIdentifier'
type: array
title: Event Types
prospect_ids:
items:
type: string
pattern: ^[a-f0-9]{40}$
type: array
title: Prospect Ids
type: object
required:
- enrollment_id
- enrollment_key
- event_types
- prospect_ids
title: ProspectsEnrollment
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]
ProspectsFetchFilters:
properties:
prospect_id:
# --- truncated at 32 KB (145 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/explorium/refs/heads/main/openapi/explorium-prospects-api-openapi.yml