POST /search_reference_data • Credits: 0 credits per call. The endpoint is free.

Search Reference Data returns the complete list of filter labels that RichAPI accepts in a Lead Search request. The response holds seven lists: seniority levels, industries, job functions, years of experience, years at current company, company sizes and profile languages. The endpoint is free. Each POST call costs 0 credits.

What does Search Reference Data do?

Lead Search rejects a filter label that it does not hold in its catalog. Search Reference Data returns every label that RichAPI accepts, so you can build a valid Lead Search request on the first attempt. RichAPI holds the labels as a static mapping and resolves each one to a LinkedIn identifier before a search runs. The endpoint reads that mapping and returns the labels only. The endpoint calls no external provider, so the response is immediate and the cost is 0 credits. Call it as often as you need.

Which endpoint does Search Reference Data use?

Method:POST
URL:https://api.richapi.ai/api/v1/search_reference_data
Authentication:x-api-key header
Request body: An empty JSON object {}
Response: Synchronous JSON
Credits: 0 credits per call

Search Reference Data accepts the POST method only. If you send GET, the API returns 405 with the error search_reference_data only supports POST. Put no parameter in the query string.

How to send a Search Reference Data request

Copy your API key from the RichAPI dashboard.
Send a POST request to https://api.richapi.ai/api/v1/search_reference_data.
Set the x-api-key header to your API key.
Set the Content-Type header to application/json.
Send an empty JSON object {} as the request body.
Read the list that matches the Lead Search filter that you want to set.

cURL

curl -X POST https://api.richapi.ai/api/v1/search_reference_data   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{}'

Python

import requests

response = requests.post(
    "https://api.richapi.ai/api/v1/search_reference_data",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={},
    timeout=60,
)
response.raise_for_status()
catalog = response.json()
print(catalog["seniority"])

Node.js

const response = await fetch("https://api.richapi.ai/api/v1/search_reference_data", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});

const catalog = await response.json();
console.log(catalog.seniority);

Which reference data types does Search Reference Data return?

Search Reference Data returns seven lists in one response. Each list maps to one Lead Search parameter. Send a value from the list exactly as the response spells it.

Response key	What the list holds	Values	Lead Search parameter	Example values
`seniority`	Seniority levels	10	`seniority`, `exclude_seniority`	`Senior`, `Director`, `CXO`
`industries`	LinkedIn industry names	434	`industries`, `exclude_industries`	`Software Development`, `Banking`
`functions`	Job functions	26	`functions`, `exclude_functions`	`Engineering`, `Sales`
`yearsOfExperience`	Total experience ranges	5	`years_of_experience`	`3 to 5 years`
`yearsAtCurrentCompany`	Tenure ranges at the current employer	5	`years_at_current_company`	`1 to 2 years`
`companySize`	Company headcount ranges	9	`company_size`	`51-200`, `1001-5000`
`profileLanguages`	Profile languages and language codes	22	`profile_languages`	`English`, `French`

The profileLanguages value is an object. The key is the label and the value is the language code, for example "English": "en". Send the label, not the code.

Which parameters does Search Reference Data accept?

Search Reference Data accepts no parameter. The request body is an empty JSON object {}. The response is the same for every request and for every workspace.

Parameter	Type	Required	Default	Description
None	—	—	—	Search Reference Data takes no parameter. Send `{}` as the request body.

What does Search Reference Data return?

The block below is an example response. The industries array is shortened to 8 entries. The real industries array holds 434 entries in alphabetical order.

{
  "seniority": [
    "CXO",
    "Director",
    "Entry Level",
    "Entry Level Manager",
    "Experienced Manager",
    "In Training",
    "Owner / Partner",
    "Senior",
    "Strategic",
    "Vice President"
  ],
  "industries": [
    "Abrasives and Nonmetallic Minerals Manufacturing",
    "Accessible Architecture and Design",
    "Accessible Hardware Manufacturing",
    "Accommodation Services",
    "Accounting",
    "Administration of Justice",
    "Administrative and Support Services",
    "Advertising Services"
  ],
  "functions": [
    "Accounting",
    "Administrative",
    "Arts and Design",
    "Business Development",
    "Community and Social Services",
    "Consulting",
    "Customer Success and Support",
    "Education",
    "Engineering",
    "Entrepreneurship",
    "Finance",
    "Healthcare Services",
    "Human Resources",
    "Information Technology",
    "Legal",
    "Marketing",
    "Media and Communication",
    "Military and Protective Services",
    "Operations",
    "Product Management",
    "Program and Project Management",
    "Purchasing",
    "Quality Assurance",
    "Real Estate",
    "Research",
    "Sales"
  ],
  "yearsOfExperience": [
    "Less than 1 year",
    "1 to 2 years",
    "3 to 5 years",
    "6 to 10 years",
    "More than 10 years"
  ],
  "yearsAtCurrentCompany": [
    "Less than 1 year",
    "1 to 2 years",
    "3 to 5 years",
    "6 to 10 years",
    "More than 10 years"
  ],
  "companySize": [
    "Self-employed",
    "1-10",
    "11-50",
    "51-200",
    "201-500",
    "501-1000",
    "1001-5000",
    "5001-10000",
    "10001+"
  ],
  "profileLanguages": {
    "Arabic": "ar",
    "Bahasa Indonesia": "in",
    "Chinese": "zh",
    "Czech": "cs",
    "Danish": "da",
    "Dutch": "nl",
    "English": "en",
    "French": "fr",
    "German": "de",
    "Italian": "it",
    "Japanese": "ja",
    "Korean": "ko",
    "Malay": "ms",
    "Norwegian": "no",
    "Polish": "pl",
    "Portuguese": "pt",
    "Romanian": "ro",
    "Russian": "ru",
    "Spanish": "es",
    "Swedish": "sv",
    "Tagalog": "tl",
    "Turkish": "tr"
  }
}

Which response fields does Search Reference Data return?

Field	Type	Description
`seniority`	array of strings	Valid seniority level labels. 10 entries, in alphabetical order.
`industries`	array of strings	Valid LinkedIn industry labels. 434 entries, in alphabetical order.
`functions`	array of strings	Valid job function labels. 26 entries, in alphabetical order.
`yearsOfExperience`	array of strings	Valid total experience range labels. 5 entries.
`yearsAtCurrentCompany`	array of strings	Valid tenure range labels for the current employer. 5 entries.
`companySize`	array of strings	Valid company headcount range labels. 9 entries.
`profileLanguages`	object	Valid profile language labels. The key is the label and the value is the language code. 22 entries.

How do I use a reference label in a Lead Search request?

Follow these steps to find the valid seniority labels and then filter a Lead Search by one of them.

Send the Search Reference Data request and read the seniority array.

curl -X POST https://api.richapi.ai/api/v1/search_reference_data   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{}'

Pick the labels that you need from the seniority array, for example Director and Vice President.
Send the Lead Search request with those labels in the seniority parameter.

curl -X POST https://api.richapi.ai/api/v1/lead_search   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "seniority": ["Director", "Vice President"],
    "functions": ["Engineering"],
    "company_size": ["51-200"],
    "page": 1
  }'

RichAPI resolves Director and Vice President to LinkedIn identifiers before the search runs. If a label is not in the catalog, Lead Search returns 400 and the error names the label and the total count of valid options.

CAUTION: Search Reference Data is free, but Lead Search is not. Lead Search charges 10 credits per call plus 0.5 credits per returned profile.

How much does Search Reference Data cost?

Search Reference Data costs 0 credits per call. The call still needs a valid API key, and it counts toward the rate limit of the key.

Which errors can Search Reference Data return?

Status	Meaning	What to do
`401`	The API key is missing, wrong or revoked.	Send a valid key in the `x-api-key` header.
`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. For access, write to [email protected].
`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, write to [email protected].

Lead Search API

Search Reference Data API