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

excludeListId string

ID of a people exclusion list belonging to your organization. People whose LinkedIn handle is in the list are excluded from results.

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""Senior""Professional""Entry""Intern"

Filter by skills

Matches when the LinkedIn profile skills include all of these keywords

Array of string

Matches when the LinkedIn profile skills include at least one of these keywords

Array of string

Matches when the LinkedIn profile skills include none 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

When set, enables full text exact matching per mode instead of substring matching.

anyOf boolean

When true, anyOf terms match the full job title exactly rather than as a substring.

allOf boolean

When true, allOf terms match the full job title exactly rather than as a substring.

noneOf boolean

When true, noneOf terms match the full job title exactly rather than as a substring.

Filter by all job descriptions

Matches when the job descriptions include all of these

Array of string

Matches when the job descriptions include at least one of these

Array of string

Matches when the job descriptions include none of these

Array of string

Filter by current job description

Matches when the current job description includes all of these

Array of string

Matches when the current job description includes at least one of these

Array of string

Matches when the current job description includes none of these

Array of string

Filter by profile description

Matches when the LinkedIn profile description includes all of these keywords

Array of string

Matches when the LinkedIn profile description includes at least one of these keywords

Array of string

Matches when the LinkedIn profile description includes none 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, with `mode` choosing whether a person has to match one of them or all of them. Note: To avoid breaking changes, passing a bare array of departments still works and is treated as `mode: anyOf`, which is what it always meant.

Array of the departments to include. Available values are located at /v2/data-fields endpoint.

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""Education"

mode enum

[default] anyOf - match at least one of the departments allOf - match all of the departments

"anyOf""allOf"

Exclude people by departments. Available values are located at /v2/data-fields endpoint.

Array of Department

enum

Filter by sub-departments, one level below departments, with `mode` choosing whether a person has to match one of them or all of them. With both levels set to `anyOf`, a department and a sub-department under a different department returns people in either.

Array of the sub-departments to include, one level below departments. Available values are located at /v2/data-fields endpoint.

Array of SubDepartment

enum

"Accounting and audit""Banking and credit""Financial advisory and investment""Corporate finance & control""Accounting and Finance - unspecified""Board membership""Board - unspecified""Administrative support""Business Support - unspecified""Customer service & support""Call centre & contact centre""Customer success""Customer Relations - unspecified""Graphic and visual design""Art direction and creative direction""Photography and video production""Specialist and applied design""UX & product design""Design - unspecified""Content, writing & editorial""Editorial Personnel - unspecified""Software development""Data, analytics & machine learning""QA & software testing""Mechanical & manufacturing engineering""Civil, structural & quantity surveying""Electrical & automation engineering""IT infrastructure, cloud & DevOps""Architecture & solutions design""Field & laboratory technical services""General engineering""Security engineering""Network & infrastructure""Technical support & helpdesk""Systems analysis & data management""IT management & strategy""Information security""Information technology - unspecified""Engineering - unspecified""Business ownership & entrepreneurship""Founder/Owner - unspecified""Nursing""Physicians & surgeons""Pharmacy, therapy & allied health""Direct care & patient support""Healthcare administration & coordination""Healthcare - unspecified""Recruiting & talent acquisition""HR business partnering & operations""Learning & development""Health, safety & environment""HR - unspecified""Attorney & legal practice""Legal support & administration""Contracts & procurement""Compliance & regulatory affairs""Legal - unspecified""Consulting & advisory""Operational unit management""Executive leadership""Management - unspecified""Production operations""Maintenance & repair""Skilled trades & craft production""Manufacturing - unspecified""Brand, digital & growth marketing""Social media & community""Marketing and Advertising - unspecified""Project & programme management""General operations management""Business analysis & process improvement""Aviation & flight operations""Food & beverage production""Hospitality & front-of-house""Facilities, maintenance & cleaning""Construction & field operations""Operations - unspecified""Communications, PR & events""PR and Communications - unspecified""Procurement and purchasing""Procurement - unspecified""Product management""Product ownership""Product operations & support""Product strategy & innovation""Product - unspecified""Quality control & assurance""Quality Control - unspecified""Research & science""R&D - unspecified""Retail & store sales""Account management""Business development""Real estate""Field & territory sales""Inside sales & telemarketing""Commercial & B2B sales""Relationship & client management""Sales engineering & technical sales""Merchandising & brand promotion""General & direct sales""Sales - unspecified""Security & protective services""Security - unspecified""Warehouse & logistics""Driving & transportation""Supply Chain - unspecified""Student or trainee""Not currently employed""General or unspecialised worker""Other - unspecified""K-12 teaching""Higher education faculty""Classroom & learning support""Training & instructional design""Student guidance & support services""School leadership & administration""Education - unspecified"

mode enum

[default] anyOf - match at least one of the sub-departments allOf - match all of the sub-departments. A person usually carries one sub-department per department, so allOf across two rarely matches anyone.

"anyOf""allOf"

Exclude people by sub-departments. Available values are located at /v2/data-fields endpoint.

Array of SubDepartment

enum

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 the specified fields are absent

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

laborStatusOpenToWork boolean

Filter by open-to-work status. True to include only, false to exclude.

laborStatusHiring boolean

Filter by hiring status. True to include only, false to exclude.

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

excludeListId string

ID of a companies exclusion list belonging to your organization. Domains from the list are excluded from results.

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 false -> excludes e-commerce companies 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

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.

Array of the industries to include

Array of string

mode enum

[default] anyOf - match at least one of the industries 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.

Array of the industry categories to include

Array of string

mode enum

[default] anyOf - match at least one of the industry categories 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.

Array of string

Array of Linkedin industries to exclude. Available values are located at /v2/data-fields endpoint.

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. Accepts alpha-2 ISO 3166 country codes.

Array of string

Exclude companies that are present in the specified countries. Accepts 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. Accepts alpha-2 ISO 3166 country codes.

Array of string

Exclude companies that are present in the specified countries. Accepts 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

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 false -> filter on the absolute value of the headcount growth

Filter by headcount growth values. Valid range: -10,000,000 to 10,000,000. If `as_percentage=false`, values are in integer form (e.g., `5`, `-5`). 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 false -> filter on the absolute value of the headcount growth

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, so a VP/leadership hiring signal spans the functional departments under `anyOf` rather than sitting in 'Management'.

enum

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 false -> filter on the absolute value of the headcount growth

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"

enum

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 the specified fields are absent

Array of enum

enum

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"

Filter by open job postings. Requires the Advanced filtering add-on; requests using these filters without it are rejected.

Number of open job postings the company has.

from integer

Greater than or equal to

to integer

Less than or equal to

Departments the company has at least one open job posting in.

The filter should match **any** of the specified values.

Array of Department

enum

The filter should match **all** of the specified values.

Array of Department

enum

The filter should match **none** of the specified values.

Array of Department

enum

Sub-departments (one level below departments) the company has at least one open job posting in.

The filter should match **any** of the specified values.

Array of SubDepartment

enum

The filter should match **all** of the specified values.

Array of SubDepartment

enum

The filter should match **none** of the specified values.

Array of SubDepartment

enum

Seniorities the company has at least one open job posting at.

The filter should match **any** of the specified values.

Array of Seniority

enum

"Owner""Founder""Board Member""C-Level""Partner""VP""Head""Director""Manager""Other""Senior""Professional""Entry""Intern"

The filter should match **all** of the specified values.

Array of Seniority

enum

"Owner""Founder""Board Member""C-Level""Partner""VP""Head""Director""Manager""Other""Senior""Professional""Entry""Intern"

The filter should match **none** of the specified values.

Array of Seniority

enum

"Owner""Founder""Board Member""C-Level""Partner""VP""Head""Director""Manager""Other""Senior""Professional""Entry""Intern"

Countries, as alpha-2 ISO 3166 codes, the company has at least one open job posting in.

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

States or regions the company has at least one open job posting in.

The filter should match **any** of the specified values.

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.

The filter should match **all** of the specified values.

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.

The filter should match **none** of the specified values.

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 buying signals, using the keys company results return in `buyingSignals`. Teams and leaders: `has_product` (Has product), `has_hr` (Has HR), `has_legal` (Has legal), `has_software_engineering` (Has software engineering), `has_qa` (Has QA), `has_product_design` (Has product design), `has_ux` (Has UX), `has_ae_am` (Has AEs/AMs), `has_sdr_bdr` (Has SDRs/BDRs), `has_product_management` (Has product management), `has_community_roles` (Has community roles), `has_engineering_leader` (Has engineering leader), `has_marketing_leader` (Has marketing leader), `has_sales_leader` (Has sales leader), `has_product_leader` (Has product leader), `has_data_leader` (Has data leader). Hiring a leader: `hiring_engineering_leader` (Hiring engineering leader), `hiring_marketing_leader` (Hiring marketing leader), `hiring_sales_leader` (Hiring sales leader), `hiring_product_leader` (Hiring product leader), `hiring_finance_leader` (Hiring finance leader), `hiring_hr_leader` (Hiring HR leader), `hiring_design_leader` (Hiring design leader), `hiring_cs_leader` (Hiring customer success leader). Hiring pace: `recruiting_velocity:low` (Low), `recruiting_velocity:medium` (Moderate), `recruiting_velocity:high` (High), `recruiting_velocity:very_high` (Very high). `small_website` for a company with a small website. Seniority by department: `dept:<department>:<seniority>`, such as `dept:sales:vp` for a company with a VP in sales. Department is one of `engineering`, `marketing_and_advertising`, `product`, `sales`, and seniority one of `owner`, `founder`, `board_member`, `c_level`, `partner`, `vp`, `head`, `director`, `manager`, `other`, `senior`, `professional`, `entry`, `intern`. Requires the Advanced filtering add-on; requests using this filter without it are rejected.

The company has **at least one** of these signals.

Array of string

The company has **all** of these signals.

Array of string

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`, `laborStatusOpenToWork`, `laborStatusHiring`, `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 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""You are not allowed to access this feature"

404 Not found

422 Validation Error

Array of ValidationError

Array of string | integer

string | integer

msg string Required

type string Required

input any

object

429 Too Many Requests

detail string Required

API token

Session only — cleared when you close the tab.

Request

cURL

Python

JavaScript

JSON

curl -X POST 'https://api.ocean.io/v3/search/people/preview' \
  -H 'x-api-token: <YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "size": 50,
    "peopleFilters": {
      "lookalikeLinkedinHandles": [
        "michael-scott-13532",
        "dwight-schrute"
      ],
      "countries": [
        "us",
        "dk"
      ],
      "includePeopleIds": [
        "43g19df9c1d70f9a",
        "54hb1b1bfb1ffc5t"
      ],
      "includeLinkedinHandles": [
        "jim-halpert-5343",
        "toby-67832"
      ],
      "excludePeopleIds": [
        "43g19df9c1d70f9a",
        "54hb1b1bfb1ffc5t"
      ],
      "excludeLinkedinHandles": [
        "jim-halpert-5343",
        "toby-67832"
      ],
      "excludeListId": "string",
      "seniorities": [
        "Founder",
        "Owner"
      ],
      "skills": {
        "allOf": [
          "Product Management",
          "Entrepreneurship"
        ],
        "anyOf": [
          "Social Media",
          "Competitive Analysis"
        ],
        "noneOf": [
          "Writing",
          "Project Management"
        ]
      },
      "jobTitleKeywords": {
        "allOf": [
          "Manager"
        ],
        "anyOf": [
          "Marketing",
          "designer"
        ],
        "noneOf": [
          "content"
        ],
        "exactMatch": {
          "anyOf": false,
          "allOf": false,
          "noneOf": false
        }
      },
      "allJobDescriptions": {
        "allOf": [
          "software engineer"
        ],
        "anyOf": [
          "software engineer"
        ],
        "noneOf": [
          "entry-level"
        ]
      },
      "currentJobDescription": {
        "allOf": [
          "software engineer",
          "big tech company"
        ],
        "anyOf": [
          "software engineer"
        ],
        "noneOf": [
          "entry-level"
        ]
      },
      "profileDescription": {
        "allOf": [
          "software engineer"
        ],
        "anyOf": [
          "software engineer"
        ],
        "noneOf": [
          "entry-level"
        ]
      },
      "regions": [
        "CA",
        "TX"
      ],
      "states": [
        {
          "abbreviation": "NY",
          "country": "us"
        },
        {
          "abbreviation": "ENG",
          "country": "gb"
        },
        {
          "abbreviation": "5",
          "country": "at"
        },
        {
          "abbreviation": "SH",
          "country": "de"
        }
      ],
      "excludeStates": [
        {
          "abbreviation": "NY",
          "country": "us"
        },
        {
          "abbreviation": "ENG",
          "country": "gb"
        },
        {
          "abbreviation": "5",
          "country": "at"
        },
        {
          "abbreviation": "SH",
          "country": "de"
        }
      ],
      "excludeCountries": [
        "us",
        "dk"
      ],
      "cities": [
        {
          "city": "New York",
          "country": "us"
        },
        {
          "city": "Los Angeles",
          "country": "us"
        }
      ],
      "excludeCities": [
        {
          "city": "New York",
          "country": "us"
        },
        {
          "city": "Los Angeles",
          "country": "us"
        }
      ],
      "names": [
        "John Doe",
        "Peter Pan"
      ],
      "departments": {
        "departments": [
          "Management",
          "Marketing and Advertising"
        ],
        "mode": "anyOf"
      },
      "excludeDepartments": [
        "Management",
        "Marketing and Advertising"
      ],
      "subDepartments": {
        "mode": "anyOf",
        "subDepartments": [
          "Software development"
        ]
      },
      "excludeSubDepartments": [
        "Technical support & helpdesk"
      ],
      "fieldsExist": [
        "name",
        "country",
        "linkedinUrl"
      ],
      "fieldsNotExist": [
        "firstName",
        "location",
        "jobTitleEnglish"
      ],
      "changedPositionAfter": "2023-01",
      "changedPositionBefore": "2023-01",
      "updatedWithinMonths": 1,
      "connections": {
        "from": 100,
        "to": 400
      },
      "followers": {
        "from": 100,
        "to": 5000
      },
      "laborStatusOpenToWork": true,
      "laborStatusHiring": true
    },
    "companiesFilters": {
      "lookalikeDomains": [
        "bestcustomer.com",
        "idealcustomer.com"
      ],
      "includeDomains": [
        "interesting.com",
        "amazing.com"
      ],
      "excludeDomains": [
        "boring.com",
        "useless.com"
      ],
      "excludeListId": "string",
      "companySizes": [
        "2-10",
        "51-200",
        "100001-500000"
      ],
      "ecommerce": true,
      "yearFounded": {
        "from": 1960,
        "to": 1990
      },
      "countriesCount": {
        "from": 1,
        "to": 5
      },
      "revenues": [
        "0-1M",
        "1-10M",
        ">1000M"
      ],
      "employeeCountOcean": {
        "from": 10,
        "to": 100
      },
      "mobileApps": {
        "from": 1,
        "to": 5
      },
      "mobileAppsFilter": {
        "count": {
          "from": 1,
          "to": 5
        }
      },
      "locationsCount": {
        "from": 5,
        "to": 10
      },
      "departmentSizes": [
        {
          "department": "Accounting and Finance",
          "from": 5,
          "to": 10
        }
      ],
      "employeeCountLinkedin": {
        "from": 50,
        "to": 100
      },
      "industries": {
        "industries": [
          "Advertising Platforms",
          "Biopharma"
        ],
        "mode": "anyOf"
      },
      "excludeIndustries": [
        "CRM",
        "B2B"
      ],
      "industryCategories": {
        "industryCategories": [
          "Real Estate",
          "Hardware"
        ],
        "mode": "anyOf"
      },
      "excludeIndustryCategories": [
        "Information Technology",
        "Privacy and Security"
      ],
      "linkedinIndustries": [
        "Management Consulting",
        "Computer Software"
      ],
      "excludeLinkedinIndustries": [
        "Management Consulting",
        "Computer Software"
      ],
      "fundingRound": {
        "date": {
          "from": "2020-01-01",
          "to": "2023-01-01"
        },
        "raised": {
          "from": 1000000,
          "to": 5000000
        },
        "types": [
          "Seed",
          "Series A"
        ]
      },
      "primaryLocations": {
        "includeCountries": [
          "es"
        ],
        "excludeCountries": [
          "br",
          "de"
        ],
        "includeRegions": [
          {
            "abbreviation": "CA",
            "country": "us"
          },
          {
            "abbreviation": "YT",
            "country": "ca"
          }
        ],
        "excludeRegions": [
          {
            "abbreviation": "CA",
            "country": "us"
          },
          {
            "abbreviation": "YT",
            "country": "ca"
          }
        ],
        "includeCities": [
          {
            "city": "New York",
            "country": "us"
          },
          {
            "city": "Los Angeles",
            "country": "us"
          }
        ],
        "excludeCities": [
          {
            "city": "New York",
            "country": "us"
          },
          {
            "city": "Los Angeles",
            "country": "us"
          }
        ],
        "geolocation": {
          "latitude": 38.880817,
          "longitude": -77.10216,
          "radius": 1000
        }
      },
      "otherLocations": {
        "includeCountries": [
          "es"
        ],
        "excludeCountries": [
          "br",
          "de"
        ],
        "includeRegions": [
          {
            "abbreviation": "CA",
            "country": "us"
          },
          {
            "abbreviation": "YT",
            "country": "ca"
          }
        ],
        "excludeRegions": [
          {
            "abbreviation": "CA",
            "country": "us"
          },
          {
            "abbreviation": "YT",
            "country": "ca"
          }
        ],
        "includeCities": [
          {
            "city": "New York",
            "country": "us"
          },
          {
            "city": "Los Angeles",
            "country": "us"
          }
        ],
        "excludeCities": [
          {
            "city": "New York",
            "country": "us"
          },
          {
            "city": "Los Angeles",
            "country": "us"
          }
        ],
        "geolocation": {
          "latitude": 38.880817,
          "longitude": -77.10216,
          "radius": 1000
        }
      },
      "webTraffic": {
        "views": {
          "from": 1000,
          "to": 1000000
        },
        "visits": {
          "from": 1000,
          "to": 10000
        }
      },
      "socialMedias": {
        "medias": {
          "all_of": [
            "facebook",
            "x"
          ],
          "any_of": [
            "youtube",
            "xing"
          ],
          "none_of": [
            "instagram",
            "tiktok"
          ]
        },
        "min_count": 3
      },
      "technologies": {
        "apps": {
          "all_of": [
            "Amazon Advertising",
            "Google Maps"
          ],
          "any_of": [
            "BrightEdge",
            "Nette Framework"
          ],
          "none_of": [
            "Kount",
            "Nativo"
          ]
        },
        "categories": {
          "all_of": [
            "Analytics",
            "Security"
          ],
          "any_of": [
            "Advertising",
            "WordPress themes"
          ],
          "none_of": [
            "CMS",
            "Reviews"
          ]
        }
      },
      "keywords": {
        "all_of": [
          "lead generation",
          "marketing"
        ],
        "any_of": [
          "smart prospecting",
          "data platform"
        ],
        "none_of": [
          "seo"
        ]
      },
      "minRelevance": "B",
      "maxRelevance": "B",
      "headcountGrowth": {
        "asPercentage": false,
        "growthRange": {
          "from": -1,
          "to": 3
        },
        "months": "Three months"
      },
      "departmentHeadcountGrowth": {
        "anyOf": [
          {
            "asPercentage": false,
            "department": "Accounting and Finance",
            "growthRange": {
              "from": -1,
              "to": 3
            },
            "months": "Three months"
          }
        ]
      },
      "updatedWithinMonths": 1,
      "fieldsExist": [
        "industries",
        "emails",
        "locations"
      ],
      "fieldsNotExist": [
        "industryCategories",
        "phones"
      ],
      "companyMatchingMode": "precise",
      "jobPostings": {
        "count": {
          "from": 10
        },
        "departments": {
          "anyOf": [
            "Engineering",
            "Sales"
          ]
        },
        "subDepartments": {
          "anyOf": [
            "Software development"
          ]
        },
        "seniorities": {
          "anyOf": [
            "Director",
            "VP"
          ]
        },
        "countries": {
          "anyOf": [
            "de",
            "dk"
          ]
        },
        "states": {
          "anyOf": [
            {
              "abbreviation": "CA",
              "country": "us"
            }
          ]
        }
      },
      "buyingSignals": {
        "anyOf": [
          "has_sdr_bdr",
          "dept:sales:vp"
        ]
      }
    },
    "peoplePerCompany": 3,
    "jobTitleThreshold": 0.8,
    "searchAfter": "N4IglgdgJgpgHiAXAVgL5A",
    "fields": [
      "id",
      "domain",
      "name",
      "firstName",
      "lastName",
      "country",
      "state",
      "location",
      "linkedinUrl",
      "seniorities",
      "departments",
      "photo",
      "jobTitle",
      "jobTitleEnglish",
      "currentJobDescription",
      "experiences",
      "summary",
      "skills",
      "headline",
      "updatedAt",
      "connectionsCount",
      "followersCount",
      "laborStatusOpenToWork",
      "laborStatusHiring",
      "company.revenue",
      "company.peopleCount",
      "company.industries",
      "company.technologies",
      "company.latestFundingRound"
    ]
  }'

Response

200

400

402

403

422

429

{
  "detail": "OK",
  "total": 75,
  "redirectMap": {
    "given_local_domain.uk": "original.com",
    "ikea.nl": "ikea.com"
  },
  "creditsUsed": 1,
  "people": [
    {
      "ranking": 1,
      "person": {
        "name": "John ***",
        "jobTitle": "CEO"
      },
      "company": {
        "name": "Google",
        "logo": "https://cdn2.ocean.io/logos/ocean.io/b162ddc061a4ca67e8aacbbf747dc8e62cce7496.png",
        "topIndustries": [
          "Analytics",
          "B2B",
          "Software"
        ],
        "size": "501-1000",
        "description": "B2B Sales and Marketing teams use Ocean.io's prospecting data platform to find accounts and contacts no one else can.",
        "primaryCountry": "us",
        "primaryRegion": "CA",
        "linkedinHandle": "zoominfo"
      }
    }
  ]
}