Search people

Finds people by a plain-language query, by filters, or by a saved search (savedSearchId or savedSearchName): send exactly one. linkedinUrl looks up one person, on its own or within the search.

Returns one page of people and the filters the search ran with. For the next page, send those filters with the page’s pagination.nextCursor as cursor. A page can hold fewer people than limit, so only a missing nextCursor marks the end. People never carry an email address or a phone number.

Price: $0.0001 per person returned. Before the search runs, limit times $0.0001 is held from your balance, and what the page does not use is released. A page with nothing on it costs nothing. Scope: search. Read-only keys may call it.

POST /v1/people/search

Search people

cURL

curl --request POST \
  --url https://api.outbound.dev/v1/people/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "operations directors at logistics companies in Portugal",
  "limit": 25
}
'

200

{
  "data": [
    {
      "linkedinMemberId": "ACoAAB2cdEF",
      "linkedin_url": "linkedin.com/in/ana-ruiz-ops",
      "full_name": "Ana Ruiz",
      "first_name": "Ana",
      "last_name": "Ruiz",
      "job_title": "Director of Operations",
      "job_title_levels": [
        "director"
      ],
      "job_title_role": "operations",
      "job_company_name": "Halden Freight",
      "job_company_website": "haldenfreight.com",
      "job_company_linkedin_url": "linkedin.com/company/halden-freight",
      "job_company_employee_count": 240,
      "location_name": "lisbon, lisbon, portugal"
    }
  ],
  "pagination": {
    "nextCursor": "c2Nyb2xsXzI",
    "total": 1246
  },
  "filters": {
    "job_title_levels": [
      "director"
    ],
    "job_title_role": [
      "operations"
    ],
    "job_company_location_country": [
      "portugal"
    ]
  }
}

Authorizations

Authorization · string · header · required

An API key from the console, starting ob_live_, sent as Authorization: Bearer <key>.

Body

application/json

query · string

Who to find, in plain language. It is turned into filters, which the page answers with as filters.

Required string length: 1 - 2000

Example:

"operations directors at logistics companies in Portugal"

filters · object

Filters by name, with values from GET /v1/people/filters and GET /v1/people/autocomplete.

Show child attributes

Example:

{
  "job_title_levels": ["director", "vp"],
  "job_title_role": ["operations"]
}

savedSearchId · string

Run a saved people search by its id.

Required string length: 24

Pattern: ^[0-9a-fA-F]+$

savedSearchName · string

Run a saved people search by its title. A title several saved searches share answers 409 saved_search_name_ambiguous.

Required string length: 1 - 255

linkedinUrl · string

Look up one person by a LinkedIn profile URL, in/<slug> or the bare slug. It counts as a search on its own, or narrows one.

Required string length: 1 - 2048

limit · integer · default: 10

People per page. The page's most possible cost, limit times $0.0001, is held from your balance first.

Required range: 1 <= x <= 100

cursor · string

The pagination.nextCursor of the page before. Send it with the same search, as the filters the first page answered with.

Required string length: 1 - 4096

Response

200

application/json

One page of people.

data · object[] · required

Show child attributes

pagination · object · required

Show child attributes

filters · object · required

The filters the search ran with. Send them with cursor for the next page, or save them as a saved search.

unresolvedCriteria · string[]

With query: the parts of it that could not be turned into a filter.

closestCompanyMatches · object[]

With query: each company it named that the search chose between same-named companies for, and the one chosen.

Show child attributes

ignoredFilterKeys · string[]

With a saved search: stored filters the search no longer takes, left out.

unappliedCompanyNames · object[]

Company names in the filters the search could not apply yet, by filter.