Search people

People Search finds professionals who match a plain-language description, such as “VPs of sales at solar companies in California”. Each page returns up to 10 people with their current role and employer, location, years of experience, skills, schools, and public profile links. It is available on all plans, including Free.

Search for people

Describe the people you need. See the Quickstart for authentication and SDK setup.

import ContextDev from "context.dev";

const client = new ContextDev({ apiKey: process.env.CONTEXT_DEV_API_KEY });
const people = await client.people.search({
  query: "VPs of sales at solar companies in California",
  filters: { countries: ["US"], years_of_experience_min: 5 },
});

console.log(people.results);

import os
from context.dev import ContextDev

client = ContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])
people = client.people.search(
    query="VPs of sales at solar companies in California",
    filters={"countries": ["US"], "years_of_experience_min": 5},
)

print(people.results)

require "cgi/core"
require "context_dev"

client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))
people = client.people.search(
  query: "VPs of sales at solar companies in California",
  filters: {countries: ["US"], years_of_experience_min: 5},
)

pp people.results

package main

import (
    "context"
    "fmt"
    "os"

    contextdev "github.com/context-dot-dev/context-go-sdk/v2"
    "github.com/context-dot-dev/context-go-sdk/v2/option"
)

func main() {
    client := contextdev.NewClient(option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")))
    people, err := client.People.Search(context.Background(), contextdev.PersonSearchParams{
        Query: "VPs of sales at solar companies in California",
        Filters: contextdev.PersonSearchParamsFilters{
            Countries:            []string{"US"},
            YearsOfExperienceMin: contextdev.Int(5),
        },
    })
    if err != nil {
        panic(err)
    }

    fmt.Printf("%+v\n", people.Results)
}

<?php

require __DIR__.'/vendor/autoload.php';

use ContextDev\Client;

$client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));
$people = $client->people->search(
    query: 'VPs of sales at solar companies in California',
    filters: ['countries' => ['US'], 'yearsOfExperienceMin' => 5],
);

print_r($people->results);

curl https://api.context.dev/v1/people/search \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "VPs of sales at solar companies in California",
    "filters": {"countries": ["US"], "years_of_experience_min": 5}
  }'

Choose a mode

`mode`	How it searches	Query length
`fast` (default)	Matches people on basic criteria, such as their role, location, or background.	Up to 500 characters.
`ultra`	Plans a deeper search, judges each candidate against every criterion in the query, and adds a `match.confidence` score to each result.	Up to 5,000 characters.

Use ultra for detailed requests that combine several criteria. Complex ultra searches can take up to 30 seconds. The SDKs’ default timeouts allow for that; if you set your own client timeout, keep it above 30 seconds. ultra pages cost more than fast pages; see Credits.

import ContextDev from "context.dev";

const client = new ContextDev({ apiKey: process.env.CONTEXT_DEV_API_KEY });
const people = await client.people.search({
  query: "Engineering managers at fintech companies in New York who previously worked at a bank and have led platform teams",
  mode: "ultra",
});

for (const person of people.results) {
  console.log(person.name, person.match?.confidence);
}

import os
from context.dev import ContextDev

client = ContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])
people = client.people.search(
    query="Engineering managers at fintech companies in New York who previously worked at a bank and have led platform teams",
    mode="ultra",
)

for person in people.results:
    print(person.name, person.match.confidence if person.match else None)

require "cgi/core"
require "context_dev"

client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))
people = client.people.search(
  query: "Engineering managers at fintech companies in New York who previously worked at a bank and have led platform teams",
  mode: :ultra,
)

people.results.each do |person|
  puts "#{person.name} #{person.match&.confidence}"
end

package main

import (
    "context"
    "fmt"
    "os"

    contextdev "github.com/context-dot-dev/context-go-sdk/v2"
    "github.com/context-dot-dev/context-go-sdk/v2/option"
)

func main() {
    client := contextdev.NewClient(option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")))
    people, err := client.People.Search(context.Background(), contextdev.PersonSearchParams{
        Query: "Engineering managers at fintech companies in New York who previously worked at a bank and have led platform teams",
        Mode:  contextdev.PersonSearchParamsModeUltra,
    })
    if err != nil {
        panic(err)
    }

    for _, person := range people.Results {
        fmt.Println(person.Name, person.Match.Confidence)
    }
}

<?php

require __DIR__.'/vendor/autoload.php';

use ContextDev\Client;

$client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));
$people = $client->people->search(
    query: 'Engineering managers at fintech companies in New York who previously worked at a bank and have led platform teams',
    mode: 'ultra',
);

foreach ($people->results as $person) {
    echo $person->name, ' ', $person->match?->confidence, PHP_EOL;
}

curl https://api.context.dev/v1/people/search \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Engineering managers at fintech companies in New York who previously worked at a bank and have led platform teams",
    "mode": "ultra"
  }'

Filter results

Filters apply in addition to your query, and every result must match them.

`filters` field	Meaning
`countries`	Countries people live in, as two-letter codes such as `US` or `GB`.
`years_of_experience_min`	Minimum years of professional experience.
`years_of_experience_max`	Maximum years of professional experience; at least `years_of_experience_min`.

Match exact phrases

In fast mode, put a phrase in double quotes to require it word for word. Quoted phrases are matched against a person’s name, headline, current and past job titles, employers, schools, and fields of study.

Query	Returns people whose profile
`"site reliability" engineers in Berlin`	Contains “site reliability”.
`"Stanford" OR "MIT" founders`	Contains “Stanford” or “MIT”.
`product designers -"agency"`	Does not contain “agency”.

OR only joins quoted phrases: in "Workday" OR Oracle, neither name is required. Straight and curly double quotes both work; single quotes are read as plain text.

Read the results

People are in results, most relevant first. Unavailable details are null or empty lists.

{
  "results": [
    {
      "name": "Alex Morgan",
      "description": "Sales leader helping solar companies grow.",
      "profiles": ["https://www.linkedin.com/in/alex-morgan-example/"],
      "location": {"country_code": "US", "region": "California", "city": "San Francisco"},
      "role": {
        "title": "VP of Sales",
        "seniority": "executive",
        "functions": ["sales"],
        "started_on": "2023-06-01",
        "company": {"name": "Solstice", "domain": "solstice.example"}
      },
      "years_of_experience": 12,
      "is_founder": false,
      "skills": ["Enterprise Sales", "Sales Leadership", "Renewable Energy"],
      "schools": ["University of California, Berkeley"]
    }
  ],
  "next_cursor": "<opaque cursor>",
  "request_id": "3f1c2a6e-8b4d-4c1e-9f0a-2d7b5e6c8a91"
}

Field	Meaning
`name`, `description`	Full name and a short summary of what the person does.
`profiles`	Public professional profile URLs.
`location`	Where the person lives: `country_code`, `region`, and `city`.
`role`	Current `title`, `seniority`, `functions`, `started_on` date, and employer `company` with `name` and `domain`.
`years_of_experience`, `is_founder`	Years of professional experience, and whether the person is currently a founder or co-founder.
`skills`, `schools`	Professional skills and schools attended.
`match.confidence`	`ultra` only: how well the person matches your query, from 0 to 1.

To get a fuller profile, send a result’s profiles URL to People Enrich.

Page through results

Pass next_cursor back as cursor with the same query, mode, and filters to fetch the next page. A cursor sent with a different query, mode, or filters returns 400.

{
  "query": "VPs of sales at solar companies in California",
  "filters": {"countries": ["US"], "years_of_experience_min": 5},
  "cursor": "<next_cursor from the previous response>"
}

Stop when next_cursor is null or absent; a full page does not guarantee another page. There is no limit parameter, and one search can page through up to 1,000 people.

Errors and credits

Each page that returns people is charged at its mode’s rate, and pages with no matches are free. See Credits for prices.

Status	Cause	What to do
400	Invalid input, such as a `fast` query over 500 characters, a minimum above the maximum, or a cursor from a different search.	Fix the request. Use `ultra` for longer queries.
402	`USAGE_EXCEEDED`: your balance can’t cover the page.	See insufficient credits.
408	The search did not finish in time.	Retry; a shorter or more specific query can help.
429	`RATE_LIMITED`: your organization hit a request limit.	Wait for `Retry-After`; see rate limits.

Try it in the API playground. The People Search reference lists every field.

Get started

Web data

Entity Enrichment

Automation

Account and billing

Production

Search for people

Choose a mode

Filter results

Match exact phrases

Read the results

Page through results

Errors and credits

​Search for people

​Choose a mode

​Filter results

​Match exact phrases

​Read the results

​Page through results

​Errors and credits

Search for people

Choose a mode

Filter results

Match exact phrases

Read the results

Page through results

Errors and credits