Find people

This guide takes a plain-language description of an audience to a page of people, then shows how to make the search precise, size it for free, page through it and keep it.

Search with a description

Describe who you want in query. The search turns it into filters and answers with them:

curl https://api.outbound.dev/v1/people/search \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "operations directors at logistics companies in Portugal", "limit": 10}'

Read what came back besides the people:

filters: what the search ran with. This is the search from now on.
unresolvedCriteria: parts of the query that could not be turned into a filter. When it is not empty, the search is broader than the query.
closestCompanyMatches: companies the query named that had several same-named matches, and the one the search chose.

A search takes exactly one of query, filters, savedSearchId or savedSearchName.

Refine the filters

Once you have filters, edit them directly. GET /v1/people/filters lists every filter and the values it takes:

curl "https://api.outbound.dev/v1/people/filters?field=job_title_levels" \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"

{
  "fields": {
    "job_title_levels": {
      "valueShape": "term",
      "values": [
        { "label": "Director", "value": "director" },
        { "label": "VP", "value": "vp" }
      ]
    }
  }
}

Free-text filters, such as job titles, companies, schools and skills, have no fixed values. Their entry names the autocomplete query that suggests them:

curl "https://api.outbound.dev/v1/people/autocomplete?field=title&q=head%20of%20operations" \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"

Send a suggestion’s name as the filter value. A value that matches nothing answers 422 with filter_value_unresolved, naming the filter in param.

Count before you pay

Counting is free. Send the same filters to POST /v1/people/count:

curl https://api.outbound.dev/v1/people/count \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters": {"job_title_levels": ["director", "vp"], "job_title_role": ["operations"]}}'

A new count runs in the background. The first answer is 202 with status pending. Send the same request every few seconds until it answers 200:

{ "status": "ready", "total": 1246019, "filters": { "job_title_levels": ["director", "vp"], "job_title_role": ["operations"] } }

A count takes up to about a minute and a half.

Page through the results

Send the filters with the page’s nextCursor as cursor. Only a missing nextCursor marks the end. Each page is charged for its own people, so limit sets what a page can cost: 25 people at most $0.0025. See Pagination.

Look up one person

linkedinUrl finds one person by their LinkedIn profile, as a URL, in/<slug> or the bare slug. Send it alone, or with filters to check the person matches them:

{ "linkedinUrl": "linkedin.com/in/ana-ruiz-ops" }

Keep the search

Save the filters under a title, then run them again whenever you need fresh results:

curl https://api.outbound.dev/v1/saved-searches \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Portugal freight ops", "filters": {"job_title_levels": ["director"], "job_title_role": ["operations"]}}'

curl https://api.outbound.dev/v1/saved-searches/6a1f0c2b9d4e8a7f3c5b2e15/run \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 25}'

A run is a people search: it pages and is charged the same way. Creating, changing and deleting a saved search need a key that can write.

Get started

Concepts

Guides