post /v2/search/people

Search people (deprecated)

Search people using filters and/or people Ids

Authorizations

apiToken string

x-api-token string

Body application/json

size integer

Number of people to return. The maximum value is 10,000. To get more than 10,000 results, use `searchAfter`.

from integer

Return people from number X. Passing 1 will return all the results. Passing 10 will return results from the 10th. Note: `size + from` cannot be higher than 10,001

searchAfter string

Use `searchAfter` returned by the previous request to get the next page. Note: this cannot be used together with `onePersonPerDomain` enabled.

Collection of filters to be applied to the search

Only return specified people. Note: this is not implemented yet.

Array of string

Exclude specified people from the results. Note: this is not implemented yet.

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 job title

Array of string

Exclude people by job title

Array of string

Filter by departments. 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"

Filter by countries (alpha-2 ISO 3166 country codes)

Array of string

List of states/regions (ISO-3166-2 region codes) to search for people

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 (ISO-3166-2 region codes) to exclude when searching for people

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 countries (alpha-2 ISO 3166 country codes) to exclude when searching for people

Array of string

Filter by names

Array of string

Filter by email address

Array of string

Filter people based on keywords from their summary

Array of string

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)

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 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 **all** countries where the company has presence. Must be provided as alpha-2 ISO 3166 country codes. `["es", "pt"]` means Spain (primary/not primary) **OR** Portugal (primary/not primary). if additional filter `primaryCountries = ["de"]` is used then it means: (Spain (not primary) **OR** Portugal (not primary)) **AND** Germany (primary)

Array of string

Filter only by **primary** countries where the company has presence. Must be provided as alpha-2 ISO 3166 country codes. `countries = ["de", "at"]` means Germany (primary) **OR** Austria (primary). if additional filter `countries = ["es"]` is used then it means: (Germany (primary) **OR** Austria (primary)) **AND** Spain (not primary)

Array of string

Filter by country states (if applicable)

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 only by **primary** states where the company has presence. Behavior is the same as for primary countries

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

Filter only by **primary** cities where the company has presence. Behavior is the same as for primary countries

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 headquarter location

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

latitude number Required

Latitude of the location

longitude number Required

Longitude of the location

radius integer Required

Radius in meters

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

Filter by keywords

Array of the keywords

Array of string

mode enum

[default] anyOf - match at least one of the keywords allOf - match all of the keywords noneOf - match none of the keywords

"anyOf""allOf""noneOf"

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

Filter by social media presence

Array of the social medias to include

Array of enum

enum

"linkedin""x""facebook""instagram""youtube""xing""tiktok"

mode enum

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

"anyOf""allOf"

Filter by software technologies used by the company. Available values are located at /v2/data-fields endpoint.

Array of the technologies to include

Array of string

mode enum

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

"anyOf""allOf"

minScore number

Minimum score for companies to appear in the results.

includeEmails boolean

Include the emails for all the results. One email credit will be charged for each verified email.

webhookUrl string

Only relevant if `includeEmails` is True. Webhook url to get the reveal email results, if any email has to be processed in the background.

includePhones boolean

Include the phones for all the results. One phone credit will be charged for each verified phone.

webhookUrl string

Only relevant if `includePhones` is True. Webhook url to get the reveal phone results, if any phone has to be processed in the background.

onePersonPerDomain boolean

Only return one person per company

peoplePerCompany integer

Number of people to return per company. If you want to return all people from a company, don't set this value.

Responses

200 Successful Response

Array of PublicPerson

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

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

searchAfter string

Used for pagination. Use `searchAfter` returned by this request in the next request to get the next page of search results. If `searchAfter` is not present in the response then there is no next page.

detail string Required

Status text

total integer

Total number of results of the search, accessible with pagination.

Mapping of original domains passed in filters to their redirected domains.

object

creditsUsed number Required

Number of credits charged for this request.

400 Bad Request

detail enum Required

"Conflicting API tokens provided in query parameters and headers""Plan version not supported for this endpoint"

402 Payment Required

detail enum Required

"Insufficient standard 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

API token

Session only — cleared when you close the tab.

Request

cURL

Python

JavaScript

JSON

curl -X POST 'https://api.ocean.io/v2/search/people' \
  -H 'x-api-token: <YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "size": 10,
    "from": 10,
    "searchAfter": "NoBgdA7BAsBMEgGwBoAEAiADgGwK4HN8BTAJwC8wBjAewFt0BdIA",
    "peopleFilters": {
      "includeIds": [
        "51e19df9c1d70c7c",
        "971b1b1bfb1ffb1a"
      ],
      "excludeIds": [
        "51e19df9c1d70c7c",
        "971b1b1bfb1ffb1a"
      ],
      "seniorities": [
        "Founder",
        "Owner"
      ],
      "jobTitles": [
        "CEO",
        "CTO"
      ],
      "excludeJobTitles": [
        "CEO",
        "CTO"
      ],
      "departments": [
        "Management",
        "Marketing and Advertising"
      ],
      "countries": [
        "us",
        "dk"
      ],
      "states": [
        {
          "abbreviation": "NY",
          "country": "us"
        },
        {
          "abbreviation": "ON",
          "country": "ca"
        },
        {
          "abbreviation": "5",
          "country": "at"
        },
        {
          "abbreviation": "SH",
          "country": "de"
        }
      ],
      "excludeStates": [
        {
          "abbreviation": "NY",
          "country": "us"
        },
        {
          "abbreviation": "ON",
          "country": "ca"
        },
        {
          "abbreviation": "5",
          "country": "at"
        },
        {
          "abbreviation": "SH",
          "country": "de"
        }
      ],
      "excludeCountries": [
        "us",
        "dk"
      ],
      "names": [
        "John Doe",
        "Peter Pan"
      ],
      "emails": [
        "[email protected]",
        "[email protected]"
      ],
      "keywords": [
        "engineering",
        "research"
      ],
      "fieldsExist": [
        "name",
        "country",
        "linkedinUrl"
      ],
      "fieldsNotExist": [
        "firstName",
        "location",
        "jobTitleEnglish"
      ],
      "changedPositionAfter": "2023-01",
      "changedPositionBefore": "2023-01"
    },
    "companiesFilters": {
      "lookalikeDomains": [
        "bestcustomer.com",
        "idealcustomer.com"
      ],
      "includeDomains": [
        "interesting.com",
        "amazing.com"
      ],
      "excludeDomains": [
        "boring.com",
        "useless.com"
      ],
      "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"
        ]
      },
      "countries": [
        "es",
        "pt"
      ],
      "primaryCountries": [
        "de"
      ],
      "states": [
        {
          "abbreviation": "CA",
          "country": "us"
        },
        {
          "abbreviation": "YT",
          "country": "ca"
        }
      ],
      "primaryStates": [
        {
          "abbreviation": "NY",
          "country": "us"
        }
      ],
      "cities": [
        {
          "city": "New York",
          "country": "us"
        },
        {
          "city": "Los Angeles",
          "country": "us"
        }
      ],
      "primaryCities": [
        {
          "city": "New York",
          "country": "us"
        },
        {
          "city": "Los Angeles",
          "country": "us"
        }
      ],
      "headquarterGeolocation": {
        "latitude": 38.880817,
        "longitude": -77.10216,
        "radius": 1000
      },
      "geolocation": {
        "latitude": 50.83348,
        "longitude": -0.1410065,
        "radius": 5000
      },
      "webTrafficVisits": {
        "from": 1000,
        "to": 10000
      },
      "keywords": {
        "keywords": [
          "premium copy paper",
          "paper"
        ],
        "mode": "anyOf"
      },
      "fieldsExist": [
        "industries",
        "emails",
        "locations"
      ],
      "fieldsNotExist": [
        "industryCategories",
        "phones"
      ],
      "socialMedias": {
        "medias": [
          "linkedin",
          "facebook"
        ],
        "mode": "anyOf"
      },
      "technologies": {
        "mode": "anyOf",
        "technologies": [
          "Amazon Advertising",
          "Google Maps"
        ]
      },
      "minScore": 0.95
    },
    "revealEmails": {
      "includeEmails": true,
      "webhookUrl": "https://url.com/webhook"
    },
    "revealPhones": {
      "includePhones": true,
      "webhookUrl": "https://url.com/webhook"
    },
    "onePersonPerDomain": false,
    "peoplePerCompany": 3
  }'

Response

200

400

402

403

422

{
  "people": [
    {
      "id": "e9447c74eafa8a19",
      "domain": "google.com",
      "name": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "country": "us",
      "state": "CA",
      "location": "Copenhagen, Capital Region, Denmark",
      "linkedinUrl": "https://www.linkedin.com/in/someone",
      "seniorities": [
        "C-Level",
        "Manager"
      ],
      "departments": [
        "Management",
        "Marketing and Advertising"
      ],
      "photo": "http://media.licdn.com/dms/image/somelink",
      "jobTitle": "Professeur",
      "jobTitleEnglish": "Teacher",
      "currentJobDescription": "Software Engineer specializing in cloud infrastructure",
      "experiences": [
        {
          "dateFrom": "2020-01-01",
          "dateTo": "2021-01-01",
          "description": "Software Engineer specializing in cloud infrastructure",
          "domain": "domain.com",
          "jobTitle": "Software Engineer"
        }
      ],
      "summary": "Some text that the person wrote to describe themselves",
      "skills": [
        "Product Management",
        "Entrepreneurship",
        "Social Media"
      ],
      "phone": {
        "numbers": [
          "+4512345678",
          "+33 6 00 00 00 00"
        ],
        "status": "verified"
      },
      "email": {
        "address": "[email protected]",
        "status": "verified"
      },
      "inferredEmails": [
        "[email protected]",
        "[email protected]"
      ],
      "updatedAt": "2022-10-27T12:09:37Z",
      "connectionsCount": 10,
      "followersCount": 50,
      "headline": "Senior Software Engineer | Tech Lead"
    }
  ],
  "searchAfter": "NoBgdA7BAsBMEgGwBoAEAiADgGwK4HN8BTAJwC8wBjAewFt0BdIA",
  "detail": "OK",
  "total": 32871,
  "redirectMap": {
    "given_local_domain.uk": "original.com",
    "ikea.nl": "ikea.com"
  },
  "creditsUsed": 1
}