Search people (live)

Written and maintained by The ProspectAPIs team

POST/v1/people/search

POST /v1/people/search is the ProspectAPIs operation searchPeople, in the People reads group of the REST API. Search people by keywords and filters, read fresh. Returns the first 1,000 results per query; page with start. $0.012 per live read. Billed per call once the reads are live; while they are not yet on sale the call is free (GET /pricing reports people_reads.available). Cost: $0.012 per live read, up to 1,000 results a query. Send your API key as a Bearer token in the Authorization header.

The quickstart shows this call in context, next to the first requests most integrations make.

Parameters

Parameters of POST /v1/people/search
Name	In	Type	Description
Idempotency-Key	header	string	Optional, 1 to 255 printable ASCII characters. A retry with the same key and body within 24 hours gets the first answer back with Idempotent-Replayed: true and is never charged again. The same key with a different body is 422; a retry while the first call is still running is 409.

Request body

JSON. Give keywords or at least one filter.

Request body of POST /v1/people/search
Field	Type	Description
keywords	string	Free-text keywords. At most 500 characters.
filters	object	Named filters: network, current_company, past_company, location, industry, school, profile_language, connection_of, service_category, first_name, last_name, title, company, school_name.
start	integer	Zero-based offset into the first 1,000 results. 0 to 999.
count	integer	Results per page. 1 to 50.

Example body

{}

Responses

Response codes of POST /v1/people/search
Status	Meaning
200	The matching people and a page cursor, read fresh.
400	The request was invalid (e.g. a bad filter or input); nothing was charged.
401	The API key is missing or invalid.
402	Out of credits. The body carries top_up_url; nothing was charged.
429	Too many requests; retry after the window.
503	This read is temporarily unavailable. Nothing was charged.

Every error answers with the same JSON body, an error string and sometimes a code; the errors page lists each status and when it happens. A per-key 429 carries Retry-After; see rate limits.

200 response fields

The matching people and a page cursor, read fresh. The body is a PeopleReadResult.

Fields of the 200 response
Field	Type	Description
data required	object	The read result. For search, posts, engagers and followers this is { items, page }; for a profile it is the profile object.
coverage required	object	How complete the source was.
coverage.filled	integer
coverage.of	integer

Response headers
Header	Meaning
RateLimit-Limit	Requests this API key may make per minute.
RateLimit-Remaining	Requests left in the current one-minute window.
RateLimit-Reset	Seconds until the current window resets.

Code samples

Each sample sends the same request. Set PROSPECTAPIS_KEY in your environment first. Values come from the spec's examples; replace them with your own.

curl

curl -X POST https://api.prospectapis.com/v1/people/search \
  -H "Authorization: Bearer $PROSPECTAPIS_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

JavaScript (fetch)

const res = await fetch("https://api.prospectapis.com/v1/people/search", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PROSPECTAPIS_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json().catch(() => ({}))).error ?? res.statusText}`);
const data = await res.json();
console.log(data);

Python (requests)

import os, requests

res = requests.post(
    "https://api.prospectapis.com/v1/people/search",
    headers={"Authorization": f"Bearer {os.environ['PROSPECTAPIS_KEY']}"},
    json={},
    timeout=30,
)
res.raise_for_status()
data = res.json()
print(data)

Billing

Billing reserves before it serves: the call holds what it may cost, serves at most what that hold covers, and refunds the rest when the response closes. Any non-2xx answer refunds the whole hold, so a failed call costs nothing. The response reports your balance in X-Credits-Remaining.

Previous operation: Read a person's profile (live). Next operation: Read a person's posts (live). Every operation, grouped by area, is on the API reference index.

Create a free account to get a key, then run the samples above with your own values (this call acts for real, so use real inputs).

Was this page helpful?