Search people

POST /v2/search/people

Search people using filters

application/json

Body Required

  • size integer

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

    Minimum value is 1.0, maximum value is 10000.0. Default value is 50.

  • 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

    Minimum value is 1.0, maximum value is 10001.0. Default value is 1.

  • searchAfter string | null
  • peopleFilters object | null

    Additional properties are NOT allowed.

    Hide peopleFilters attributes Show peopleFilters attributes object | null
    • includeIds array[string] | null
    • excludeIds array[string] | null
    • seniorities array[string] | null

      Values are Owner, Founder, Board Member, C-Level, Partner, VP, Head, Director, Manager, or Other.

    • jobTitles array[string] | null
    • excludeJobTitles array[string] | null
    • departments array[string] | null

      Values are 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, or Other.

    • countries array[string] | null
    • names array[string] | null
    • emailStatuses array[string] | null

      Values are verified, guessed, catchAll, or notAttempted.

    • emails array[string] | null
    • keywords array[string] | null
    • fieldsExist array[string] | null

      Values are country, departments, firstName, jobTitle, jobTitleEnglish, lastName, linkedinUrl, location, name, photo, seniorities, or summary.

    • fieldsNotExist array[string] | null

      Values are country, departments, firstName, jobTitle, jobTitleEnglish, lastName, linkedinUrl, location, name, photo, seniorities, or summary.

    • phoneStatuses array[string] | null

      Values are verified, notFound, inProgress, or notAttempted.

  • companiesFilters object | null

    Additional properties are NOT allowed.

    Hide companiesFilters attributes Show companiesFilters attributes object | null
    • lookalikeDomains array[string] | null

      Not more than 10 elements.

    • minScore number | null

      Default value is 0.79.

    • includeDomains array[string] | null
    • excludeDomains array[string] | null
    • companySizes array[string] | null

      Values are 0-1, 2-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10001-50000, 50001-100000, 100001-500000, or 500000+.

    • ecommerce boolean | null
    • socialMedias object | null

      Additional properties are NOT allowed.

      Hide socialMedias attributes Show socialMedias attributes object | null
      • medias array[string] Required

        Array of the social medias to include

        Values are linkedin, x, facebook, instagram, youtube, xing, or tiktok.

      • mode string

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

        Values are anyOf or allOf. Default value is anyOf.

    • yearFounded object | null

      Additional properties are NOT allowed.

      Hide yearFounded attributes Show yearFounded attributes object | null
      • from integer | null

        Minimum value is 0.0.

      • to integer | null

        Minimum value is 0.0.

    • countriesCount object | null

      Additional properties are NOT allowed.

      Hide countriesCount attributes Show countriesCount attributes object | null
      • from integer | null

        Minimum value is 0.0.

      • to integer | null

        Minimum value is 0.0.

    • revenues array[string] | null

      Values are 0-1M, 1-10M, 10-50M, 50-100M, 100-500M, 500-1000M, or >1000M.

    • employeeCountOcean object | null

      Additional properties are NOT allowed.

      Hide employeeCountOcean attributes Show employeeCountOcean attributes object | null
      • from integer | null

        Minimum value is 0.0.

      • to integer | null

        Minimum value is 0.0.

    • webTrafficVisits object | null

      Additional properties are NOT allowed.

      Hide webTrafficVisits attributes Show webTrafficVisits attributes object | null
      • from integer | null

        Minimum value is 0.0.

      • to integer | null

        Minimum value is 0.0.

    • mobileApps object | null

      Additional properties are NOT allowed.

      Hide mobileApps attributes Show mobileApps attributes object | null
      • from integer | null

        Minimum value is 0.0.

      • to integer | null

        Minimum value is 0.0.

    • headquarterGeolocation object | null

      Additional properties are NOT allowed.

      Hide headquarterGeolocation attributes Show headquarterGeolocation attributes object | null
    • geolocation object | null

      Additional properties are NOT allowed.

      Hide geolocation attributes Show geolocation attributes object | null
    • locationsCount object | null

      Additional properties are NOT allowed.

      Hide locationsCount attributes Show locationsCount attributes object | null
      • from integer | null

        Minimum value is 0.0.

      • to integer | null

        Minimum value is 0.0.

    • departmentSizes array[object] | null
      Hide departmentSizes attributes Show departmentSizes attributes object
      • from integer | null

        Minimum value is 0.0.

      • to integer | null

        Minimum value is 0.0.

      • department string Required

        Values are 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, or Other.

    • keywords object | null

      Additional properties are NOT allowed.

      Hide keywords attributes Show keywords attributes object | null
      • keywords array[string] Required

        Array of the keywords

      • mode string

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

        Values are anyOf, allOf, or noneOf. Default value is anyOf.

    • states array[object] | null
      Hide states attributes Show states attributes object
      • country string Required

        Values are at, ca, ch, de, es, fr, gb, or us.

      • abbreviation string Required

        Valid ISO state abbreviation

    • employeeCountLinkedin object | null

      Additional properties are NOT allowed.

      Hide employeeCountLinkedin attributes Show employeeCountLinkedin attributes object | null
      • from integer | null

        Minimum value is 0.0.

      • to integer | null

        Minimum value is 0.0.

    • countries array[string] | null
    • primaryCountries array[string] | null
    • industries object | null

      Additional properties are NOT allowed.

      Hide industries attributes Show industries attributes object | null
      • industries array[string] Required

        Array of the industries to include

      • mode string

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

        Values are anyOf or allOf. Default value is anyOf.

    • excludeIndustries array[string]

      Array of the industries to exclude

    • industryCategories object | null

      Additional properties are NOT allowed.

      Hide industryCategories attributes Show industryCategories attributes object | null
      • industryCategories array[string] Required

        Array of the industry categories to include

      • mode string

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

        Values are anyOf or allOf. Default value is anyOf.

    • excludeIndustryCategories array[string]

      Array of the industry categories to exclude

    • technologies object | null

      Additional properties are NOT allowed.

      Hide technologies attributes Show technologies attributes object | null
      • technologies array[string] Required

        Array of the technologies to include

      • mode string

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

        Values are anyOf or allOf. Default value is anyOf.

    • fieldsExist array[string] | null

      Values are companySize, countries, departmentSizes, description, emails, faxes, impressum, industries, industryCategories, keywords, legalName, locations, logo, medias, mobileApps, name, phones, primaryCountry, revenue, rootUrl, technologies, technologyCategories, webTraffic, or yearFounded.

    • fieldsNotExist array[string] | null

      Values are companySize, countries, departmentSizes, description, emails, faxes, impressum, industries, industryCategories, keywords, legalName, locations, logo, medias, mobileApps, name, phones, primaryCountry, revenue, rootUrl, technologies, technologyCategories, webTraffic, or yearFounded.

  • revealEmails object | null

    Additional properties are NOT allowed.

    Hide revealEmails attributes Show revealEmails attributes object | null
    • includeEmails boolean

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

      Default value is false.

    • webhookUrl string | null
  • revealPhones object | null

    Additional properties are NOT allowed.

    Hide revealPhones attributes Show revealPhones attributes object | null
    • includePhones boolean

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

      Default value is false.

    • webhookUrl string | null
  • onePersonPerDomain boolean

    Only return one person per company

    Default value is false.

Responses

  • 200 application/json

    Successful Response

    Hide response attributes Show response attributes object
    • people array[object] Required
      Hide people attributes Show people attributes object
      • id string Required

        Internal ocean id of the person

      • domain string Required

        Domain of the company the person is working for

      • name string | null
      • firstName string | null
      • lastName string | null
      • country string | null
      • location string | null
      • linkedinUrl string | null
      • seniorities array[string] | null

        Values are Owner, Founder, Board Member, C-Level, Partner, VP, Head, Director, Manager, or Other.

      • departments array[string] | null

        Values are 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, or Other.

      • photo string | null
      • jobTitle string | null
      • jobTitleEnglish string | null
      • summary string | null
    • searchAfter string | null
    • detail string Required

      Status text

    • total integer | null
  • 404

    Not found

  • 422 application/json

    Validation Error

    Hide response attribute Show response attribute object
    • detail array[object]
      Hide detail attributes Show detail attributes object
POST /v2/search/people 
curl \
 -X POST https://api.ocean.io/v2/search/people?apiToken=string \
 -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"],"names":["John Doe","Peter Pan"],"emailStatuses":["verified","catchAll"],"emails":["email_1@domain.com","email_2@domain.com"],"keywords":["engineering","research"],"fieldsExist":["name","country","linkedinUrl"],"fieldsNotExist":["firstName","location","jobTitleEnglish"],"phoneStatuses":["verified","notFound"]},"companiesFilters":{"lookalikeDomains":["bestcustomer.com","idealcustomer.com"],"minScore":0.95,"includeDomains":["interesting.com","amazing.com"],"excludeDomains":["boring.com","useless.com"],"companySizes":["2-10","51-200","100001-500000"],"ecommerce":true,"socialMedias":{"mode":"anyOf","medias":["linkedin","facebook"]},"yearFounded":{"to":1990,"from":1960},"countriesCount":{"to":5,"from":1},"revenues":["0-1M","1-10M","\u003e1000M"],"employeeCountOcean":{"to":100,"from":10},"webTrafficVisits":{"to":10000,"from":1000},"mobileApps":{"to":5,"from":1},"headquarterGeolocation":{"radius":1000,"latitude":38.880817,"longitude":-77.10216},"geolocation":{"radius":5000,"latitude":50.83348,"longitude":-0.1410065},"locationsCount":{"to":10,"from":5},"departmentSizes":[{"to":10,"from":5,"department":"Accounting and Finance"}],"keywords":{"mode":"anyOf","keywords":["premium copy paper","paper"]},"states":[{"country":"us","abbreviation":"ca"},{"country":"ca","abbreviation":"yt"}],"employeeCountLinkedin":{"to":100,"from":50},"countries":["es","pt"],"primaryCountries":["de"],"industries":{"mode":"anyOf","industries":["Advertising Platforms","Biopharma"]},"excludeIndustries":["CRM","B2B"],"industryCategories":{"mode":"anyOf","industryCategories":["Real Estate","Hardware"]},"excludeIndustryCategories":["Information Technology","Privacy and Security"],"technologies":{"mode":"anyOf","technologies":["Amazon Advertising","Google Maps"]},"fieldsExist":["industries","emails","locations"],"fieldsNotExist":["industryCategories","phones"]},"revealEmails":{"webhookUrl":"https://url.com/webhook","includeEmails":true},"revealPhones":{"webhookUrl":"https://url.com/webhook","includePhones":true},"onePersonPerDomain":false}'
Request examples 
{
  "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"
    ],
    "names": [
      "John Doe",
      "Peter Pan"
    ],
    "emailStatuses": [
      "verified",
      "catchAll"
    ],
    "emails": [
      "email_1@domain.com",
      "email_2@domain.com"
    ],
    "keywords": [
      "engineering",
      "research"
    ],
    "fieldsExist": [
      "name",
      "country",
      "linkedinUrl"
    ],
    "fieldsNotExist": [
      "firstName",
      "location",
      "jobTitleEnglish"
    ],
    "phoneStatuses": [
      "verified",
      "notFound"
    ]
  },
  "companiesFilters": {
    "lookalikeDomains": [
      "bestcustomer.com",
      "idealcustomer.com"
    ],
    "minScore": 0.95,
    "includeDomains": [
      "interesting.com",
      "amazing.com"
    ],
    "excludeDomains": [
      "boring.com",
      "useless.com"
    ],
    "companySizes": [
      "2-10",
      "51-200",
      "100001-500000"
    ],
    "ecommerce": true,
    "socialMedias": {
      "mode": "anyOf",
      "medias": [
        "linkedin",
        "facebook"
      ]
    },
    "yearFounded": {
      "to": 1990,
      "from": 1960
    },
    "countriesCount": {
      "to": 5,
      "from": 1
    },
    "revenues": [
      "0-1M",
      "1-10M",
      ">1000M"
    ],
    "employeeCountOcean": {
      "to": 100,
      "from": 10
    },
    "webTrafficVisits": {
      "to": 10000,
      "from": 1000
    },
    "mobileApps": {
      "to": 5,
      "from": 1
    },
    "headquarterGeolocation": {
      "radius": 1000,
      "latitude": 38.880817,
      "longitude": -77.10216
    },
    "geolocation": {
      "radius": 5000,
      "latitude": 50.83348,
      "longitude": -0.1410065
    },
    "locationsCount": {
      "to": 10,
      "from": 5
    },
    "departmentSizes": [
      {
        "to": 10,
        "from": 5,
        "department": "Accounting and Finance"
      }
    ],
    "keywords": {
      "mode": "anyOf",
      "keywords": [
        "premium copy paper",
        "paper"
      ]
    },
    "states": [
      {
        "country": "us",
        "abbreviation": "ca"
      },
      {
        "country": "ca",
        "abbreviation": "yt"
      }
    ],
    "employeeCountLinkedin": {
      "to": 100,
      "from": 50
    },
    "countries": [
      "es",
      "pt"
    ],
    "primaryCountries": [
      "de"
    ],
    "industries": {
      "mode": "anyOf",
      "industries": [
        "Advertising Platforms",
        "Biopharma"
      ]
    },
    "excludeIndustries": [
      "CRM",
      "B2B"
    ],
    "industryCategories": {
      "mode": "anyOf",
      "industryCategories": [
        "Real Estate",
        "Hardware"
      ]
    },
    "excludeIndustryCategories": [
      "Information Technology",
      "Privacy and Security"
    ],
    "technologies": {
      "mode": "anyOf",
      "technologies": [
        "Amazon Advertising",
        "Google Maps"
      ]
    },
    "fieldsExist": [
      "industries",
      "emails",
      "locations"
    ],
    "fieldsNotExist": [
      "industryCategories",
      "phones"
    ]
  },
  "revealEmails": {
    "webhookUrl": "https://url.com/webhook",
    "includeEmails": true
  },
  "revealPhones": {
    "webhookUrl": "https://url.com/webhook",
    "includePhones": true
  },
  "onePersonPerDomain": false
}
Response examples (200) 
{
  "people": [
    {
      "id": "e9447c74eafa8a19",
      "domain": "google.com",
      "name": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "country": "us",
      "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",
      "summary": "Some text that the person wrote to describe themselves"
    }
  ],
  "searchAfter": "NoBgdA7BAsBMEgGwBoAEAiADgGwK4HN8BTAJwC8wBjAewFt0BdIA",
  "detail": "OK",
  "total": 32871
}
Response examples (422) 
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}