POST /people_search • Credits: 0.1 credits per result returned

People Search returns LinkedIn profiles that match company filters and person filters. The response is a paginated list of profiles with the LinkedIn URL, the first name, the last name, and the headline. Each result costs 0.1 credits, so a page of 25 results costs 2.5 credits, or $0.05.

What People Search does

People Search queries an indexed database of LinkedIn profiles. Two filter groups narrow the search. Company filters: LinkedIn company URL, domain, industry, and employee count range. Person filters: job title and location. RichAPI combines both groups and returns the profiles that match every filter in the request body. The response reports the total match count in totalElements and the page count in totalPages.

Endpoint

Method: POST
URL: https://api.richapi.ai/api/v1/people_search
Authentication: x-api-key header
Response: synchronous JSON
Credits: 0.1 per result returned

How to send a People Search request

Create an API key in the RichAPI dashboard.
Set the x-api-key header to your API key.
Set the Content-Type header to application/json.
Add page and limit to the request body. Both parameters are required.
Add the company filters and the person filters that you need.
Send the request to https://api.richapi.ai/api/v1/people_search.
Read the profiles from the content array in the response.
Read numberOfElements in the response to confirm the credit charge.

cURL

curl -X POST https://api.richapi.ai/api/v1/people_search   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "page": 0,
    "limit": 25,
    "domain": ["openai.com"],
    "industry": ["Software Development"],
    "employee_size_start": 50,
    "employee_size_end": 500,
    "job_title": ["CTO", "VP Engineering"],
    "location": ["United States"]
  }'

Python

import requests

response = requests.post(
    "https://api.richapi.ai/api/v1/people_search",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "page": 0,
        "limit": 25,
        "domain": ["openai.com"],
        "industry": ["Software Development"],
        "employee_size_start": 50,
        "employee_size_end": 500,
        "job_title": ["CTO", "VP Engineering"],
        "location": ["United States"],
    },
    timeout=60,
)
response.raise_for_status()
print(response.json())

Node.js

const response = await fetch("https://api.richapi.ai/api/v1/people_search", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    page: 0,
    limit: 25,
    domain: ["openai.com"],
    industry: ["Software Development"],
    employee_size_start: 50,
    employee_size_end: 500,
    job_title: ["CTO", "VP Engineering"],
    location: ["United States"],
  }),
});

const data = await response.json();
console.log(data);

Request parameters

The People Search request body is flat. Every parameter is a top-level key. RichAPI rejects any key that this table does not name, and it returns 400 with the message Unknown input field(s).

Parameter	Type	Required	Default	Description
`page`	integer	Yes	`0`	Page number. The first page is `0`.
`limit`	integer	Yes	`10`	Results per page. The maximum page size is `100`.
`linkedin`	array of strings	No	`[]`	LinkedIn company URLs, for example `https://www.linkedin.com/company/openai/`.
`domain`	array of strings	No	`[]`	Company domains, for example `openai.com`.
`industry`	array of strings	No	`[]`	Industry names, for example `Software Development`.
`employee_size_start`	integer	No	None	Minimum employee count of the company, for example `50`.
`employee_size_end`	integer	No	None	Maximum employee count of the company, for example `500`.
`job_title`	array of strings	No	`[]`	Job titles to match, for example `CTO`.
`location`	array of strings	No	`[]`	Locations to match. A location is a country, a state, or a city.

CAUTION: Send only the parameter names in the table above. RichAPI rejects an unknown key with 400 and charges no credits.

Response

This is an example response for the request above, which sends page: 0 and limit: 25. The values are illustrative, and the profiles are fictional. The content array holds 25 profiles for a request with limit: 25. This example shows the first two profiles.

{
  "last": false,
  "size": 25,
  "first": true,
  "number": 0,
  "content": [
    {
      "url": "https://www.linkedin.com/in/dana-okafor-a91b2c34/",
      "headline": "CTO at Northwind Robotics",
      "lastname": "Okafor",
      "firstname": "Dana"
    },
    {
      "url": "https://www.linkedin.com/in/marcus-reinholt-77d4e015/",
      "headline": "VP Engineering at Lumen Grid Systems",
      "lastname": "Reinholt",
      "firstname": "Marcus"
    }
  ],
  "totalPages": 3321,
  "totalElements": 83001,
  "numberOfElements": 25
}

In this example response, numberOfElements is 25. The charge is 25 x 0.1 = 2.5 credits, or $0.05.

Response fields

Field	Type	Description
`last`	boolean	`true` when the response is the final page of the People Search result set.
`size`	integer	The page size that the People Search request asked for in `limit`.
`first`	boolean	`true` when the response is the first page of the People Search result set.
`number`	integer	The zero-based number of the current page.
`content`	array of objects	The matched LinkedIn profiles.
`content[].url`	string	The LinkedIn profile URL.
`content[].headline`	string	The LinkedIn headline of the profile.
`content[].lastname`	string	The last name of the profile.
`content[].firstname`	string	The first name of the profile.
`totalPages`	integer	The number of pages in the People Search result set.
`totalElements`	integer	The number of profiles that match the filters across all pages.
`numberOfElements`	integer	The number of profiles in this response. RichAPI bills this number.

How much does People Search cost?

People Search costs 0.1 credits for each result that the response returns. One credit costs $0.02 on the 1,000 and 5,000 credit packs. Larger packs cost less per credit.

RichAPI counts the numberOfElements field in the response. RichAPI does not count the limit value in the request body. If the request asks for 100 results and the response returns 73 results, RichAPI charges for 73 results.

The formula is:

credits = numberOfElements x 0.1
cost    = credits x $0.02

The worked example for 73 results is 73 x 0.1 = 7.3 credits, and 7.3 x $0.02 = $0.146.

Results returned (`numberOfElements`)	Arithmetic	Credits	Cost
10	`10 x 0.1`	1	$0.02
25	`25 x 0.1`	2.5	$0.05
50	`50 x 0.1`	5	$0.10
73	`73 x 0.1`	7.3	$0.146
100	`100 x 0.1`	10	$0.20

CAUTION: Do not send a broad People Search filter with limit: 100. A full page of 100 results costs 10 credits, or $0.20.

How do you page through People Search results?

People Search pages are zero-based. Send page: 0 for the first page. To read the next page, increase page by 1 and keep the same filters and the same limit. The response reports totalPages, and last is true on the final page.

Request	Results	Position
`{"page": 0, "limit": 25}`	Results 1 to 25	`first` is `true`
`{"page": 1, "limit": 25}`	Results 26 to 50	Middle page
`{"page": 2, "limit": 25}`	Results 51 to 75	Middle page

This Python loop reads every page until last is true.

import requests

url = "https://api.richapi.ai/api/v1/people_search"
headers = {"x-api-key": "YOUR_API_KEY"}
body = {
    "page": 0,
    "limit": 25,
    "job_title": ["CTO"],
    "location": ["United States"],
}

profiles = []
while True:
    response = requests.post(url, headers=headers, json=body, timeout=60)
    response.raise_for_status()
    data = response.json()
    profiles.extend(data["content"])
    if data["last"]:
        break
    body["page"] = body["page"] + 1

print(len(profiles))

How does pagination affect the People Search cost?

Each page is a separate request, and RichAPI bills each request on its own numberOfElements. The total cost of a paged run is the sum of every page. Ten pages of 25 results return 250 results in total. The arithmetic is 250 x 0.1 = 25 credits, and 25 x $0.02 = $0.50.

Pages read	`limit`	Total results	Arithmetic	Credits	Cost
1	25	25	`25 x 0.1`	2.5	$0.05
4	25	100	`100 x 0.1`	10	$0.20
10	25	250	`250 x 0.1`	25	$0.50
1	100	100	`100 x 0.1`	10	$0.20

A page size of 100 and a page size of 25 cost the same for the same number of results. A larger limit reduces the number of requests. A larger limit does not reduce the credit cost.

CAUTION: Stop the page loop at the number of results that you need. Every extra page charges 0.1 credits for each result that the page returns.

Errors

Status	Meaning	What to do
`400`	The request body failed validation, or it holds an unknown key.	Correct the parameter that the message names. Make sure that `page` and `limit` are present.
`401`	The API key is missing, wrong or revoked.	Send a valid key in the `x-api-key` header.
`402`	`Insufficient credits`: the organization has too few credits. Or `Monthly spend limit reached`: the team hit its monthly spend limit.	Buy credits in the RichAPI dashboard, or ask the organization owner to raise the spend limit.
`403`	`Endpoint not available on your plan`: this API key has no access to this endpoint.	Call `GET /api/v1/my-endpoints` to list the endpoints this key can use. Contact support for access.
`404`	The endpoint name is wrong.	Send the request to `/people_search`.
`429`	Rate limit exceeded (too many requests per second).	Wait for the `Retry-After` seconds, then retry the request.
`500`	The API failed.	Send the request again. If the failure repeats, contact support.
`502`	The upstream provider failed.	Send the request again with exponential backoff.
`504`	The upstream provider timed out.	Reduce `limit`, then send the request again.

A failed request returns a JSON object with an error field. RichAPI charges no credits for a failed request.

A 400 response with the message Unknown input field(s) names each key that RichAPI does not accept. Remove those keys, then send the request again.

Frequently asked questions

How much does one People Search request cost?

One People Search request costs 0.1 credits for each result in the response, and one credit costs $0.02 on the 1,000 and 5,000 credit packs. A response with 25 results costs 2.5 credits, or $0.05.

Does People Search charge for results that it does not return?

No. People Search charges on the numberOfElements field of the response, not on the limit value of the request body. If the request asks for 100 results and only 73 come back, the charge is 73 x 0.1 = 7.3 credits, or $0.146.

What is the maximum page size for People Search?

The maximum value of the limit parameter in a People Search request is 100. The default value is 10.

How do you read the second page of People Search results?

Send the same filters and the same limit value, and set page to 1. People Search page numbers start at 0, so page: 1 returns the second page.

Why does People Search return Unknown input field(s)?

The People Search request body holds a key that RichAPI does not accept. Send only page, limit, linkedin, domain, industry, employee_size_start, employee_size_end, job_title, and location.

How do you find the last People Search page?

The People Search response returns last as true on the final page. The response also returns totalPages, which is the number of pages in the full result set.

Is People Search synchronous?

Yes. People Search returns the profiles in the response of the same HTTP request. People Search needs no polling and no webhook.

Which fields does a People Search result contain?

Each object in the content array contains url, firstname, lastname, and headline. The url field holds the LinkedIn profile URL.

People Search API