API Reference

Search people profiles

post
https://api.pearch.ai/v2/search

Run a search query. This accepts a natural language query as query parameter along with additional settings. It returns a list of profiles that match the query and orders them by relevance. The query can be:

  • a simple search query like "software engineer from Ohio"
  • a more complex query like "Find me engineers in California speaking at least basic english working in software industry with experience at FAANG with 2+ years of experience and at least 500 followers and at least BS degree".
  • a full JD-style query that describes the ideal candidate in detail along with job description, responsibilities, requirements, etc.

If the query is already structured (for example JSON, structured text, or a boolean expression), you have two main options:

  • Use the query parameter and pass the structured query as is. This is the simplest approach. Pearch.ai will interpret structured parts and priorities written in free-form text (such as “must have” or “very important”).
  • Use the custom_filters parameter and map some or all structured parts to it. This gives you more control over filtering.

Use parameters to control tradeoffs between speed and quality. Here are some recipes:

  • For highest quality results (30-180 seconds) use pro search with insights and profile scoring enabled: {"query": "<YOUR QUERY HERE>", "type": "pro", "insights": true, "profile_scoring": true}
  • For medium to high quality results use "fast" search (<30s). {"query": "<YOUR QUERY HERE>", "type": "fast", "insights": true, "profile_scoring": true}
  • If you want to implement pagination, pass the thread_id of the previous request to the next request with increased limit.

Results are generally returned in the order of decreasing relevancy. However, you may notice results with out of order score values in some cases especially when requesting large number of results. It should be safe to use stable sorting by score field on the client side in this cases. Note that score field is only calculated and returned when profile_scoring=true.

Check out other parameters below to adjust speed vs quality and additional data that can be returned by the endpoint.

Cost: (number of profiles returned) × (sum of credits for each of type, insights, profile_scoring, high_freshness, reveal_emails, reveal_phones)

Body Params
string
required
Defaults to Software engineer with Python experience from Florida who is interested in science

The human readable search query string. The query can be a simple search query like "software engineer from Ohio" or a more complex query like "Find me engineers in California speaking at least basic english working in software industry with experience at FAANG with 2+ years of experience and at least 500 followers and at least BS degree". Query parameter can handle full job descriptions, but passing specific subset of important requirements normally works better

string

Unique identifier for the thread. This is returned by every /v2/search call and is used to run follow-up queries on the same thread. There are now two alternative ways to call with thread_id: (1) with an increased limit and an empty or omitted query, to request more results (in this case results are appended, and you are only charged for additional, new results) or (2) with a new query to perform a follow-up conversational search; in this case, the new query should only specify additional requirements or changes as in a natural conversation, and the results are replaced instead of appended. Running a search with the same thread_id and same limit as the previous request will return the same results as before without incurring additional charges.

string
enum
Defaults to pro

The type of search to perform.

  • "pro" is slower and more costly, but has higher quality and recall. Profile scoring is included at no extra cost. Cost: 5 credits per candidate
  • "fast" is faster but may have less recall. Cost: 1 credit per candidate
Allowed:
boolean
Defaults to true

Enable detailed insights and analysis for search results. This includes scores for each of query requirements along with quotes from profiles that match subqueries. Check out insights output fields for details. This may be helpful if you share search results with users and want to provide deeper explanations of why profiles are relevant. If your product only needs highly relevant profiles without explanations, use {"insights": false, "profile_scoring": true} Cost: 1 credit per candidate

insights_items
array of strings

When insights is true, optionally restrict which insight fields to include. If omitted, all insight types are included.

insights_items
boolean
Defaults to false

Enable real-time profile updates for fresher data. This downloads the most recent copies of profiles directly from source websites in realtime (e.g. Linkedin). Scraped results are cached for up to 24 hours. If you are ok with profiles that may be a few months outdated, and want to save ~30 seconds, turn off high_freshness. Cost: 2 credits per candidate

boolean
Defaults to true

Enable profile scoring and reranking for better result quality. This filters out less relevant profiles and produces scores for more relevant once. Scores range from 0.0 to 4.0 where higher is better. Included free with pro search. With fast search: 1 credit per candidate

custom_filters
object

Custom filters in JSON format for advanced filtering. Leave empty to use default filtering logic. Format: {"filter_name1": ["value1", "value2"], "filter_name2": ["value3", "value4"], ...}.

Filtering logic: Conditions between different keys are joined with "AND", so all conditions must pass. Within each condition, we always use "OR". For example, {"titles": ["swe", "mle"]} means the profile must have either "swe" OR "mle" as a title. If you specify multiple keys like {"titles": ["swe", "mle"], "locations": ["San Francisco"]}, the profile must match at least one title (swe OR mle) AND be in San Francisco.

Use any string values as is. Pearch.ai internally correctly matches them to profile data. E.g. you may pass {"industries": "health"} to filter for profiles in health industry, this will be correctly mapped to pearch.ai internal healthcare industry. If you want to force no filtering at all (custom_filters or default filters), pass empty object "custom_filters": {}. This will speed up search, increase recall at some relevancy cost.

string
enum

Mode for handling custom filters. 'exact' - only use the passed custom_filters, no LLM-generated filters. 'smart' - merge custom_filters with LLM-generated filters.

Allowed:
boolean
Defaults to false

Be stricter when filtering. If true, titles must match exactly after expanding abbreviations (e.g., "CEO" → "Chief Executive Officer") or translating (e.g., "Ingeniero de software" → "Software Engineer"). If false, fuzzy matching is also used. All other filters are always applied strictly. Enabling strict_filters improves quality but can greatly reduce the number of results. This setting only affects Pearch's implicit filtering. Custom filters are not affected and are always applied strictly.

boolean
Defaults to false

Only return profiles with at least one email address. Profiles will have additional has_email field set to true. Cost: 1 credit per candidate. Deprecated name: require_emails

boolean
Defaults to false

Include email addresses in search results if available. This returns all available emails including personal and work emails. Cost: 6 credits per candidate, only charged if the candidate has at least one email address. Deprecated name: show_emails

boolean
Defaults to false

Only return profiles with at least one phone number. Profiles will have additional has_phone_numbers field set to true. Cost: 1 credit per candidate. Deprecated name: require_phone_numbers

boolean
Defaults to false

Only return profiles with at least one phone number OR at least one email address. Useful when you need contact information but either email or phone is acceptable. Cost: 1 credit per candidate. Deprecated name: require_phones_or_emails

boolean
Defaults to false

Include phone numbers in search results if available. This returns all available phone numbers including personal and work numbers. Cost: 6 credits per candidate, only charged if the candidate has at least one phone number. Deprecated name: show_phone_numbers

integer
1 to 1000
Defaults to 10

The maximum number of search results to return.

integer
≥ 0
Defaults to 0

The number of search results to skip before returning results. Used for pagination in combination with limit.

docid_blacklist
array of strings

List of profile docids to exclude from search results. Use this to filter out profiles that have already been seen or contacted.

docid_blacklist
docid_whitelist
array of strings

List of profile docids to limit search results to. Only profiles with these docids will be returned.

docid_whitelist
boolean
Defaults to false

If true, the search will be processed asynchronously. The endpoint will return immediately with thread ID that can be used to check the status and retrieve results when ready.

Responses

400

Invalid parameter values. JSON body contains the error message.

401

Invalid API key

Updated 11 days ago

Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 11 days ago