Docs · API reference

Search people

Start a search for people by job title, then ask for the results. Each person is checked against their live profile, so a search takes a few minutes. People come back with no email: use Find a work email for the ones you want.

Preview: may change before launch · Updated 1 November 2026

Preview

This is how the API is planned to work. Names and fields may change before launch. The APIs are in early access: join early access to get a key when they're ready.

POST https://api.magpie-cloud.com/v1/people/searches. What it's for, and how it works: Prospect search API.

Request

A JSON body, with your API key in the Authorization header (see Authentication).

Field	Type	Required	What it is
`titles`	string[]	Yes	1 to 10 job titles to match, such as `Head of Operations`.
`seniorities`	string[]	No	Any of `owner`, `founder`, `c_suite`, `partner`, `vp`, `head`, `director`, `manager`, `senior`, `entry`, `intern`, worked out from each person's title.
`countries`	string[]	No	Two-letter codes, such as `GB`.
`cities`	string[]	No	Cities to search in.
`industries`	string[]	No	The industries of the companies they work at.
`headcount`	object	No	`min` and `max` employees at their company.
`companies`	string[]	No	Up to 25 company names. Few people pass this filter.
`limit`	integer	No	How many people to look for, from 1 to 200. 25 if left out.

Example

Request · POST /people/searches

curl https://api.magpie-cloud.com/v1/people/searches \
  -H "Authorization: Bearer $MAGPIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "titles": ["Head of Operations"],
    "seniorities": ["head", "director"],
    "industries": ["Truck Transportation"],
    "countries": ["GB"],
    "limit": 25
  }'

const res = await fetch("https://api.magpie-cloud.com/v1/people/searches", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAGPIE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    titles: ["Head of Operations"],
    seniorities: ["head", "director"],
    industries: ["Truck Transportation"],
    countries: ["GB"],
    limit: 25,
  }),
});
const data = await res.json();

import os
import requests

res = requests.post(
    "https://api.magpie-cloud.com/v1/people/searches",
    json={
        "titles": ["Head of Operations"],
        "seniorities": ["head", "director"],
        "industries": ["Truck Transportation"],
        "countries": ["GB"],
        "limit": 25,
    },
    headers={"Authorization": f"Bearer {os.environ['MAGPIE_API_KEY']}"},
    timeout=90,
)
data = res.json()

Response · 200

{
  "id": "ps_0baf089fe94eedd45f",
  "status": "running",
  "limit": 25,
  "poll_after_ms": 5000
}

Ask for the results until status is done. People arrive as they're confirmed, each with a name, title, seniority, company, country and profile link, and next pages through them with cursor. stats says how many candidates were looked at, so an empty search can be explained.

Response: GET /people/searches/{id}

{
  "id": "ps_0baf089fe94eedd45f",
  "status": "done",
  "found": 1,
  "people": [
    {
      "name": "Alex Sample",
      "title": "Head of Operations",
      "title_verified": true,
      "seniority": "head",
      "company": {
        "name": "Example Freight Ltd",
        "domain": "examplefreight.example",
        "industry": "Truck Transportation",
        "headcount": "51-200"
      },
      "country": "GB",
      "profile_url": "https://profiles.example/alex-sample"
    }
  ],
  "next": null,
  "stats": {
    "searches": 3,
    "candidates": 9,
    "verified": 1,
    "rejected": {
      "title mismatch": 8
    }
  },
  "credits_charged": 1
}

Response

Field	Type	What it is
`id`	string	The search's id, for asking for its results.
`status`	string	`running`.
`poll_after_ms`	integer	How long to wait before asking for results, in milliseconds.

Errors

Errors come back as JSON with a code and a message. See Errors for the shape, and when to try again.

Status	Code	When
`400`	`invalid_request`	A filter isn't valid, or `titles` is missing.
`401`	`unauthorized`	The API key is missing, wrong or revoked.
`402`	`out_of_credits`	Your credits have run out.
`403`	`feature_unavailable`	People search isn't open to your account yet.
`429`	`poll_too_soon`	You asked for results within 2 seconds of asking before.
`429`	`rate_limited`	Too many requests. Wait the number of seconds in the `Retry-After` header, then try again.
`5xx`	Varies	Something went wrong on our side. Safe to try again after a short wait.

Billing

The planned price is 1 credit (£0.004$0.006) for each person returned. It may change before launch. Starting a search is free, and a search that finds no one costs nothing.

See Credits and prices for how credits work.

Notes

POST /people/searches/{id}/more carries on the same search through its next cities, and DELETE /people/searches/{id} stops one. Nobody is charged twice.
An account can run one search at a time and start 20 a day. A search forgotten for an hour expires.
People who have opted out of prospecting are left out.
Nobody is kept on our side: what you store is up to you.

Questions about the APIs? Email pele@magpiecrm.com.