Lookalike people search (RC)

POST /v3/search/people

Note: this endpoint is marked as a Release Candidate (RC). We won't change the format of parameters/results but there is a lot we want to improve, mainly about speed, stability and number of results. Search people using filters. Note: at the moment, lookalikeLinkedinHandles is mandatory.

Query parameters

apiToken string Required

application/json

Body Required

size integer

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

Minimum value is 1.0, maximum value is 10000.0. Default value is 50.
peopleFilters object | null

Additional properties are NOT allowed.
Hide peopleFilters attributes Show peopleFilters attributes object | null
- lookalikePeopleIds array[string] | null Deprecated
- lookalikeLinkedinHandles array[string]
  
  List of people linkedin handles to search for similar people.
- countries array[string] | null
- excludePeopleIds array[string] | null
- excludeLinkedinHandles array[string] | null
- seniorities array[string] | null
  
  Values are Owner, Founder, Board Member, C-Level, Partner, VP, Head, Director, Manager, or Other.
- jobTitleKeywords object | null
  
  Additional properties are NOT allowed.
  Hide jobTitleKeywords attributes Show jobTitleKeywords attributes object | null
  
  allOf array[string] | null
  
  anyOf array[string] | null
  
  noneOf array[string] | null
- regions array[string] | null Deprecated
- 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 state abbreviation. List available in the region section there: /v2/data-fields.
companiesFilters object | null

Additional properties are NOT allowed.
Hide companiesFilters attributes Show companiesFilters attributes object | null
- lookalikeDomains array[string] | null
- includeDomains 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.
- excludeDomains array[string] | null
- primaryCountries 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+.
peoplePerCompany integer | null

Minimum value is 1.0.
jobTitleThreshold number | null

Minimum value is 0.0, maximum value is 1.0. Default value is 0.8.

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
  
  state 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
  
  phone object | null
  
  Additional properties are allowed.
  
  Hide phone attributes Show phone attributes object | null
  
  numbers array[string] | null Required
  
  status string Required
  
  Status of the phone numbers: verified or not found
  
  Values are verified, notFound, or inProgress.
  
  email object | null
  
  Additional properties are allowed.
  
  Hide email attributes Show email attributes object | null
  
  address string | null Required
  
  status string Required
  
  Status of the address: verified, catchAll or guessed
  
  Values are verified, guessed, catchAll, or notFound.
  
  company object Required
  
  Additional properties are allowed.
  
  Hide company attributes Show company attributes object
  
  companySize 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+.
  
  logo string | null
  
  name string | null
- detail string Required
  
  Status text
- total integer | null
403 application/json

Forbidden
Hide response attribute Show response attribute object
- detail string Required
  
  Value is Current API token is not registered in our database.
402 application/json

Payment Required
Hide response attribute Show response attribute object
- detail string Required
  
  Value is Insufficient standard credits.
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
  
  loc array[string | integer] Required
  
  msg string Required
  
  type string Required

POST /v3/search/people

curl \
 -X POST https://api.ocean.io/v3/search/people?apiToken=string \
 -H "Content-Type: application/json" \
 -d '{"size":10,"peopleFilters":{"lookalikePeopleIds":["michael-scott-13532","dwight-schrute"],"lookalikeLinkedinHandles":["michael-scott-13532","dwight-schrute"],"countries":["us","dk"],"excludePeopleIds":["43g19df9c1d70f9a","54hb1b1bfb1ffc5t"],"excludeLinkedinHandles":["jim-halpert-5343","toby-67832"],"seniorities":["Founder","Owner"],"jobTitleKeywords":{"allOf":["Manager"],"anyOf":["Marketing","designer"],"noneOf":["content"]},"regions":["CA","TX"],"states":[{"country":"us","abbreviation":"NY"},{"country":"gb","abbreviation":"UKI"},{"country":"at","abbreviation":"5"},{"country":"de","abbreviation":"SH"}]},"companiesFilters":{"lookalikeDomains":["best-customer.com","ideal-lead.com"],"includeDomains":["interesting.com","potential-lead.io"],"industries":{"mode":"anyOf","industries":["Advertising Platforms","Biopharma"]},"excludeDomains":["waste-of-time.co.uk","useless.com"],"primaryCountries":["de"],"companySizes":["2-10","51-200","100001-500000"]},"peoplePerCompany":3,"jobTitleThreshold":0.8}'

Request examples

{
  "size": 10,
  "peopleFilters": {
    "lookalikePeopleIds": [
      "michael-scott-13532",
      "dwight-schrute"
    ],
    "lookalikeLinkedinHandles": [
      "michael-scott-13532",
      "dwight-schrute"
    ],
    "countries": [
      "us",
      "dk"
    ],
    "excludePeopleIds": [
      "43g19df9c1d70f9a",
      "54hb1b1bfb1ffc5t"
    ],
    "excludeLinkedinHandles": [
      "jim-halpert-5343",
      "toby-67832"
    ],
    "seniorities": [
      "Founder",
      "Owner"
    ],
    "jobTitleKeywords": {
      "allOf": [
        "Manager"
      ],
      "anyOf": [
        "Marketing",
        "designer"
      ],
      "noneOf": [
        "content"
      ]
    },
    "regions": [
      "CA",
      "TX"
    ],
    "states": [
      {
        "country": "us",
        "abbreviation": "NY"
      },
      {
        "country": "gb",
        "abbreviation": "UKI"
      },
      {
        "country": "at",
        "abbreviation": "5"
      },
      {
        "country": "de",
        "abbreviation": "SH"
      }
    ]
  },
  "companiesFilters": {
    "lookalikeDomains": [
      "best-customer.com",
      "ideal-lead.com"
    ],
    "includeDomains": [
      "interesting.com",
      "potential-lead.io"
    ],
    "industries": {
      "mode": "anyOf",
      "industries": [
        "Advertising Platforms",
        "Biopharma"
      ]
    },
    "excludeDomains": [
      "waste-of-time.co.uk",
      "useless.com"
    ],
    "primaryCountries": [
      "de"
    ],
    "companySizes": [
      "2-10",
      "51-200",
      "100001-500000"
    ]
  },
  "peoplePerCompany": 3,
  "jobTitleThreshold": 0.8
}

Response examples (200)

{
  "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",
      "summary": "Some text that the person wrote to describe themselves",
      "phone": {
        "status": "verified",
        "numbers": [
          "+4512345678",
          "+33 6 00 00 00 00"
        ]
      },
      "email": {
        "status": "verified",
        "address": "example.jonas@ocean.io"
      },
      "company": {
        "companySize": "2-10",
        "logo": "https://cdn2.ocean.io/companies-logos-v1/domain.com/020539e284d9318e805301b672ad23047c30818a.png",
        "name": "Dunder Mifflin Paper Company"
      }
    }
  ],
  "detail": "OK",
  "total": 32871
}

Response examples (403)

{
  "detail": "Current API token is not registered in our database"
}

Response examples (402)

{
  "detail": "Insufficient standard credits"
}

Response examples (422)

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}