post /v3/search/people/preview

Preview - Lookalike people

Preview search people with company information. Only available for enterprise API customers.
Endpoint POST /v3/search/people/preview
Credit cost Not available on this plan
Response Synchronous
Availability Enterprise plans only

Quickstart#

Not available on v3

Preview endpoints are not available on the v3 Unified plan. They are available on v2 (Per Search) and v1 (Legacy) plans.

curl -X POST "https://api.ocean.io/v3/search/people/preview" \
  -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"]
    }
  }'
import requests

response = requests.post(
    'https://api.ocean.io/v3/search/people/preview',
    headers={'X-Api-Token': 'YOUR_API_TOKEN'},
    json={
        'peopleFilters': {
            'seniorities': ['VP', 'C-Level'],
            'departments': ['Sales'],
        },
        'companiesFilters': {
            'primaryLocations': {'includeCountries': ['us']},
            'companySizes': ['201-500', '501-1000'],
        },
    },
)
data = response.json()
const response = await fetch('https://api.ocean.io/v3/search/people/preview', {
  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'],
    },
  }),
});
const data = await response.json();

Example response:

{ "total": 12340 }

Authorizations

apiToken string
x-api-token string

Body application/json

size integer
Number of people to return
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
detail string Required
Status text
total integer
Total number of the available results.
Mapping of original domains passed in filters to their redirected domains.
object
creditsUsed number Required
Number of credits charged for this request.
Array of found people. Returns empty array if no results
Array of PublicPersonWithCompanyPreview
ranking integer Required
Position ranking in the search results (1-based)
Person information
name string
Full name of the person
jobTitle string
Job title of the person
Company information
name string Required
Name of the company
logo string Required
URL to the company logo
Array of top 3 industries
Array of string
size string Required
Company size in brackets
description string Required
Company description
primaryCountry string Required
Primary country code of the company
primaryRegion string Required
Primary region code of the company
linkedinHandle string
LinkedIn company handle/username
400 Bad Request
detail enum Required
"Conflicting API tokens provided in query parameters and headers"
402 Payment Required
detail enum Required
"Insufficient email credits""Some email verifications are already in progress and might use all your remaining email credits. Please try again later.""Insufficient phone credits""Some phone verifications are already in progress and might use all your remaining phone credits. Please try again later.""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