OCocean
Search

Lookalike people search

Changed on

Search people using filters and/or people Ids

Webhook result: Email results Phone results

post/v3/search/people

Request

  • Base URL
    https://api.ocean.io
  • URL
    https://api.ocean.io/v3/search/people
  • Auth
    none declared

Query parameters

apiTokenstring nullable

Headers

x-api-tokenstring nullable

Request body

sizeinteger

Number of people to return. The maximum value is 10,000.

peoplePerCompanyinteger nullable

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

jobTitleThresholdnumber nullable

Threshold for job title similarity. The value must be between 0 and 1. Default is 0.8

searchAfterstring nullable

Use searchAfter returned by the previous request to get the next page.

Example request

{
  "size": 10,
  "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"
    ],
    "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"
      ]
    },
    "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"
      ]
    },
    "excludeDepartments": [
      "Management",
      "Marketing and Advertising"
    ],
    "subDepartments": {
      "subDepartments": [
        "Software development"
      ]
    },
    "excludeSubDepartments": [
      "Technical support & helpdesk"
    ],
    "fieldsExist": [
      "name",
      "country",
      "linkedinUrl"
    ],
    "fieldsNotExist": [
      "firstName",
      "location",
      "jobTitleEnglish"
    ],
    "changedPositionAfter": "2023-01",
    "changedPositionBefore": "2023-01",
    "updatedWithinMonths": 1
  },
  "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,
    "revenues": [
      "0-1M",
      "1-10M",
      ">1000M"
    ],
    "departmentSizes": [
      {
        "department": "Accounting and Finance",
        "from": 5,
        "to": 10
      }
    ],
    "industries": {
      "industries": [
        "Digital Agencies",
        "Advertising Services"
      ]
    },
    "excludeIndustries": [
      "CRM",
      "B2B"
    ],
    "excludeIndustryCategories": [
      "Information Technology",
      "Privacy and Security"
    ],
    "linkedinIndustries": [
      "Management Consulting",
      "Computer Software"
    ],
    "excludeLinkedinIndustries": [
      "Management Consulting",
      "Computer Software"
    ],
    "fundingRound": {
      "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"
        }
      ]
    },
    "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"
        }
      ]
    },
    "minRelevance": "B",
    "maxRelevance": "B",
    "headcountGrowth": {
      "asPercentage": true
    },
    "departmentHeadcountGrowth": {
      "anyOf": [
        {
          "asPercentage": false,
          "department": "Accounting and Finance",
          "growthRange": {
            "from": -1,
            "to": 3
          },
          "months": "Three months"
        }
      ],
      "allOf": [
        {
          "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": {
      "states": {
        "anyOf": [
          {
            "country": "us"
          }
        ],
        "allOf": [
          {
            "country": "us"
          }
        ],
        "noneOf": [
          {
            "country": "us"
          }
        ]
      }
    }
  },
  "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

Successful Response

detailstring required

Status text

totalinteger nullable

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

searchAfterstring nullable

Pagination cursor. The next page is this searchAfter value sent back in the following request; its absence from a response means there is no next page.

redirectMapobject nullable

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

creditsUsednumber required

Number of credits charged for this request.

includeDomainsStatusesobject nullable

Domains from includeDomains filter that were not found in the search results, along with the reason

Example response

{
  "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"
      ],
      "subDepartments": [
        "Software development"
      ],
      "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"
        ]
      },
      "email": {
        "address": "name@gmail.com"
      },
      "inferredEmails": [
        "john.doe@domain.com",
        "j.doe@domain.com"
      ],
      "updatedAt": "2022-10-27T12:09:37Z",
      "connectionsCount": 10,
      "followersCount": 50,
      "headline": "Senior Software Engineer | Tech Lead",
      "laborStatusOpenToWork": true,
      "laborStatusHiring": true,
      "company": {
        "logo": "https://cdn2.ocean.io/companies-logos-v1/domain.com/020539e284d9318e805301b672ad23047c30818a.png",
        "name": "Dunder Mifflin Paper Company",
        "employeeCountOcean": 57,
        "industries": [
          "Audio",
          "Electronics"
        ],
        "technologies": [
          "Accesso",
          "Adcash",
          "Atlassian Jira"
        ]
      },
      "relevance": "A"
    }
  ],
  "detail": "OK",
  "lookalikePeopleStatuses": {
    "successfulPeople": [
      "person_id_1",
      "person_id_2"
    ],
    "notFoundPeople": [
      "person_id_1",
      "person_id_2"
    ],
    "triggeredDomainPeople": [
      "person_id_1",
      "person_id_2"
    ],
    "missingCompanyInformationPeople": [
      "person_id_1",
      "person_id_2"
    ]
  },
  "total": 32871,
  "searchAfter": "NoBgdA7BAsBMEgGwBoAEAiADgGwK4HN8BTAJwC8wBjAewFt0BdIA",
  "redirectMap": {
    "given_local_domain.uk": "original.com",
    "ikea.nl": "ikea.com"
  },
  "creditsUsed": 1,
  "includeDomainsStatuses": {
    "bad-content-domain.com": "bad content",
    "invalid-domain.com": "invalid domain",
    "not-found-domain.com": "in progress"
  }
}

Changes