Skip to main content
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_code filter applies to the company’s headquarters location, while the country_code filter 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

  1. Input: Provide filters such as job level, department, or industry to refine prospect search.
  2. Processing: The system scans and retrieves relevant prospect records.
  3. Output: A structured response containing matched prospect data.

​
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: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:
  • value: for a single filter value (e.g. "value": "true")
  • values: for multiple possible matches (e.g. "values": ["director", "manager"])
Example Request Body:
Filter Matching Logic:
  • Fields using value are matched exactly.
  • 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.

​
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.

​
Prospect Filters Reference

​
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"]
cURL
Mode full : Returns additional attributes such as job history, social links, and experience.
cURL
  • 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=true to expand and include semantically related roles.

​
Body Params - Try Me Example

Authorizations

​
api_key
string
header
required

Body

application/json
​
mode
enum<string>
required

The mode of fetching prospects.

Available options:
full,
preview
Example:

"full"

​
page_size
integer
required

The maximum number of prospects in a page. Max limit is 500

Required range: 1 <= x <= 500
Example:

3

​
request_context
Request Context · object | null
Example:

null

​
size
integer

The maximum number of prospects to return. Max size is 60000 (which is the default value)

Required range: 1 <= x <= 60000
Example:

3

​
page
integer | null

The page number to fetch.

Required range: x >= 1
Example:

1

​
exclude
string[] | null

List of prospect ids to exclude from the response.

Maximum array length: 1000
Pattern: ^[a-f0-9]{40}$
Example:

null

​
filters
Filters · object | null
​
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

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

​
response_context
ResponseContext · object
required
​
total_pages
integer
required

The total number of pages.

Required range: x >= 0
​
data
Prospect · object[]

List of prospects that match the filters.

​
total_results
integer

The total number of Prospects that match the filters.

Required range: x >= 0
​
page
integer

The page number of the response.

Required range: x >= 0