Skip to main content
POST
Search Query

Headers

x-api-key
string | null

Body

application/json

Unified search query request — replaces both /start-filter-search and /browse.

simple_filters
Simple Filters · object | null

MongoDB-style filters; the API translates them to DSL.

filters
Filters · object | null

Raw OpenSearch DSL filters.

parsed_query
Parsed Query · object | null

Structured filter set returned by a previous search.

search_id
string | null

Search history ID returned by a previous search. Replays only the query shape; pass exclusions again on this request if they should apply.

query
string | null

Natural-language query. Mutually exclusive with simple_filters / filters / parsed_query / search_id. Supported for people and company search.

query_label
string | null

Display label stored with a structured search. It does not affect the query or results. Oversized labels are truncated.

Maximum string length: 50000
persist_history
boolean
default:true

Set false to skip the canonical search-history write for this search (e.g. a page load that replays a search another surface already recorded). Replays via search_id never write history regardless.

from_offset
integer | null

Company-mode page offset for page-numbered navigation (mirrors OpenSearch from). Offset pages return no cursor and are not persisted to history; page one (offset 0 or omitted) behaves exactly as before. People mode rejects this field.

Required range: 0 <= x <= 10000
cursor
string | null

Opaque pagination cursor returned by a previous response.

mode
enum<string>
default:company

Search mode; inferred from DB when using search_id.

Available options:
people,
company
page_size
integer
default:10

Maximum number of results per page (1-100). Pages may contain fewer rows while more results remain (e.g. with exclusion filtering); rely on has_more/next_cursor, never on page fullness.

Required range: 1 <= x <= 100
max_results
integer | null

Maximum number of results to return across pages. Omit to get the default for your credential: 1000 for API keys, the platform ceiling for signed-in sessions. Values above your ceiling are rejected.

output_shape
enum<string>
default:raw

Return raw OpenSearch rows or canonical workflow LEAD/COMPANY rows. The selected shape is retained by cursor continuations.

Available options:
raw,
workflow
selected_company_names
string[] | null

Platform-only exact company selections. The backend resolves names to company IDs instead of trusting client-supplied OpenSearch IDs. Excess hints are ignored; parsed-query name matching still applies.

Maximum array length: 1000
Required string length: 1 - 500
selected_company_ids
Selected Company Ids · object | null

Platform-only name -> company ID map from autocomplete. Each pair is verified against the company index before use; unverified pairs fall back to name resolution. Disambiguates companies sharing a name. Excess hints are ignored; parsed-query name matching still applies.

exclude_public_ids
string[] | null

People-mode inline identifiers to exclude from results, applied as a post-filter. Accepts LinkedIn public IDs or profile URLs. For company searches, use exclude_entity_ids. Max 1000 for API requests, 50000 for platform requests.

Maximum array length: 50000
exclude_entity_ids
string[] | null

Inline identifiers to exclude from results, applied as a post-filter. People mode: LinkedIn public IDs or profile URLs. Company mode: numeric LinkedIn company IDs, company URLs/slugs, or exact website domains (values that resolve to no or multiple companies are ignored). Max 1000 for API requests, 50000 for platform requests.

Maximum array length: 50000
exclude_list_ids
string[] | null

Saved exclusion-list IDs to apply as a post-filter. Each list's entity type must match the search mode (person lists for people searches, company lists for company searches). Max 5 (10 for organizations with extended exclusion limits).

Maximum array length: 10
expand_structured_location
boolean
default:false

Expand a parsed_query location by radius. Off by default: only the query (NL) branch expanded before, so existing callers keep their result sets. location_expansion_enabled still gates the NL branch.

location_expansion_enabled
boolean
default:true

Expand the location filter to nearby areas via PostGIS radius on the query (NL) branch. For parsed_query, use expand_structured_location.

location_expansion_radius_miles
integer
default:10

Radius (miles) for PostGIS location expansion. Ignored when expansion is disabled.

Required range: 5 <= x <= 200

Response

Successful Response

Response for a completed filter search.

total_results
integer
required

Rows returned so far (cumulative for company pagination).

search_id
string | null

Search history ID returned by a previous search. Replays only the query shape; pass exclusions again on this request if they should apply.

resource_handle_id
string
default:""

Legacy export handle. Empty for company direct-filter mode.

csv_download_url
string | null

Signed URL to download results as CSV.

json_download_url
string | null

Signed URL to download results as JSON.

next_cursor
string | null

Cursor to fetch the next page; null when exhausted.

cursor_expires_in_seconds
integer | null

Seconds until next_cursor expires.

request_duration_ms
integer | null

Server-side request duration in milliseconds.

has_more
boolean
default:false

True when another page is available via next_cursor. Always continue via the cursor; a short or empty page does NOT mean the results are exhausted.

page_size
integer | null

Maximum number of results per page (1-100). Pages may contain fewer rows while more results remain (e.g. with exclusion filtering); rely on has_more/next_cursor, never on page fullness.

page_count
integer | null

Number of results in this response page. May be less than page_size (down to 0) while has_more is true, e.g. when exclusion filtering is active.

page_number
integer | null

1-based page number (company pagination).

total_pages
integer | null

Final total page count; omitted while has_more is true.

max_pages
integer | null

Upper bound on pages based on max_results and page_size.

max_results
integer | null

Effective maximum rows this search may return across pages after applying the request and credential limits.

remaining_results
integer | null

Rows still available under max_results after this page.

download_expires_in_seconds
integer | null

Seconds until the download URLs expire.

total_available
integer | null

Exact total matches across pages; people-mode only. Null when unknown — including when exclusions are applied by post-filter scan rather than in the query, where the match count would overstate the eligible results. Never a capped or approximate figure.

total_available_lower_bound
integer | null

Minimum total matches when OpenSearch caps hit tracking; people-mode only. Null when the total is exact or no reliable lower bound is available.

charge_credits
number | null

Credits charged for this page: 0.1 credit per result returned for billed callers, 0 when this call was not billed.

output_shape
enum<string>
default:raw

Shape of the rows in results. Echoed because cursor continuations reject output_shape on the request.

Available options:
raw,
workflow
exported_count
integer
default:0

Legacy export count; always 0 for company direct-filter mode.

results
Results · object[]

Rows returned for the current page.

parsed_query
Parsed Query · object | null

Structured filter set echoed back; round-trippable into a follow-up request.

natural_language_query
string | null

Original natural-language query echoed verbatim, if any.

company_filter_truncated
Company Filter Truncated · object | null

Present when company filters matched more companies than the resolver expansion cap. "total_matched": positive filters truncated — results cover people at the largest matching employers only. "excluded_total_matched": a not-filter truncated — only the largest matching employers are excluded, so people at smaller excluded companies may still appear.