API Reference

Search people profiles (asynchronous)

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

Submit a search query to be processed asynchronously in the background. This endpoint returns immediately with a task ID and thread ID that can be used to check the status, retrieve results when ready, and paginate through search results.

This is useful for long-running searches that may take several minutes to complete. The search will continue processing in the background while you can use the task ID to monitor progress and retrieve results. The thread ID can be used only to paginate the existing result set through /v2/search or /v2/search/submit.

Initial searches support the same parameters as synchronous /v2/search. For pagination with thread_id, send only limit and optionally offset; search or filter parameters return HTTP 400.

Cost: (number of profiles returned) × (credits for type + insights + high_freshness + reveal_emails + reveal_phones).

Rate limit: 60 actual search requests per user per 60 seconds. /v2/search, /v2/search/submit, and /v2/search/count share this limit. Fully cached thread reloads that do not run a new search use a separate higher limit of 120 cached requests per user per 60 seconds. When the rate limit is exceeded, the API returns HTTP 429 with details about the triggered window, current value, and limit.

Check out official Python client

PRICING

CHECK HOW OUR CREDIT SYSTEM WORKS

KNOWLEDGE BASE

Insights and Research from PEARCH AI team

Body Params
string
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. Provide query, search_requirements, or non-empty custom_filters when thread_id is omitted. A request with only custom_filters uses exact filter retrieval without semantic query ranking. If both query and search_requirements are provided, search_requirements takes precedence for search execution.

search_requirements
array of objects

Structured search requirements. Use this when you already have a list of requirement texts and whether each one is mandatory. Each item supports only requirement text and must_have. If this parameter is provided, it overrides query for search execution.

search_requirements
string

Unique identifier returned by every /v2/search and /v2/search/submit call. Reuse it only for pagination by sending thread_id with limit and optionally offset; omit query and all search/filter parameters. Adding or changing search/filter parameters, including query, search_requirements, custom_filters, docid_blacklist, or docid_whitelist, returns HTTP 400. Running a search with the same thread_id and same limit returns the same results without 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. Cost: 5 credits per candidate
  • "fast" is faster but may have less recall. Cost: 1 credit per candidate
Allowed:
integer
≥ 1
Defaults to 200

Target search time budget in seconds. Defaults to 30 for fast search and 200 for pro search.

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
Allowed:
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). If you are ok with profiles that may be a few months outdated, and want to save ~30 seconds, turn off high_freshness. Refreshed roles include employment_type when the source provides it. Cost: 2 credits per candidate

boolean
Defaults to false

Fill below-limit responses with low confidence results when profile scoring exhausts candidates before reaching the requested limit. These fallback profiles are marked with their score and remain free for search and scoring. When contact reveal is requested, fallback profiles are enriched like regular results and credits_charged includes only contact data actually returned.

custom_filters
object

Custom filters in JSON format for advanced filtering. Omit the parameter 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.

Canonical industry values and common aliases such as health, pharma, and technology are normalized deterministically. Other industry strings are resolved semantically when the selected search mode permits it. Exact-only operations return HTTP 400 when a value cannot be resolved; a requested filter is never silently dropped.
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. 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. 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
uri

An HTTP or HTTPS URL that will receive a POST after the search completes successfully. The JSON request body has exactly the same format as a successful synchronous /v2/search response.

Responses

400

Invalid parameter values. A request that combines thread_id with search or filter parameters is rejected with status: thread_id only supports pagination parameters for this client. Unsupported with thread_id: <field names>.

401

Invalid API key

429

Rate limit exceeded. JSON body contains the triggered window, current value, and limit.

Updated 5 months ago

Did this page help you?
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 5 months ago

Did this page help you?