POST /lead_search • Credits: 10 credits per call plus 0.5 credits per returned profile

Lead Search returns LinkedIn people profiles that match up to 31 filters. The response holds up to 25 profiles per page, a sessionId for the next page, and the total match count. Each POST call costs 10 credits plus 0.5 credits per returned profile.

What does Lead Search do?

Sales teams need lists of people who match a precise profile. Lead Search builds that list from LinkedIn with 31 filters for keyword, geography, seniority, job function, industry, company, school and job title. Lead Search also accepts a full LinkedIn Sales Navigator search URL. RichAPI resolves each filter label, such as Senior or 51-200, to the LinkedIn identifier before the search runs. The data source is LinkedIn. One page returns up to 25 profiles and a session ID for the next page.

Which endpoint does Lead Search use?

Method: POST
URL: https://api.richapi.ai/api/v1/lead_search
Authentication: x-api-key header
Request format: JSON request body
Response: synchronous JSON
Page size: 25 profiles
Credits: 10 credits per call plus 0.5 credits per returned profile

Lead Search accepts the POST method only. If you send GET, the API returns 405.

How to send a Lead Search request

Copy your API key from the RichAPI dashboard.
Choose the filters for the profile that you want to find.
Set each filter parameter to an array of labels, for example "seniority": ["Senior", "Director"].
Set page to 1 for the first page.
Send a POST request to https://api.richapi.ai/api/v1/lead_search.
Send the API key in the x-api-key header.
Read the profiles from the elements array in the response.
Save the sessionId value from the response. Send it back in session_id for the next page.

CAUTION: Each Lead Search call costs 10 credits plus 0.5 credits per returned profile. A full page of 25 profiles costs 22.5 credits.

cURL

curl -X POST https://api.richapi.ai/api/v1/lead_search   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "search_query": "founder",
    "locations": ["United States", "London"],
    "seniority": ["Senior", "Director"],
    "functions": ["Engineering", "Sales"],
    "company_size": ["51-200", "201-500"],
    "exclude_locations": ["India"],
    "page": 1
  }'

Python

import requests

response = requests.post(
    "https://api.richapi.ai/api/v1/lead_search",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "search_query": "founder",
        "locations": ["United States", "London"],
        "seniority": ["Senior", "Director"],
        "functions": ["Engineering", "Sales"],
        "company_size": ["51-200", "201-500"],
        "exclude_locations": ["India"],
        "page": 1,
    },
    timeout=60,
)
response.raise_for_status()
print(response.json())

Node.js

const response = await fetch("https://api.richapi.ai/api/v1/lead_search", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    search_query: "founder",
    locations: ["United States", "London"],
    seniority: ["Senior", "Director"],
    functions: ["Engineering", "Sales"],
    company_size: ["51-200", "201-500"],
    exclude_locations: ["India"],
    page: 1,
  }),
});

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

What parameters does Lead Search accept?

Lead Search accepts 33 parameters. Every parameter is optional. Send at least one filter so that the search returns a useful list. The default "" means that RichAPI does not apply the filter.

Which parameters set the search query?

Parameter	Type	Required	Default	Description
`search_query`	string	No	`""`	Fuzzy keyword search.
`sales_nav_url`	string	No	`""`	Full LinkedIn Sales Navigator search URL. RichAPI accepts it together with the individual filters.

Which parameters filter by geography?

Parameter	Type	Required	Default	Description
`locations`	array	No	`""`	Location text values, for example `United States`.
`geo_ids`	array	No	`""`	LinkedIn geo IDs or location names. RichAPI resolves each name to a geo ID.
`company_headquarter_locations`	array	No	`""`	Company headquarters location filters.

Which parameters filter by person and seniority?

Parameter	Type	Required	Default	Description
`seniority`	array	No	`""`	Seniority labels, for example `Senior`, `Director` or `CXO`.
`functions`	array	No	`""`	Job function labels, for example `Engineering` or `Sales`.
`industries`	array	No	`""`	Industry labels, for example `Software Development` or `Banking`.
`years_of_experience`	array	No	`""`	Experience range labels, for example `3 to 5 years`.
`years_at_current_company`	array	No	`""`	Tenure range labels, for example `1 to 2 years`.
`profile_languages`	array	No	`""`	Profile language labels, for example `English`. RichAPI resolves each label to a language code.
`current_job_titles`	array	No	`""`	Current job title filters.
`past_job_titles`	array	No	`""`	Past job title filters.
`first_names`	array	No	`""`	First name filters.
`last_names`	array	No	`""`	Last name filters.
`schools`	array	No	`""`	School LinkedIn URLs or IDs.
`recently_changed_jobs`	boolean	No	`""`	Filter for people who recently changed jobs.

Which parameters filter by company?

Parameter	Type	Required	Default	Description
`current_companies`	array	No	`""`	Current company LinkedIn URLs or IDs.
`past_companies`	array	No	`""`	Past company LinkedIn URLs or IDs.
`company_size`	array	No	`""`	Company size ranges, for example `51-200` or `201-500`.

Which parameters exclude results?

Parameter	Type	Required	Default	Description
`exclude_seniority`	array	No	`""`	Seniority labels to exclude.
`exclude_functions`	array	No	`""`	Job function labels to exclude.
`exclude_industries`	array	No	`""`	Industry labels to exclude.
`exclude_locations`	array	No	`""`	Location text values to exclude.
`exclude_geo_ids`	array	No	`""`	LinkedIn geo IDs or location names to exclude.
`exclude_current_companies`	array	No	`""`	Current company LinkedIn URLs or IDs to exclude.
`exclude_past_companies`	array	No	`""`	Past company LinkedIn URLs or IDs to exclude.
`exclude_current_job_titles`	array	No	`""`	Current job titles to exclude.
`exclude_past_job_titles`	array	No	`""`	Past job titles to exclude.
`exclude_schools`	array	No	`""`	School LinkedIn URLs or IDs to exclude.
`exclude_company_headquarter_locations`	array	No	`""`	Company headquarters locations to exclude.

Which parameters control paging?

Parameter	Type	Required	Default	Description
`page`	integer	No	`1`	Positive page number for pagination. The default is `1`.
`session_id`	string	No	`""`	Session ID for stable pagination. Omit it and RichAPI generates one. Send the `sessionId` from the first page for every later page.

How does the Sales Navigator URL input work?

The sales_nav_url parameter accepts one full LinkedIn Sales Navigator people-search URL. Build the search in Sales Navigator, copy the URL from the address bar, then set sales_nav_url to that value. RichAPI accepts sales_nav_url together with the individual filter parameters in the same request body. Paging works the same way for a Sales Navigator URL search. Set page and session_id as you do for a filter search.

curl -X POST https://api.richapi.ai/api/v1/lead_search   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "sales_nav_url": "https://www.linkedin.com/sales/search/people?query=...",
    "page": 1
  }'

What does Lead Search return?

{
  "elements": [
    {
      "id": "ACwAAD0vgEYBfTKAh4CcxbRiFnfRzU6XVSI9SaU",
      "premium": false,
      "summary": "Currently pursuing a degree in Systems Analysis and Development...",
      "lastName": "Chambela Geronimo",
      "location": {
        "geoId": "101165590",
        "countryCode": "br",
        "linkedinText": "Santo Andre, Sao Paulo, Brazil"
      },
      "firstName": "Rayara",
      "pictureUrl": "https://media.licdn.com/dms/image/...",
      "linkedinUrl": "https://www.linkedin.com/in/ACwAAD0vgEYBfTKAh4CcxbRiFnfRzU6XVSI9SaU",
      "openProfile": false
    }
  ],
  "sessionId": "session_abc123",
  "pagination": {
    "pageSize": 25,
    "pageNumber": 1,
    "totalPages": 100,
    "totalElements": 12345678,
    "previousElements": 0
  }
}

Which fields does the Lead Search response hold?

Field	Type	Description
`elements`	array	The list of matched lead profiles for this page.
`elements[].id`	string	The LinkedIn profile identifier.
`elements[].premium`	boolean	`true` for a profile with LinkedIn Premium.
`elements[].summary`	string	The profile summary text.
`elements[].lastName`	string	The last name.
`elements[].location`	object	The location of the profile.
`elements[].location.geoId`	string	The LinkedIn geo ID of the location.
`elements[].location.countryCode`	string	The two-letter country code.
`elements[].location.linkedinText`	string	The location text from LinkedIn.
`elements[].firstName`	string	The first name.
`elements[].pictureUrl`	string	The profile picture URL.
`elements[].linkedinUrl`	string	The LinkedIn profile URL.
`elements[].openProfile`	boolean	`true` for a LinkedIn Open Profile.
`sessionId`	string	The session ID to pass for subsequent pages.
`pagination`	object	The pagination data for the search.
`pagination.pageSize`	integer	The number of elements per page.
`pagination.pageNumber`	integer	The current page number. The count starts at 1.
`pagination.totalPages`	integer	The total number of pages.
`pagination.totalElements`	integer	The total number of matched profiles across all pages.
`pagination.previousElements`	integer	The number of elements on the previous pages.

How does Lead Search pagination work?

Lead Search returns one page of up to 25 profiles per call. The first response holds a sessionId value. Send that value in session_id on every later call, together with the same filters and a higher page number. The session keeps the result order stable across pages. If you omit session_id, RichAPI generates a new session and the search starts again from a fresh result set.

A session_id value must start with your API key prefix. Use the sessionId from the first response and do not edit it. Read pagination.totalPages to find how many pages match the filters.

What are the Lead Search filter limits?

Limit	Maximum
Items in one list parameter	70
Location names in `geo_ids` or `exclude_geo_ids`	10
Profiles per page	25
Characters in `session_id`	128

RichAPI resolves each location name in geo_ids with one extra lookup call. To avoid the lookups, send numeric LinkedIn geo IDs instead of names.

How much does Lead Search cost?

Lead Search costs 10 credits per call plus 0.5 credits per returned profile. One credit costs $0.02 on the 1,000 and 5,000 credit packs. Larger packs cost less per credit. A full page of 25 profiles costs 10 + (25 x 0.5) = 22.5 credits. That is $0.45.

Cost of one call, by the number of profiles returned:

Profiles returned	Credits	Cost
0	10	$0.20
5	12.5	$0.25
10	15	$0.30
25 (one full page)	22.5	$0.45

Cost of many calls, with a full page of 25 profiles per call:

Calls	Profiles	Credits	Cost
1	25	22.5	$0.45
10	250	225	$4.50
40	1,000	900	$18.00
100	2,500	2,250	$45.00
400	10,000	9,000	$180.00

RichAPI reserves the credits before the call and refunds them for any response outside the 200 range.

Which errors can Lead Search return?

Status	Meaning	What to do
`400`	The request body failed validation. An unknown filter label, an unresolved location name, a list of more than 70 items, or an invalid `session_id` causes this failure.	Correct the parameter that the error message names.
`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.
`405`	The request used a method other than `POST`.	Send the request again with the `POST` method.
`429`	Too many requests.	Read the `Retry-After` header. Wait that many seconds, then send the request again.
`500`	The API failed.	Send the request again. If the failure repeats, contact support.
`502`	The location lookup failed at the provider.	Send the request again. To avoid the lookup, send numeric geo IDs in `geo_ids`.
`504`	The location lookup exceeded the request deadline.	Reduce the number of location names in `geo_ids`, then send the request again.

Frequently asked questions

Is search_query required for Lead Search?

No. Every one of the 33 Lead Search parameters is optional. Send at least one filter so that the search returns a useful list.

How many profiles does one Lead Search page return?

One Lead Search page returns up to 25 profiles in the elements array. Read pagination.totalPages in the response to find how many pages match the filters.

How do I get the second page of Lead Search results?

Send the same filters again with page set to 2. Set session_id to the sessionId value from the first response.

How much does a Lead Search call cost for zero profiles?

A Lead Search call that returns zero profiles costs the 10 credit base only. That is 10 credits, or $0.20.

Does a failed Lead Search request cost credits?

No. RichAPI refunds the credit reservation for every response outside the 200 range. A 400, 429 or 500 response costs no credits.

Where do I find the valid labels for seniority, functions and industries?

Send a request to the RichAPI Search Reference Data endpoint. It returns every valid label for seniority, industries, functions, years of experience, years at current company, company size and profile languages.

Can I use a Sales Navigator URL and filters in the same Lead Search request?

Yes. Set sales_nav_url to the full Sales Navigator search URL, and set any other filter parameter in the same request body.

Lead Search API