Fetch Prospects
Prospects
Fetch prospects
POST
Fetch Prospects
Introduction
The Fetch Prospects endpoint allows users to retrieve a list of prospect records based on filtering criteria such as job level, department, or other professional attributes. This API is essential for sales intelligence, lead enrichment, and prospecting workflows. Key Benefits:- Identify high-value prospects based on job roles, seniority, and industry.
- Enhance lead scoring and segmentation with structured data.
- Retrieve up-to-date professional details to optimize outreach.
- Integrate seamlessly with existing CRM and marketing automation platforms.
- Consideration:
- Not all filters have a high coverage rate. Using a filter with low data coverage may result in a smaller set of returned results.
- Conversely, using broader filters can yield more results. For example, if filtering by a very specific attribute results in few matches, expanding the filter criteria may increase the number of retrieved records.
- When filtering by location, note that there are two distinct filter types: company location and prospect location. For example, the
company_country_codefilter applies to the company’s headquarters location, while thecountry_codefilter applies to the individual prospect’s location. This distinction is particularly important for global companies where prospects may be distributed across different locations than the company headquarters.RetryClaude can make mistakes. Please double-check responses.)
Endpoint:POST /prospects
How It Works
How It Works
- Input: Provide filters such as job level, department, or industry to refine prospect search.
- Processing: The system scans and retrieves relevant prospect records.
- Output: A structured response containing matched prospect data.
Request Schema
Request Schema
| Field | Type | Description |
|---|---|---|
mode | String | full |
size | Number | Max number of returned results - up to 60000 |
page_size | Number | Max number of records per page - up to 100 |
page | Number | Page number to retrieve |
filters | Object | Filter object (see Filters Object below) |
Pagination, Filtering & Modes Parameters
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. |
- If
sizeis smaller thanpage_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:value: for a single filter value (e.g."value": "true")values: for multiple possible matches (e.g."values": ["director", "manager"])
- Fields using
valueare matched exactly. - Fields using
valuesare matched using an OR condition. - Filters are combined using an AND across different fields.
Mode Parameter
The optionalmode 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_sizeto control payload size for better performance. - Use
sizeto set an upper limit and avoid unintentionally requesting large datasets. - Apply filters whenever possible to reduce response size and processing time.
Prospect Filters
Prospect Filters
Prospect Filters Reference
| Parameter | Description | Notes / Best Practices |
|---|---|---|
| has_email | Filter prospects by whether they have an email. Categories: [True, False] | Enter true to find only prospects with email addresses, or false to exclude them. Uses a single value (true/false). Logic is based on checking the existence of a value in the email field. |
| has_phone_number | Filter prospects by whether they have a phone number. Categories: [True, False] | Use true to get only prospects with phone numbers. Useful when planning outreach via phone. Uses a single value. Logic checks whether the phone field is populated. |
| job_title | Filter prospects by their job titles. Example: [Sales Representative, SEO specialist, Technical Support Engineer] | Enter one or more job titles as free text. The filter matches prospects whose title includes all the words. For more consistent results, prefer using job_level and job_department. Uses a single value with flexible keyword matching. Logic ensures all words appear in the target field, regardless of order. |
| include_related_job_titles (Used inside job_title filter) | Expand filtering results to include related job titles. | When set to true, the system broadens the search to include job titles that are semantically or hierarchically related to the provided title(s). Default is false. Useful for retrieving a wider range of relevant roles. |
| job_level | Filter prospects by their job level. Examples Categories: manager, president, senior manager, owner, advisor, freelancer, junior, director, c-suite, board member, senior non-managerial, non-managerial, partner, vice president, founder. | Use autocomplete to search and select job levels. You can choose one or more values. The response fields (job_level_array, job_level_main) provide enriched context. Examples of new levels: manager, president, senior manager, owner, advisor, freelancer, junior, director, c-suite, board member, senior non-managerial, non-managerial, partner, vice president, founder. |
| job_department | Filter prospects by their job department. Examples Categories: retail, engineering, customer success, administration, education, security, healthcare, public service, partnerships, creative, strategy, real estate, procurement, IT, data, c-suite, manufacturing, support, logistics, product, sales, design, marketing, finance, R&D, trade, human resources, legal, operations. | Use autocomplete to browse and select departments. Works best when combined with job_level to ensure title coverage across organizations. The response fields (job_department_array, job_department_main) provide enriched context. Examples of new departments: retail, engineering, customer success, administration, education, security, healthcare, public service, partnerships, creative, strategy, real estate, procurement, IT, data, c-suite, manufacturing, support, logistics, product, sales, design, marketing, finance, R&D, trade, human resources, legal, operations. |
| business_id | Filter prospects by account. Use Explorium entity IDs. Example: [EXP_ENTITY_ID_1, EXP_ENTITY_ID_2][EXP_ENTITY_ID_1, EXP_ENTITY_ID_2] | Paste one or more valid business IDs. These are specific identifiers in the system. |
| country_code | Filter prospects by country using alpha-2 codes. Example: [us, ca] | Use the country autocomplete to search by country name and select the correct two-letter code. This avoids manual errors and ensures valid input. Uses a list of values. Logic checks whether the country code matches. |
| region_country_code | Filter prospects by region using ISO 3166-2 codes. Example: [us-ut, us-ca] | First choose a country in the autocomplete, then select a region. The code will be formatted as country-region (e.g., us-ca). Uses values. Logic checks for region code inclusion. |
| city_region_country | Filter by city, region, and country of the company location. Example: [“New York, NY, US”] | Use cascading autocomplete to select a country, then region and city. The full location string is used for precise geographic targeting. Accepts multiple values. Logic checks structured address fields. |
| company_size | Filter by company’s number of employees. Options: [1-10, 11-50, …, 10001+] | Use autocomplete to select the company size range you’re interested in. Helpful for distinguishing between small businesses and large enterprises. Accepts multiple values. Internally maps to normalized size brackets. |
| company_revenue | Filter by company’s annual revenue. Options: [0-500K, 500K-1M, …, 10B-100B] | Use autocomplete to choose from available revenue brackets. Each value represents a range, making segmentation simple and accurate. Accepts values. The logic compares the company revenue field against the selected bracket range. |
| google_category | Filter by company’s Google business category. Example: [Paving contractor, Retail] | Use autocomplete to find and apply relevant business categories based on Google’s classifications. Accepts values. The logic checks category labels against company classification metadata. |
| naics_category | Filter by NAICS code (2, 4, or full). Example: [23, 5611] | Use autocomplete to find relevant industry codes. Recommended for accurate industry classification. Uses multiple values. Logic compares NAICS codes to industry metadata. |
| linkedin_category | Filter by company’s LinkedIn business category. Example: [software development, investment banking] | Use autocomplete to choose from LinkedIn’s available business categories to align with industry filters. Accepts values. Filters based on company category tags provided by LinkedIn. |
| company_country_code | Filter by company HQ country using alpha-2 codes. Example: [us, ca] | Use the country autocomplete to select the appropriate country code. This ensures accurate targeting based on company location. Accepts values. Matches against the company’s registered country code. |
| company_region_country_code | Filter by company HQ region using ISO 3166-2 codes. Example: [us-ut, us-ca] | Start by choosing the company’s country, then use autocomplete to select the relevant region. This automatically formats the code correctly. Accepts multiple values. Matches structured region codes from company metadata. |
| total_experience_months | Filter by total months of experience. | You can specify minimum (gte) and/or maximum (lte) months of experience. For example, use gte: 60 to filter for 5+ years. This uses a numeric value range. Logic compares experience duration against thresholds. |
| current_role_months | Filter by number of months in current role. | Use gte or lte to define how long the prospect has held their current position. Great for identifying newly promoted prospects or those with long tenure. Accepts a numeric range of value. Logic checks against current role start date. |
| company_name | Filter by company name. Example: [“Meta”, “Tesla”] | Enter one or more full company names. Useful for targeting specific known organizations. Accepts a list of values. Matching is typically exact or fuzzy depending on the configuration. |
Prospecting HR Directors at Healthcare Companies in Texas for Payroll Software
Use Case:
A payroll software provider wants to sell to HR directors at mid-sized healthcare organizations in Texas who handle payroll compliance and workforce management.Filters:
- Company Country Code:
["us"] - Company Region (State Code):
["us-tx"] - Company Size:
["501-1000"] - Company Revenue:
["75M-200M"] - NAICS Category:
["62"](Healthcare & Social Assistance) - Job Level:
["director", "manager", "vp"] - Job Department:
["human resources"] - Has Email:
["True"]
Targeting CFOs of Investment Banks in New York for Financial Compliance Software
A regulatory compliance software provider wants to reach out to CFOs at mid-sized investment banks in New York who have been in their role for over two years and are likely leading compliance initiatives.Filters:
- Company Country Code:
["us"] - Company Region (State Code):
["us-ny"] - Company Size:
["1001-5000"] - Company Revenue:
["500M-1B"] - LinkedIn Category:
["investment banking"] - Job Department:
["finance"] - Job Level:
["CXO"] - Has Email:
["True"] - Has Phone Number:
["True"]
Example Request (cURL)
Example Request (cURL)
cURL
Mode full : Returns additional attributes such as job history, social links, and experience.cURL
Best Practices
Best Practices
- Use refined filters to retrieve the most relevant prospects.
- Batch requests efficiently to optimize API performance.
- Monitor pagination settings to avoid missing data.
- Ensure data freshness by running regular queries to keep prospect information up-to-date.
- Be mindful of filter coverage – some filters may return fewer results due to lower data availability, while broader filters may yield larger result sets.
- If you are not certain about the exact job title, it’s recommended to set
include_related_job_titles=trueto expand and include semantically related roles.
Body Params - Try Me Example
Authorizations
Headers
Body
application/json
The mode of fetching prospects.
Available options:
full, preview Example:
"full"
The number of prospects to fetch.
Required range:
1 <= x <= 60000Example:
3
The maximum number of prospects to fetch.
Required range:
1 <= x <= 500Example:
3
Example:
null
The page number to fetch.
Required range:
x >= 1Example:
1
List of prospect ids to exclude from the response.
Maximum array length:
1000Example:
null
Example:
{}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
- ProspectsFetchResponse
- ProspectsFetchResponseV2
This is base response model for all responses in partner service.
The total number of pages.
Required range:
x >= 0List of prospects that match the filters.
The total number of Prospects that match the filters.
Required range:
x >= 0The page number of the response.
Required range:
x >= 0