post /v3/search/people

Lookalike people search

Search people using filters and/or people Ids

Looking for the legacy endpoint? Access it here

Webhook result: Email results Phone results
Endpoint POST /v3/search/people
Credit cost 0.2 credits / result
Response Synchronous — up to 10,000 results per request
When to use Build a filtered list of contacts matching your target persona

Example use case: Find VP-level Sales leaders at US SaaS companies with 200–1000 employees who changed jobs in the last 90 days.

Quickstart#

curl -X POST "https://api.ocean.io/v3/search/people" \
  -H "X-Api-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "peopleFilters": {
      "seniorities": ["VP", "C-Level"],
      "departments": ["Sales"]
    },
    "companiesFilters": {
      "primaryLocations": { "includeCountries": ["us"] },
      "companySizes": ["201-500", "501-1000"],
      "industries": { "industries": ["SaaS"] }
    },
    "size": 10
  }'
import requests

response = requests.post(
    'https://api.ocean.io/v3/search/people',
    headers={'X-Api-Token': 'YOUR_API_TOKEN'},
    json={
        'peopleFilters': {
            'seniorities': ['VP', 'C-Level'],
            'departments': ['Sales'],
        },
        'companiesFilters': {
            'primaryLocations': {'includeCountries': ['us']},
            'companySizes': ['201-500', '501-1000'],
            'industries': {'industries': ['SaaS']},
        },
        'size': 10,
    },
)
data = response.json()
const response = await fetch('https://api.ocean.io/v3/search/people', {
  method: 'POST',
  headers: { 'X-Api-Token': 'YOUR_API_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    peopleFilters: {
      seniorities: ['VP', 'C-Level'],
      departments: ['Sales'],
    },
    companiesFilters: {
      primaryLocations: { includeCountries: ['us'] },
      companySizes: ['201-500', '501-1000'],
      industries: { industries: ['SaaS'] },
    },
    size: 10,
  }),
});
const data = await response.json();

Example response:

{
  "people": [
    {
      "id": "abc123",
      "name": "Jane Doe",
      "jobTitle": "VP of Sales",
      "seniorities": ["VP"],
      "departments": ["Sales"],
      "domain": "example.com",
      "country": "us",
      "linkedinUrl": "https://linkedin.com/in/jane-doe-123"
    }
  ],
  "searchAfter": ["abc123"],
  "total": 3210
}

Store the id field from each result — you'll need it to reveal emails or enrich the person.

Use searchAfter to paginate. See Pagination for details.

Authorizations

apiToken string
x-api-token string

Body application/json

size integer
Number of people to return. The maximum value is 10,000.
Collection of filters to be applied to the search
List of people linkedin handles to search for similar people.
Array of string
List of country codes (alpha-2 ISO 3166) to search for people.
Array of string
List of people IDs to include in the search.
Array of string
List of people linkedin handles to include in the search.
Array of string
List of people IDs to exclude from the search.
Array of string
List of people linkedin handles to exclude from the search.
Array of string
Filter by seniorities. Available values are located at /v2/data-fields endpoint.
Array of Seniority
enum
"Owner""Founder""Board Member""C-Level""Partner""VP""Head""Director""Manager""Other"
Filter by skills
The LinkedIn profile skills must include all of these keywords
Array of string
The LinkedIn profile skills must include at least one of these keywords
Array of string
The LinkedIn profile skills must not include any of these keywords
Array of string
Filter by keywords present in job titles
Match all of the keywords
Array of string
Match at least one of the keywords
Array of string
Match none of the keywords
Array of string
Filter by all job descriptions
Job descriptions must include all of these
Array of string
Job descriptions must include at least one of these
Array of string
Job descriptions must not include any of these
Array of string
Filter by current job description
The current job description must include all of these
Array of string
The current job description must include at least one of these
Array of string
The current job description must not include any of these
Array of string
Filter by profile description
The LinkedIn profile description must include all of these keywords
Array of string
The LinkedIn profile description must include at least one of these keywords
Array of string
The LinkedIn profile description must not include any of these keywords
Array of string
List of region codes to search for people.
Array of string
List of states/regions to search for people (ISO-3166-2 region codes). Available abbreviation values are located at /v2/data-fields endpoint (region section).
Array of State
country string Required
Alpha-2 ISO 3166 country code
abbreviation string Required
Valid state abbreviation. List available in the region section there: /v2/data-fields.
List of states/regions to exclude when searching for people (ISO-3166-2 region codes). Available abbreviation values are located at /v2/data-fields endpoint (region section).
Array of State
country string Required
Alpha-2 ISO 3166 country code
abbreviation string Required
Valid state abbreviation. List available in the region section there: /v2/data-fields.
List of country codes (alpha-2 ISO 3166) to exclude when searching for people.
Array of string
List of cities to search for people.
Array of PeopleCityFilter
city string Required
City name
country string
Alpha-2 ISO 3166 country code
Filter by country region (if applicable)
country string Required
Alpha-2 ISO 3166 country code
abbreviation string Required
Valid state abbreviation. List available in the region section there: /v2/data-fields.
List of cities to exclude when searching for people.
Array of PeopleCityFilter
city string Required
City name
country string
Alpha-2 ISO 3166 country code
Filter by country region (if applicable)
country string Required
Alpha-2 ISO 3166 country code
abbreviation string Required
Valid state abbreviation. List available in the region section there: /v2/data-fields.
Filter by names
Array of string
Filter by departments. Available values are located at /v2/data-fields endpoint.<br>
Array of Department
enum
"Accounting and Finance""Board""Business Support""Customer Relations""Design""Editorial Personnel""Engineering""Founder/Owner""Healthcare""HR""Legal""Management""Manufacturing""Marketing and Advertising""Operations""PR and Communications""Procurement""Product""Quality Control""R&D""Sales""Security""Supply Chain""Other"
Exclude people by departments. Available values are located at /v2/data-fields endpoint.<br>
Array of Department
enum
"Accounting and Finance""Board""Business Support""Customer Relations""Design""Editorial Personnel""Engineering""Founder/Owner""Healthcare""HR""Legal""Management""Manufacturing""Marketing and Advertising""Operations""PR and Communications""Procurement""Product""Quality Control""R&D""Sales""Security""Supply Chain""Other"
Return records where specified fields exist
Array of enum
enum
"country""departments""firstName""jobTitle""jobTitleEnglish""lastName""linkedinUrl""location""name""photo""seniorities""summary"
Return records where specified fields do not exist
Array of enum
enum
"country""departments""firstName""jobTitle""jobTitleEnglish""lastName""linkedinUrl""location""name""photo""seniorities""summary"
changedPositionAfter string
Return people who started a new job between the specified date (inclusive) and now
changedPositionBefore string
Return people who started a new currently active job before the specified date (inclusive)
updatedWithinMonths integer
Filter people updated within the last N months.
Number of connections of the person on Linkedin
from integer
Greater than or equal to
to integer
Less than or equal to
Number of followers of the person on Linkedin
from integer
Greater than or equal to
to integer
Less than or equal to
Collection of companies filters, the search results will display people that are associated with those companies
Find domains similar to the provided
Array of string
Only return specified domains
Array of string
Exclude specified domains from the results
Array of string
Filter by company size ranges
Array of PublicCompanySize
enum
"0-1""2-10""11-50""51-200""201-500""501-1000""1001-5000""5001-10000""10001-50000""50001-100000""100001-500000""500000+"
ecommerce boolean
true -> returns only e-commerce companies<br>false -> excludes e-commerce companies<br>none -> returns everything
Filter by year founded. Valid range: 0-2100
from integer
Greater than or equal to
to integer
Less than or equal to
Filter by the number of countries in which the company operates. Valid range: 0-300
from integer
Greater than or equal to
to integer
Less than or equal to
Filter by revenue ranges
Array of Revenue
enum
"0-1M""1-10M""10-50M""50-100M""100-500M""500-1000M"">1000M"
Only return companies that have a certain number of employee profiles in our database. Valid range: 0-10,000,000
from integer
Greater than or equal to
to integer
Less than or equal to
Filter by the number of mobile apps that the company produced. Valid range: 0-10,000
from integer
Greater than or equal to
to integer
Less than or equal to
Filter by mobile app attributes (count, downloads, release year)
Filter by the number of mobile apps that the company produced. Valid range: 0-10,000
from integer
Greater than or equal to
to integer
Less than or equal to
Filter by the number of mobile app downloads. Valid range: 0-10,000,000,000
from integer
Greater than or equal to
to integer
Less than or equal to
Filter by the release year of mobile apps. Valid range: 2000-2100
from integer
Greater than or equal to
to integer
Less than or equal to
Only return companies that have a certain amount of locations. Valid range: 0-100,000
from integer
Greater than or equal to
to integer
Less than or equal to
Filter by the size of company departments. Valid range: 0-10,000,000
Array of DepartmentSizeFilter
from integer
Greater than or equal to
to integer
Less than or equal to
enum
"Accounting and Finance""Board""Business Support""Customer Relations""Design""Editorial Personnel""Engineering""Founder/Owner""Healthcare""HR""Legal""Management""Manufacturing""Marketing and Advertising""Operations""PR and Communications""Procurement""Product""Quality Control""R&D""Sales""Security""Supply Chain""Other"
The number of employees a company has on LinkedIn. Valid range: 0-10,000,000
from integer
Greater than or equal to
to integer
Less than or equal to
Filter by company industries. Available values are located at /v2/data-fields endpoint.<br>
Array of the industries to include
Array of string
mode enum
[default] anyOf - match at least one of the industries<br>allOf - match all of the industries
"anyOf""allOf"
Array of the industries to exclude
Array of string
Filter by company industry categories. Available values are located at /v2/data-fields endpoint.<br>
Array of the industry categories to include
Array of string
mode enum
[default] anyOf - match at least one of the industry categories<br>allOf - match all of the industry categories
"anyOf""allOf"
Array of the industry categories to exclude
Array of string
Filter by Linkedin industries. This is OR filter. Available values are located at /v2/data-fields endpoint.<br>
Array of string
Array of Linkedin industries to exclude. Available values are located at /v2/data-fields endpoint.<br>
Array of string
Filter by funding rounds
Amount of money raised in funding round. Valid range: 0-100,000,000,000
from integer
Greater than or equal to
to integer
Less than or equal to
List of funding round types
Array of FundingRoundType
enum
"Seed""Series A""Angel""Series B""Series Unknown""Pre-Seed""Grant""Series C""Convertible Note""Debt Financing""Non-Equity Assistance""Undisclosed""Series D""Corporate Round""Equity Crowdfunding""Product Crowdfunding""Series E""Private Equity""Secondary Market""Initial Coin Offering""Post-IPO Equity""Series F""Post-IPO Debt""Series H""Series G""Post-IPO Secondary""Series I""Series J"
Date range of the funding round. Valid range: 1800-01-01 to 2100-12-31
from string
Date in YYYY-MM-DD format
to string
Date in YYYY-MM-DD format
Filter by primary locations (HQ)
Filter by all countries where the company has presence.<br>Must be provided as alpha-2 ISO 3166 country codes.
Array of string
Exclude companies that are present in the specified countries.<br>Must be provided as alpha-2 ISO 3166 country codes.
Array of string
Filter by country regions — US states, Canadian provinces, etc. (if applicable). Available values are located at /v2/data-fields endpoint.
Array of State
country string Required
Alpha-2 ISO 3166 country code
abbreviation string Required
Valid state abbreviation. List available in the region section there: /v2/data-fields.
Exclude companies present in the specified regions — US states, Canadian provinces, etc. (if applicable). Available values are located at /v2/data-fields endpoint.
Array of State
country string Required
Alpha-2 ISO 3166 country code
abbreviation string Required
Valid state abbreviation. List available in the region section there: /v2/data-fields.
Filter by cities
Array of CompaniesCityFilter
city string Required
City name
country string
Alpha-2 ISO 3166 country code
Filter by country region (if applicable)
country string Required
Alpha-2 ISO 3166 country code
abbreviation string Required
Valid state abbreviation. List available in the region section there: /v2/data-fields.
postalCode string
Filter by postal code
Exclude companies that are present in the specified cities
Array of CompaniesCityFilter
city string Required
City name
country string
Alpha-2 ISO 3166 country code
Filter by country region (if applicable)
country string Required
Alpha-2 ISO 3166 country code
abbreviation string Required
Valid state abbreviation. List available in the region section there: /v2/data-fields.
postalCode string
Filter by postal code
Filter by latitude and longitude
latitude number Required
Latitude of the location
longitude number Required
Longitude of the location
radius integer Required
Radius in meters
Filter by locations of offices other than the headquarters
Filter by all countries where the company has presence.<br>Must be provided as alpha-2 ISO 3166 country codes.
Array of string
Exclude companies that are present in the specified countries.<br>Must be provided as alpha-2 ISO 3166 country codes.
Array of string
Filter by country regions — US states, Canadian provinces, etc. (if applicable). Available values are located at /v2/data-fields endpoint.
Array of State
country string Required
Alpha-2 ISO 3166 country code
abbreviation string Required
Valid state abbreviation. List available in the region section there: /v2/data-fields.
Exclude companies present in the specified regions — US states, Canadian provinces, etc. (if applicable). Available values are located at /v2/data-fields endpoint.
Array of State
country string Required
Alpha-2 ISO 3166 country code
abbreviation string Required
Valid state abbreviation. List available in the region section there: /v2/data-fields.
Filter by cities
Array of CompaniesCityFilter
city string Required
City name
country string
Alpha-2 ISO 3166 country code
Filter by country region (if applicable)
country string Required
Alpha-2 ISO 3166 country code
abbreviation string Required
Valid state abbreviation. List available in the region section there: /v2/data-fields.
postalCode string
Filter by postal code
Exclude companies that are present in the specified cities
Array of CompaniesCityFilter
city string Required
City name
country string
Alpha-2 ISO 3166 country code
Filter by country region (if applicable)
country string Required
Alpha-2 ISO 3166 country code
abbreviation string Required
Valid state abbreviation. List available in the region section there: /v2/data-fields.
postalCode string
Filter by postal code
Filter by latitude and longitude
latitude number Required
Latitude of the location
longitude number Required
Longitude of the location
radius integer Required
Radius in meters
Filter by web traffic metrics
Only return companies that have a certain amount of visits. Valid range: 0-100,000,000,000
from integer
Greater than or equal to
to integer
Less than or equal to
Only return companies that have a certain amount of page views. Valid range: 0-100,000,000,000
from integer
Greater than or equal to
to integer
Less than or equal to
Filter by social media presence
Filter by social media presence
The filter should match **any** of the specified values.
Array of enum
enum
"linkedin""x""facebook""instagram""youtube""xing""tiktok"
The filter should match **all** of the specified values.
Array of enum
enum
"linkedin""x""facebook""instagram""youtube""xing""tiktok"
The filter should match **none** of the specified values.
Array of enum
enum
"linkedin""x""facebook""instagram""youtube""xing""tiktok"
minCount integer
Return companies that are present in more than `n` social networks
Filter by the software technologies present on the company's website
Filter by software technologies used by the company. Available values are located at /v2/data-fields endpoint.
The filter should match **any** of the specified values.
Array of string
The filter should match **all** of the specified values.
Array of string
The filter should match **none** of the specified values.
Array of string
Filter by software technology categories used by the company. Available values are located at /v2/data-fields endpoint.
The filter should match **any** of the specified values.
Array of string
The filter should match **all** of the specified values.
Array of string
The filter should match **none** of the specified values.
Array of string
Filter by keywords
The filter should match **any** of the specified values.
Array of string
The filter should match **all** of the specified values.
Array of string
The filter should match **none** of the specified values.
Array of string
minRelevance enum
Filter by min relevance (A - the most relevant).
"A""B""C"
maxRelevance enum
Filter by max relevance (A - the most relevant). Use combination of min_relevance: "B" and max_relevance: "B" to get only results with the "B" relevance
"A""B""C"
Filter by headcount growth
asPercentage boolean Required
true -> filter on the percentage value of the headcount growth<br>false -> filter on the absolute value of the headcount growth<br>
Filter by headcount growth values. Valid range: -10,000,000 to 10,000,000.<br>If `as_percentage=false`, values are in integer form (e.g., `5`, `-5`).<br>If `as_percentage=true`, values are in decimal form (e.g., `0.5` = 50%).
from number
Greater than or equal to
to number
Less than or equal to
Headcount growth period in months
enum
"Three months""Six months""Twelve months"
Filter by department headcount growth
The result should match **any** of the department headcount growth filters.
Array of DepartmentGrowthFilter
asPercentage boolean Required
true -> filter on the percentage value of the headcount growth<br>false -> filter on the absolute value of the headcount growth<br>
Filter by headcount growth values. Valid range: -10,000,000 to 10,000,000.<br>If `as_percentage=false`, values are in integer form (e.g., `5`, `-5`).<br>If `as_percentage=true`, values are in decimal form (e.g., `0.5` = 50%).
from number
Greater than or equal to
to number
Less than or equal to
Headcount growth period in months
enum
"Three months""Six months""Twelve months"
Functional department for the headcount growth filter. Departments are assigned by job function, not seniority — a VP of Sales appears under 'Sales', a CTO under 'Engineering', a CMO under 'Marketing and Advertising', a CFO under 'Accounting and Finance', a CHRO under 'HR', a CLO/General Counsel under 'Legal'. 'Management' captures CEO, COO, and general-manager roles only. For VP/leadership hiring signals across functions, use anyOf with the relevant functional departments rather than 'Management' alone.
enum
"Accounting and Finance""Board""Business Support""Customer Relations""Design""Editorial Personnel""Engineering""Founder/Owner""Healthcare""HR""Legal""Management""Manufacturing""Marketing and Advertising""Operations""PR and Communications""Procurement""Product""Quality Control""R&D""Sales""Security""Supply Chain""Other"
The result should match **all** of the he department headcount growth filters.
Array of DepartmentGrowthFilter
asPercentage boolean Required
true -> filter on the percentage value of the headcount growth<br>false -> filter on the absolute value of the headcount growth<br>
Filter by headcount growth values. Valid range: -10,000,000 to 10,000,000.<br>If `as_percentage=false`, values are in integer form (e.g., `5`, `-5`).<br>If `as_percentage=true`, values are in decimal form (e.g., `0.5` = 50%).
from number
Greater than or equal to
to number
Less than or equal to
Headcount growth period in months
enum
"Three months""Six months""Twelve months"
Functional department for the headcount growth filter. Departments are assigned by job function, not seniority — a VP of Sales appears under 'Sales', a CTO under 'Engineering', a CMO under 'Marketing and Advertising', a CFO under 'Accounting and Finance', a CHRO under 'HR', a CLO/General Counsel under 'Legal'. 'Management' captures CEO, COO, and general-manager roles only. For VP/leadership hiring signals across functions, use anyOf with the relevant functional departments rather than 'Management' alone.
enum
"Accounting and Finance""Board""Business Support""Customer Relations""Design""Editorial Personnel""Engineering""Founder/Owner""Healthcare""HR""Legal""Management""Manufacturing""Marketing and Advertising""Operations""PR and Communications""Procurement""Product""Quality Control""R&D""Sales""Security""Supply Chain""Other"
updatedWithinMonths integer
Filter companies updated within the last N months.
Return records where specified fields exist
Array of enum
enum
"companySize""countries""departmentSizes""description""emails""faxes""impressum""industries""industryCategories""keywords""legalName""linkedinIndustry""locations""logo""medias""mobileApps""name""phones""primaryCountry""revenue""rootUrl""technologies""technologyCategories""webTraffic""yearFounded"
Return records where specified fields do not exist
Array of enum
enum
"companySize""countries""departmentSizes""description""emails""faxes""impressum""industries""industryCategories""keywords""legalName""linkedinIndustry""locations""logo""medias""mobileApps""name""phones""primaryCountry""revenue""rootUrl""technologies""technologyCategories""webTraffic""yearFounded"
companyMatchingMode enum
Controls how strictly companies are matched when using lookalike_domains. "precise" (default): Matches companies with similar products/services using semantic similarity. "broad": Matches companies within the same industries, casting a wider net for results.
"precise""broad"
peoplePerCompany integer
Number of people to return per company. If you want to return all people from a company, don't set this value.
jobTitleThreshold number
Threshold for job title similarity. The value must be between 0 and 1. Default is 0.8
searchAfter string
Use `searchAfter` returned by the previous request to get the next page.
Fields to return in the Person objects. Only requesting the fields that are needed will use less bandwidth and result in faster responses. If not specified, the following default fields are returned: `id`, `domain`, `name`, `firstName`, `lastName`, `country`, `state`, `location`, `linkedinUrl`, `seniorities`, `departments`, `photo`, `jobTitle`, `jobTitleEnglish`, `currentJobDescription`, `experiences`, `summary`, `skills`, `headline`, `updatedAt`, `connectionsCount`, `followersCount`, `company.revenue`, `company.peopleCount`, `company.industries`, `company.technologies`, `company.latestFundingRound`.
Array of PersonField | PersonCompanyField
PersonField | PersonCompanyField

Responses

200 Successful Response
Array of LookalikePerson
id string Required
Internal ocean id of the person
domain string Required
Domain of the company the person is working for
name string
Full name of the person
firstName string
First name of the person
lastName string
Last name of the person
country string
Country code of the person
state string
State code of the person
location string
Location of the person
linkedinUrl string
Link to the linkedin profile of the person
List of seniorities computed from the job title of the person
Array of Seniority
enum
"Owner""Founder""Board Member""C-Level""Partner""VP""Head""Director""Manager""Other"
List of departments computed from the job title of the person
Array of Department
enum
"Accounting and Finance""Board""Business Support""Customer Relations""Design""Editorial Personnel""Engineering""Founder/Owner""Healthcare""HR""Legal""Management""Manufacturing""Marketing and Advertising""Operations""PR and Communications""Procurement""Product""Quality Control""R&D""Sales""Security""Supply Chain""Other"
photo string
Link to the person's profile picture on LinkedIn
jobTitle string
Job title of the person
jobTitleEnglish string
English translation of the person's job title
currentJobDescription string
Current job description of the person
List of experiences of the person
Array of Experience
domain string
Domain of the company the person is working for
jobTitle string
Job title of the person
dateFrom string
Start date of the experience
dateTo string
End date of the experience
description string
Description of the experience
linkedinCompanyHandle string
Linkedin handle of the company the person is working for
summary string
Summary of the person
Skills of the person
Array of string
Phone numbers of the person
Phone numbers
Array of string
status enum Required
Status of the phone numbers: verified or not found
"verified""notFound""inProgress"
Email of the person
address string Required
Email address
status enum Required
Status of the address: verified, catchAll or guessed
"verified""guessed""catchAll""notFound"
List of inferred email addresses for the person. This is only available for enterprise subscriptions.
Array of string
updatedAt string
When has the person data been updated for the last time
connectionsCount integer
Number of LinkedIn connections of the person
followersCount integer
Number of LinkedIn followers of the person
headline string
Headline of the person
Company size range
enum
"0-1""2-10""11-50""51-200""201-500""501-1000""1001-5000""5001-10000""10001-50000""50001-100000""100001-500000""500000+"
logo string
Logo of the company (URL)
name string
Name of the company
Revenue range
enum
"0-1M""1-10M""10-50M""50-100M""100-500M""500-1000M"">1000M"
employeeCountOcean integer
Number of people working at the company in our database.
Industries of the company<br>Available values can be found at /v2/data-fields endpoint.
Array of string
Software technologies used by the company
Array of string
Funding round of the company
date string
Date of the funding round
Type of the funding round
enum
"Seed""Series A""Angel""Series B""Series Unknown""Pre-Seed""Grant""Series C""Convertible Note""Debt Financing""Non-Equity Assistance""Undisclosed""Series D""Corporate Round""Equity Crowdfunding""Product Crowdfunding""Series E""Private Equity""Secondary Market""Initial Coin Offering""Post-IPO Equity""Series F""Post-IPO Debt""Series H""Series G""Post-IPO Secondary""Series I""Series J"
moneyRaisedInUsd integer
Amount of money raised in USD
cbUrl string
URL of the funding round on Crunchbase
relevance enum
Relevance category (A - the most relevant)
"A""B""C"
detail string Required
Status text
Statuses of the lookalike people
People that are found in the database
Array of string
People that are not found in the database
Array of string
People linked to a company that was not crawled
Array of string
People linked to a company that is missing necessary data
Array of string
total integer
Total number of results of the search, accessible with pagination.
searchAfter string
Used for pagination. Use `searchAfter` returned by this request in the next request to get the next page of search results.
Mapping of original domains passed in filters to their redirected domains.
object
creditsUsed number Required
Number of credits charged for this request.
Domains from `includeDomains` filter that were not found in the search results, along with the reason
object
400 Bad Request
detail enum Required
"Conflicting API tokens provided in query parameters and headers"
402 Payment Required
detail enum Required
"Insufficient credits"
403 Forbidden
detail enum Required
"API token should be provided in headers or query parameters""Current API token is not registered in our database"
404 Not found
422 Validation Error
Array of ValidationError
Array of string | integer
string | integer
msg string Required
type string Required
input any
object

FAQs#

How do I get email addresses for the people I find?

Collect the id values from search results and pass them to Reveal Emails. Email reveal is async and draws from the same credit pool.

Can I search for people at a specific company?

Yes — use companiesFilters.includeDomains to target specific company domains (e.g., { "includeDomains": ["stripe.com", "twilio.com"] }).

What is peoplePerCompany?

Setting "peoplePerCompany": 1 returns at most one person per company domain. Useful when building a prospecting list and you don't want multiple contacts from the same company unless you request them explicitly.

How do I find people who recently changed jobs?

Use peopleFilters.changedPositionAfter with a year-month string. For example, "changedPositionAfter": "2025-02" returns only people who started a new role from February 2025 onwards — a strong buying signal.