openapi: 3.0.4 info: title: Pearch.AI API description: "Pearch.AI API. You need to pass API key as 'Authorization: Bearer ' header." version: "2.0" x-readme: explorer-enabled: true samples-languages: ["shell"] proxy-enabled: false servers: - url: https://api.pearch.ai/ description: Main server paths: /v2/search: post: operationId: post_v2-search summary: Search people profiles tags: - Search description: | - Test this endpoint in the [playground](https://platform.pearch.ai/dashboard?tab=people-search) - Check out official [Python client](https://github.com/Pearch-ai/pearch-client) 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 enabled: `{"query": "", "type": "pro", "insights": true}` - For medium to high quality results use "fast" search (<50s). `{"query": "", "type": "fast", "insights": true}` ### Healthcare source (beta) By default a search covers every data source: LinkedIn profiles and the US National Provider Identifier (NPI) registry of healthcare providers. Use `sources` to choose: `["linkedin"]` returns only LinkedIn profiles, and `["healthcare"]` returns only registry records. The `healthcare` source adds about 6.8 million US healthcare providers from the CMS NPPES registry who have no matching LinkedIn profile: physicians, nurse practitioners, physician assistants, dentists, pharmacists, therapists, and other providers with an NPI. Most registered nurses have no NPI, so few of them are in the registry. A registry record has `docid` `npi:`, the `npi` field, and a null `linkedin_slug`. It carries the provider's specialty as `title` and the practice location. The `healthcare` object lists every specialty reported to the registry with its NUCC taxonomy code, license state, and license number, plus credentials and the date the NPI was issued. It has no work history. With `reveal_phones`, a registry record returns the practice phone listed in the registry when no other provider shares that number, plus any phones and emails our contact providers find for the person. Expect fewer contacts than on LinkedIn profiles. Registry records cost the same as other profiles. When a registry record and a LinkedIn profile in the same results have the same name and state, only the LinkedIn profile is returned. **The healthcare source is in beta.** Coverage, ranking, and contact enrichment for registry records may change, and you may run into bugs. Please report problems to [support@pearch.ai](mailto:support@pearch.ai). ### Pagination Send the previous response's `thread_id` with `limit` and `offset` to page through saved ranked candidates. The API applies page filters before the offset. You can change profile ID lists, liked-profile exclusions, contact filters and reveal options, freshness, insights, response formatting, and the time budget for each page. Omit fixed search parameters such as `query`, `search_requirements`, and `custom_filters`, or repeat their saved values. Empty fixed parameters are treated as omitted. Start a new search without `thread_id` to change the search criteria or retrieve more candidates. ### Scoring and result order Fast and Pro always evaluate candidate relevance. The optional `profile_scoring` parameter is accepted for backward compatibility but ignored: `true`, `false`, and omitting it do not change scoring, filtering, ranking, or whether `score` is returned. Setting it to `false` does not skip scoring or make the search faster. The legacy `type: "superfast"` value is an alias for Fast, with insights off by default; it does not disable scoring. The public `score` is a coarse 1–4 grade, not the full ranking value. Fast's current binary scoring path checks whether candidates pass each mandatory requirement. Candidates that pass all mandatory requirements receive `score: 4`; candidates that fail a mandatory requirement receive `score: 1` and are rejected by that path. A page of only 4s is therefore expected and does not mean all candidates are equally relevant. Optional requirements can affect ranking even when they do not change this grade. Low-confidence fill results and other scoring paths can have different grades. Fast's binary scoring path ranks accepted candidates using a more detailed internal match score. Pro orders results by its final relevance score. Preserve the API's returned order; sorting only by the public `score` does not reproduce the full ranking. Changing `profile_scoring` does not set a minimum-score filter. Per-requirement explanations in `insights` are controlled separately by `insights` and `insights_items`, not by `profile_scoring`. Use `insights: false` when explanations are not needed; candidate scoring and filtering still run. Check out other parameters below to adjust speed vs quality and additional data that can be returned by the endpoint. ### Async search callbacks A new asynchronous search returns HTTP 202 with `task_id`, `uuid` (the same identifier), and `thread_id`. A cached thread result can return HTTP 200 immediately. Use `async=true` on `/v2/search`; `/v2/search/submit` is asynchronous by default. Supply `webhook_url`, for example `https://client.example.com/callback?token=`. Use HTTPS and a dedicated secret generated and verified by your application. The supplied URL, including query parameters, is used for delivery. Callbacks have no HMAC signature or timestamp header; the URL secret does not provide cryptographic payload integrity or timestamp-based replay protection. Each callback includes `uuid`, `task_id` (equal to `uuid`), `thread_id`, and `task_status`. Deduplicate by `task_id`, since separate tasks can share a thread. Every retry sends identical JSON bytes. A successful callback preserves the synchronous result fields, including `status="Done"`, `search_results` and `search_requirements`, and adds `task_id` and `task_status="completed"`. Polling uses the outer `status="completed"`; the nested result's `status="Done"` also means success. Example successful callback (other search-result fields omitted): ```json {"uuid":"","task_id":"","thread_id":"","task_status":"completed","status":"Done","search_results":[],"search_requirements":[{"requirement_index":0,"requirement":"Python developer","must_have":true}]} ``` A failed callback includes `status="failed"`, `task_status="failed"`, `http`, and a public `error` message. Optional `code` and `action` fields are preserved. For example: ```json {"uuid":"","task_id":"","thread_id":"","task_status":"failed","status":"failed","http":500,"error":"Internal server error"} ``` **Compatibility:** older failed callbacks used `status` for the public error message. New failed callbacks use `status="failed"` and put that message in `error`. When accepting both formats, detect errors using `http >= 400`, prefer a nonempty string `error` for the message and fall back to `status`. Allow additional fields and treat newly added identifiers and `task_status` as optional when parsing legacy callbacks. Use a separate error model rather than the successful search-response model. Handled cancellations use `http=499` and `error="Search task was cancelled before completion."`. Requests rejected before a task is accepted return an HTTP error directly and do not produce a completion callback. Delivery makes at most four attempts: one immediately, then retries after waits of 1, 2, and 4 seconds following the previous failure. Every non-2xx response or transport error triggers a retry. Each attempt uses a 10-second connection/read timeout; redirects are not followed. Return any 2xx promptly after safely accepting the event, including duplicates. Failed delivery does not rerun the search or change its completion status. Retries run in the API worker, without a durable delivery queue. A process crash or restart can interrupt delivery, and delivery stops after the fourth failure. For newly started background tasks (HTTP 202), reconcile missing callbacks through `/v2/search/status/{task_id}`. For cached requests (HTTP 200), process the result in that HTTP response: polling the new task ID can return `completed` with `result=null`. If needed, reload the cached page using `thread_id` with the same `limit` and `offset`; this creates a separate API-call identifier. **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. security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: query: type: string description: 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. example: "Software engineer with Python experience from Florida who is interested in science" default: "Software engineer with Python experience from Florida who is interested in science" search_requirements: type: array description: 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. items: $ref: '#/components/schemas/SearchRequirement' example: - search_requirement: "software engineer" must_have: true - search_requirement: "located in Dallas" must_have: true - search_requirement: "has a sense of humor" must_have: false thread_id: type: string description: Identifier from a previous search response. Reuse it to page through saved ranked candidates. Omitted filters and formatting options use their saved settings when available. example: "ec191bf9-99ff-4989-8383-c97c71fafb6d" type: type: string enum: [fast, pro] default: "pro" description: | 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** time_budget: type: integer minimum: 1 description: Target search time budget in seconds. Defaults to 30 for fast search and 300 for pro search. Pro search requires at least 60 seconds. Synonym of timeout; time_budget takes precedence if both are supplied. timeout: type: integer minimum: 1 description: Synonym of time_budget. Target search time in seconds, with the same defaults and validation (30 seconds for fast; 300 seconds and a 60-second minimum for pro). If both parameters are supplied, time_budget takes precedence. insights: type: boolean default: true description: 'Enable detailed insights and analysis for search results, including per-requirement explanations and supporting profile quotes. See the `insights` output fields for details. Use `insights: false` if your product only needs relevant profiles without explanations; scoring, filtering, and ranking still run. This setting is independent of the ignored `profile_scoring` parameter. **Cost: 1 credit per candidate**' profile_scoring: type: boolean description: 'Accepted for backward compatibility and ignored. Fast and Pro always evaluate candidate relevance and return `score`, whether this parameter is true, false, or omitted. It does not control result filtering, order, per-requirement insights, or a minimum-score threshold. Omit it in new integrations.' insights_items: type: array items: type: string enum: [overall_summary, short_quotes, rationale, short_rationale] description: When insights is true, optionally restrict which insight fields to include. If omitted, all insight types are included. high_freshness: type: boolean default: false description: | Enable real-time profile updates for fresher data. This downloads the most recent copies of profiles directly from source websites in real time (for example, LinkedIn). Refreshed roles include `employment_type` when the source provides it. **Cost: 2 credits per candidate**. Enabling freshness on a page of a search originally run with freshness disabled refreshes and rechecks saved candidates. The request can return HTTP 409 if the original filters cannot be rechecked. fill_with_low_confidence_results: type: boolean default: false description: | 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. On a saved thread, set this to false to exclude saved low-confidence results. Setting it to true requires the original search to have enabled it. custom_filters: $ref: '#/components/schemas/CustomFilters' custom_filters_mode: type: string enum: [exact, smart] description: "Mode for handling custom filters. 'exact' - only use the passed custom_filters, no LLM-generated filters. 'smart' - merge custom_filters with LLM-generated filters." strict_filters: type: boolean default: false description: 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. filter_out_no_emails: type: boolean default: false description: | 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`. **Available on Scale with Us. Not included in Free Trial or Self-Service.** This filter can sharply reduce the number of matching candidates. [Contact us](mailto:support@pearch.ai) so we can help configure it for your search. Enabling this filter without access returns HTTP 403 with code `feature_not_enabled`. reveal_emails: type: boolean default: false description: "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`" filter_out_no_phones: type: boolean default: false description: | 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`. **Available on Scale with Us. Not included in Free Trial or Self-Service.** This filter can sharply reduce the number of matching candidates. [Contact us](mailto:support@pearch.ai) so we can help configure it for your search. Enabling this filter without access returns HTTP 403 with code `feature_not_enabled`. filter_out_no_phones_or_emails: type: boolean default: false description: | 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`. **Available on Scale with Us. Not included in Free Trial or Self-Service.** This filter can sharply reduce the number of matching candidates. [Contact us](mailto:support@pearch.ai) so we can help configure it for your search. Enabling this filter without access returns HTTP 403 with code `feature_not_enabled`. reveal_phones: type: boolean default: false description: "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`" limit: type: integer minimum: 1 maximum: 1000 default: 10 description: The maximum number of search results to return. With `thread_id`, omitting it inherits the saved page size. offset: type: integer minimum: 0 default: 0 description: | Number of matching saved results to skip. A positive offset requires `thread_id`, and the effective `offset + limit` must be at most 1000. Plan limits can be lower. When omitted, the offset is zero if you supply `limit`. If you omit both, the saved offset is used, or zero if none was saved. docid_blacklist: type: array items: type: string description: "List of profile docids to exclude from search results. Use this to filter out profiles that have already been seen or contacted. Registry records from the `healthcare` source use `npi:` docids. Plan limit per request: Free Trial 100 profiles; Self-Service 10,000 profiles; Scale with Us 10,000 profiles, with higher limits by agreement. Exceeding the limit returns HTTP 400 with code `docid_blacklist_too_large`." example: ["johndoe", "janedoe"] docid_whitelist: type: array items: type: string description: "List of profile docids to limit search results to. Only profiles with these docids will be returned. Registry records from the `healthcare` source use `npi:` docids. Plan limit per request: Free Trial 100 profiles; Self-Service 10,000 profiles; Scale with Us 10,000 profiles, with higher limits by agreement. Exceeding the limit returns HTTP 400 with code `docid_whitelist_too_large`." example: ["johndoe", "janedoe"] sources: type: array minItems: 1 items: type: string enum: [linkedin, healthcare] description: "Data sources to search; all sources by default. `linkedin` returns LinkedIn profiles. `healthcare` (**beta**) returns records from the US NPI registry of healthcare providers; see Healthcare source (beta) above. When paging with `thread_id`, omit `sources` or repeat its original value." example: ["healthcare"] exclude_liked_profiles: type: boolean description: Exclude profiles previously liked by the authenticated user. short_response: type: boolean description: Omit company details from each profile's work history. omit_fields: type: array items: type: string description: Top-level profile fields to omit. Use `experiences.company_info` to omit company details from work history. example: ["experiences.company_info"] async: type: boolean default: false description: If true, a new background search returns HTTP 202 with task_id, uuid (equal to task_id), and thread_id. Poll using task_id; paginate using thread_id. Cached thread results can return HTTP 200 immediately. webhook_url: type: string format: uri description: Callback URL for success, failure, or handled cancellation of an accepted task. Successful bodies preserve synchronous result fields and add task_id and task_status. See Async search callbacks above for authentication, retries, and error bodies. Requires async=true; HTTPS is recommended. example: "https://client.example.com/pearch/results" responses: "202": description: Search task submitted successfully content: application/json: schema: type: object properties: uuid: type: string description: API-call identifier, equal to task_id. task_id: type: string description: Unique identifier for the submitted search task. example: ec191bf9-99ff-4989-8383-c97c71fafb6d thread_id: type: string description: Thread ID for paging through saved results once available. A request for a thread whose first search is still in progress returns HTTP 202. example: 550e8400-e29b-41d4-a716-446655440000 status: type: string description: Current status of the in-progress task. A newly submitted task starts as `pending`. example: pending message: type: string description: Human-readable message about the task submission. example: Search task submitted successfully "200": description: Search completed and results returned content: application/json: schema: type: object properties: uuid: type: string description: Unique identifier for this API call. Equal to task_id for its asynchronous task; different from thread_id. example: "ec191bf9-99ff-4989-8383-c97c71fafb6d" thread_id: type: string description: Unique identifier for pagination of this result set. example: "ec191bf9-99ff-4989-8383-c97c71fafb6d" query: type: string description: The search query submitted by the user. example: "software engineer from Ohio" user: type: string description: Email address of the user who made the query. example: "dev@dev.co" created_at: type: number format: float description: Timestamp (UNIX epoch) when the query was created. example: 1744446727.123 duration: type: number format: float description: Time taken to complete the search in seconds. example: 2.45 status: type: string description: The current status of the query. One of `pending`, `Done`, `failed`. example: "Done" total_estimate: type: integer description: The estimated total number of search results available. This supersedes the count returned by `/v2/search/count` as the more accurate estimate of total results. See also `total_estimate_is_lower_bound` to understand if the estimate is a lower bound. Search is currently capped at 1000 results regardless of `total_estimate_is_lower_bound` value, future search vesions will significantly increase this limit. example: 1000 total_estimate_is_lower_bound: type: boolean description: Indicates whether the total_estimate is a lower bound. If true, there may be more results available than the estimate suggests. example: false has_more_results: type: boolean description: | On an initial search, `true` can indicate unreturned profiles, candidates awaiting processing, or remaining retrieval work. On a saved page, `true` indicates an additional matching saved candidate or that candidate filtering ran out of time before the API could determine whether more matched. Check `stop_reason` for incomplete page processing. example: true stop_reason: type: string enum: [target_reached, time_budget_exhausted, candidate_pool_exhausted] description: | Why the initial search or saved page stopped. - `target_reached` means the initial search met its result target, or the saved page filled and another matching saved candidate is available. - `time_budget_exhausted` means evaluation ended with work incomplete, for example because of a time or work limit. - `candidate_pool_exhausted` means the initial search stopped due to candidate availability or low yield, or the saved pool has no further matches for the page filters. A full final page can have this reason. example: target_reached credits_remaining: type: integer description: Number of credits remaining for the user. example: 950 search_results: type: array description: List of search result objects matching the query. items: $ref: '#/components/schemas/ScoredProfile' search_requirements: type: array description: The requirements the search ran on, in order. A search made from a natural-language `query` lists the requirements Pearch parsed from it. Search result feedback refers to a requirement by its `requirement_index`; take the numbers from this list rather than from your request, because Pearch may reword a requirement, for example by prefixing `Current role:`. items: $ref: '#/components/schemas/ResponseSearchRequirement' search_requirements_stats: type: array description: How the evaluated candidates matched each requirement, keyed by `requirement_index`. Empty when no candidate was evaluated. items: type: object properties: requirement_index: type: integer example: 0 requirement: type: string example: "5+ years of Python in production" must_have: type: boolean match_stats: type: object description: Share of evaluated candidates that fully, partly or did not match the requirement. properties: full: type: number partial: type: number "no": type: number parameters: type: object description: All input parameters that were sent with the request. additionalProperties: true example: query: "software engineer from Ohio" type: "pro" insights: true limit: 10 "401": description: Invalid API key "400": description: Invalid request parameters. Changing fixed search parameters or enabling low-confidence fill for the first time on a saved thread returns `unsupported_thread_parameter_changes` and lists the unsupported changes. "409": description: The thread has no reusable search state, or its saved filters cannot be rechecked for a requested profile refresh. "429": description: Rate limit exceeded. JSON body contains the triggered window, current value, and limit. /v2/search/count: post: operationId: post_v2-search-count summary: Count profiles tags: - Search description: | **Do not use this endpoint if you only want to estimate the total number of results for a query.** Use `total_estimate` from the `/v2/search` response instead; it supersedes this endpoint's count as the more accurate estimate. Return the number of profiles that match a natural-language `query`, structured `search_requirements`, or `custom_filters`. Queries and search requirements use the same parsing and filtering behavior as a superfast search, but the endpoint does not return profiles. Custom-filter-only requests continue to use the optimized custom-filter count path unless `stats` is true. Set `stats` to true to aggregate canonical profile fields from a sample of up to 1,000 matching profiles. Repeated values are counted at most once per profile. The response reports the full matching count separately from the sampled profile count. Profile statistics add 5 credits to the request cost. The request must include at least one of `query`, `search_requirements`, or `custom_filters`. Filters can be combined with either natural-language input and are ANDed with the derived search filters, matching `/v2/search` behavior. If both `query` and `search_requirements` are provided, `search_requirements` takes precedence. Expect slower response for expected large counts. E.g. for title="manager" from "US" you should expect slower response and approximate=true in the response. For title="meteorologist" from "tokio" expect faster response and approximate=false in the response. **Cost: 2 credits for a custom-filter-only request; 5 credits when `query` or `search_requirements` is present, including requests that also contain custom filters; plus 5 credits when `stats=true`.** **Rate limit: 60 requests per user per 60 seconds.** This endpoint shares the same rate limit as actual `/v2/search` and `/v2/search/submit` executions. 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](https://github.com/Pearch-ai/pearch-client)_ security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: query: type: string description: Natural-language people-search query interpreted into search filters. A request using a query costs 5 credits before optional stats. example: "Software engineers in Germany with Python experience" search_requirements: type: array description: Structured requirements interpreted into search filters. If present, these take precedence over `query`. A request using search requirements costs 5 credits before optional stats. items: $ref: '#/components/schemas/SearchRequirement' custom_filters: $ref: '#/components/schemas/CustomFilters' custom_filters_mode: $ref: '#/components/schemas/CustomFiltersMode' strict_filters: type: boolean docid_blacklist: description: "Plan limit per request: Free Trial 100 profiles; Self-Service 10,000 profiles; Scale with Us 10,000 profiles, with higher limits by agreement. Exceeding the limit returns HTTP 400 with code `docid_blacklist_too_large`." type: array items: type: string docid_whitelist: description: "Plan limit per request: Free Trial 100 profiles; Self-Service 10,000 profiles; Scale with Us 10,000 profiles, with higher limits by agreement. Exceeding the limit returns HTTP 400 with code `docid_whitelist_too_large`." type: array items: type: string exclude_liked_profiles: type: boolean enable_custom_search: type: boolean stats: type: boolean default: false description: Return profile-field statistics calculated from up to 1,000 matching profiles for an additional 5 credits. anyOf: - required: [query] - required: [search_requirements] - required: [custom_filters] responses: "200": description: Count computed successfully content: application/json: schema: type: object properties: count: type: integer description: Estimated number of matching profiles. example: 1234 approximate: type: boolean description: True if not all backing index shards returned a count. example: false uuid: type: string description: Unique identifier for this request. example: "f47ac10b-58cc-4372-a567-0e02b2c3d479" credits_used: type: integer description: Credits charged for this request. example: 0 credits_remaining: type: integer description: Number of credits remaining after this request. example: 950 stats: $ref: '#/components/schemas/SearchCountStats' "401": description: Invalid API key "400": description: Invalid parameter values. JSON body contains the error message. "429": description: Rate limit exceeded. JSON body contains the triggered window, current value, and limit. /v2/company: get: operationId: get_v2-company summary: Enrich company tags: - Enrichment description: | - Test this endpoint in the [playground](https://platform.pearch.ai/dashboard?tab=company-enrichment) Retrieve the complete stored company document using either its LinkedIn company slug or its website domain. The LinkedIn company slug is the part after `https://www.linkedin.com/company/` in a LinkedIn company URL. Provide exactly one of `linkedin_slug` or `domain`. Domains may be passed as a bare domain or a URL; for example, `openai.com`, `www.openai.com`, and `https://www.openai.com/about` are normalized to `openai.com`. This endpoint returns stored company data. It does not run realtime company lookup or contact enrichment. **Cost: 1 credit per company.** Use `GET /v1/user` to retrieve the effective `company_enrichment_cost` for your account. **Rate limit: 180 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. security: - bearerAuth: [] parameters: - name: linkedin_slug in: query required: false schema: type: string minLength: 1 maxLength: 512 description: LinkedIn company slug. This is the part after `https://www.linkedin.com/company/` in the company URL. Provide exactly one of `linkedin_slug` or `domain`. example: "openai" - name: domain in: query required: false schema: type: string minLength: 1 maxLength: 512 description: Company website domain or URL. The value is normalized to a lowercase bare domain without `www.`. Provide exactly one of `domain` or `linkedin_slug`. example: "openai.com" responses: "200": description: Company retrieved successfully content: application/json: schema: type: object required: - company - credits_remaining - credits_used - credits_breakdown properties: company: $ref: '#/components/schemas/CompanyInfo' credits_remaining: type: integer description: Number of credits remaining after this request. example: 999 credits_used: type: integer description: Credits charged for this request. example: 1 credits_breakdown: type: object nullable: true description: Itemized credit charge, or null when no credits were charged. required: - version - total - items properties: version: type: integer enum: [1] example: 1 total: type: integer example: 1 items: type: array items: type: object required: - component - data_point_type - quantity - unit_cost - credits properties: component: type: string example: "company_enrichment" data_point_type: type: string example: "company" quantity: type: number example: 1 unit_cost: type: number example: 1 credits: type: integer example: 1 example: company: name: "OpenAI" domain: "openai.com" website: "https://openai.com" linkedin_url: "https://www.linkedin.com/company/openai" linkedin_slug: "openai" industries: ["Artificial Intelligence (AI)", "Software"] founded_in: 2015 num_employees_range: "1001-5000" credits_remaining: 999 credits_used: 1 credits_breakdown: version: 1 total: 1 items: - component: "company_enrichment" data_point_type: "company" quantity: 1 unit_cost: 1 credits: 1 "400": description: Invalid parameters. Provide exactly one valid `linkedin_slug` or `domain`; unknown parameters are rejected. "401": description: Invalid API key "402": description: Insufficient credits "404": description: Company not found "429": description: Rate limit exceeded. JSON body contains the triggered window, current value, and limit. "502": description: Company enrichment backend error /v2/search_company_leads: post: operationId: post_v2-search-company-leads summary: Search companies and leads tags: - Search description: | - Test this endpoint in the [playground](https://platform.pearch.ai/dashboard?tab=company-search) - Check out official [Python client](https://github.com/Pearch-ai/pearch-client) Endpoint for finding companies and related leads within those companies. Primary use case is for B2B sales, but can also be used for headhunting/executive search. It uses natural language query and returns a list of most relevant companies. Allows for generation of personalized outreach messages for the identified leads. Main difference with [/v2/search](/reference/post_v2-search) is that the search starts with shortlisting relevant companies first, then finding leads who necessarily activaly work at these companies. Some recipes: - When you only need companies, pass only the company query: `{"company_query": "manufacturers of aviation parts"}` - When you need companies and leads, pass both company and lead queries. Note that the lead query shouldn't include company requirements: `{"company_query": "manufacturers of aviation parts", "lead_query": "CTOs and engineering managers"}` - When you want to generate personalized outreach messages for the identified leads, pass the outreach message instruction: `{"company_query": "manufacturers of aviation parts", "lead_query": "CTOs and engineering managers", "outreach_message_instruction": "Suggest buying my (Rob) SaaS recruitment product <300 characters, email style, casual, personal touch"}` - if you don't have good intuition about leads to target, use a very broad lead query like `{..., "lead_query": "people who I can contact regarding partnerships or any c-level (CEO CFO COO CTO CIO CMO CHRO CPO CLO CSO) /founder/director/owner roles"}` **Cost: (number of companies returned) × (5) + (number of leads returned) × (2 + sum of credits for `outreach_message_instruction`, `reveal_emails`, `reveal_phones`, `high_freshness`, plus 1 credit when `filter_out_no_emails` and `filter_out_no_phones` are both enabled)** _Check out official [Python client](https://github.com/Pearch-ai/pearch-client)_ security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: company_query: type: string description: "The search query for finding companies. **Cost: 5 credits per company**" example: "AI startups in San Francisco with 50-200 employees" default: "AI startups in San Francisco with 50-200 employees" thread_id: type: string description: "Unique identifier returned by every `/v2/search_company_leads` call. Reuse it only to paginate the existing result set. Search parameters must not be supplied with `thread_id`; doing so returns HTTP 400. You are charged only for additional results. Running a search with the same `thread_id` and same `limit` returns the same results without additional charges." example: "ec191bf9-99ff-4989-8383-c97c71fafb6d" lead_query: type: string description: 'Optional query for finding specific leads within the companies. Do not include company requirements in the lead query. if you don''t have good intuition about personas to target, use a very broad query like `{..., "lead_query": "people who I can contact regarding partnerships or any c-level (CEO CFO COO CTO CIO CMO CHRO CPO CLO CSO) /founder/director/owner roles"}` **Cost: 2 credits per lead**' example: "CTOs and engineering managers" outreach_message_instruction: type: string description: "Optional instruction for generating personalized outreach messages. This uses LLM to generate a message for each lead. In addition to this instruction the LLM gets full lead's profile and company information as context. **Cost: 3 credits per lead**" example: "Suggest buying my saas recruitment product <300 characters, email style, casual" limit: type: integer minimum: 1 maximum: 1000 default: 50 description: The maximum number of company results to return. leads_limit: type: integer minimum: 1 maximum: 10 default: 3 description: The number of leads to find per company. reveal_emails: type: boolean default: false description: "Include email addresses in lead results if available. **Cost: 3 credits per lead**. Deprecated name: `show_emails`" reveal_phones: type: boolean default: false description: "Include phone numbers in lead results if available. **Cost: 8 credits per lead**. Deprecated name: `show_phone_numbers`" filter_out_no_emails: type: boolean default: false description: "Only return leads with at least one email address. Leads will have an additional `has_email` field set to true. **Combined cost: 1 credit per returned lead when both `filter_out_no_emails` and `filter_out_no_phones` are enabled.** Deprecated name: `require_emails`" filter_out_no_phones: type: boolean default: false description: "Only return leads with at least one phone number. Leads will have an additional `has_phone_numbers` field set to true. **Combined cost: 1 credit per returned lead when both `filter_out_no_emails` and `filter_out_no_phones` are enabled.** Deprecated name: `require_phone_numbers`" high_freshness: type: boolean default: false description: "Enable real-time profile updates for fresher lead 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: 1 credit per lead**" company_high_freshness: type: boolean default: false description: "Enable real-time company data updates for fresher company information. This looks up companies on the internet in realtime and is included in the company search cost." required: - company_query responses: "200": description: Company and lead search completed content: application/json: schema: type: object properties: uuid: type: string description: Unique identifier for this search request. example: "f47ac10b-58cc-4372-a567-0e02b2c3d479" thread_id: type: string description: Thread identifier that can be used to paginate the existing result set. example: "ec191bf9-99ff-4989-8383-c97c71fafb6d" query: type: string description: The complete search query that was processed. example: "Find companies: ```AI startups in San Francisco```\nFind leads in these companies: ```CTOs and engineering managers```" search_results: type: array description: List of company search results with associated leads. items: $ref: '#/components/schemas/CompanyLeadResult' created_at: type: number format: float description: Timestamp (UNIX epoch) when the query was created. example: 1744446727.123 duration: type: number format: float description: Time taken to complete the search in seconds. example: 3.21 user: type: string description: Email address of the user who made the query. example: "dev@dev.co" status: type: string description: The current status of the query. One of `pending`, `Done`, `failed`. example: "Done" total_estimate: type: integer description: The estimated total number of companies available. example: 500 total_estimate_is_lower_bound: type: boolean description: Indicates whether the total_estimate is a lower bound. If true, there may be more companies available than the estimate suggests. example: false credits_remaining: type: integer description: Number of credits remaining for the user. example: 950 parameters: type: object description: All input parameters that were sent with the request. additionalProperties: true example: company_query: "AI startups in San Francisco" lead_query: "CTOs and engineering managers" limit: 50 leads_limit: 3 "400": description: Invalid parameter values. JSON body contains the error message. "401": description: Invalid API key "502": description: Search Backend Error /v1/upsert_jobs: post: operationId: post_v1-upsert-jobs summary: Index jobs tags: - Jobs description: | Accepts a JSON array of job objects, each with `job_id` and `job_description` fields, and adds them to a custom index. Each account can have a single custom index only. This endpoint is used in conjunction with `/v1/find_matching_jobs` endpoint. 1. First you need to upsert jobs with [/v1/upsert_jobs](/reference/post_v1-upsert-jobs) 2. Then you can use [/v1/find_matching_jobs](/reference/post_v1-find-matching-jobs) to find jobs relevant to a profile. **Cost: 1 credit per job** _Check out official [Python client](https://github.com/Pearch-ai/pearch-client)_ security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: jobs: type: array description: "List of job objects to be upserted. **Cost: 1 credit per job**" items: type: object properties: job_id: type: string description: Unique identifier for the job. This is used to match jobs in consecutive calls to /v1/upsert_jobs. example: "job-1234" job_description: type: string description: Free form description of the job. This can be full JD or a shorter description. example: "Machine Learning Engineer for an AI startup with leadership skills" required: - job_id - job_description replace: type: boolean description: | * If `"replace"` is true, all existing jobs will be replaced with the provided list. This means for example that if a job with existing `job_id` "job-1234" already exists, but it is not provided in the request, then it will be removed from the index. * If `"replace"` is false or omitted, jobs are upserted (added or updated only). example: false required: - jobs responses: "200": description: Jobs accepted and processed content: application/json: schema: type: object properties: uuid: type: string description: Unique identifier for the query. example: "ec191bf9-99ff-4989-8383-c97c71fafb6d" status: type: string example: "success" processed_count: type: integer example: 10 "400": description: Invalid job data "401": description: Invalid API key /v1/find_matching_jobs: post: operationId: post_v1-find-matching-jobs summary: Find relevant jobs tags: - Jobs description: | Accepts a profile (arbitrary JSON), and returns a list of jobs relevant to the provided profile. This endpoint is used in conjunction with `/v1/find_matching_jobs` endpoint. 1. First you need to upsert jobs with [/v1/upsert_jobs](/reference/post_v1-upsert-jobs) 2. Then you can use [/v1/find_matching_jobs](/reference/post_v1-find-matching-jobs) to find jobs relevant to a profile. **Cost: 1 credit per found job** _Check out official [Python client](https://github.com/Pearch-ai/pearch-client)_ security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: profile: type: object description: Arbitrary JSON representing the candidate profile. example: id: "123" name: "Jane Doe" work_history: - company: "Pure Storage" position: "Product Manager" start_date: "Mar 2024" end_date: "Present" description: "" education_history: - institution: "The School of Electrical and Computer Engineering of Applied Studies" degree: "Bachelor of Applied Science - BASc" field: "Information Technology" start_year: "2020" end_year: "2023" skills: - "Python" - "Machine Learning" limit: type: integer description: Maximum number of jobs to return (1-100) minimum: 1 maximum: 100 example: 10 responses: "200": description: List of relevant jobs returned content: application/json: schema: type: object properties: uuid: type: string description: Unique identifier for the query. example: "ec191bf9-99ff-4989-8383-c97c71fafb6d" jobs: type: array description: List of job objects relevant to the profile. items: type: object properties: job_id: type: string description: Unique identifier for the job. This is the same as job_id passed to /v1/upsert_jobs. example: "job-1234" job_description: type: string description: Job description. example: "Work on AI models for healthcare." score: type: number format: float description: Relevance score for the match (2.0..5.0). Higher is better. example: 2.92 insights: type: object description: Insights of how well the job matches the profile. properties: query_insights: type: array description: Insights broken down by subqueries. items: type: object properties: match_level: type: string description: 'The degree to which the candidate matches the requirement: Exceeds Expectations,Meets Expectations,Partially Meets,Insufficient Data,Does Not Meet' example: "Exceeds Expectations" priority: type: string description: 'Indicates how important this subquery: Essential, Important, Optional' example: "Essential" short_rationale: type: string description: Concise version of the rationale. example: "3+ years as a software engineer" subquery: type: string description: Specific subquery analyzed for this insight. example: "software engineer" short_quotes: type: array description: Short quotes from the candidate's profile. items: type: string example: "I have 3+ years of experience in software development." "400": description: Invalid input data "401": description: Invalid API key /v1/list_jobs: get: operationId: get_v1-list-jobs summary: List jobs tags: - Jobs description: | Retrieve a list of all jobs currently indexed for the authenticated user. This endpoint returns job metadata including job IDs, descriptions, and creation timestamps. The results are ordered by creation date (most recent first) and can be limited using the `limit` parameter. **Cost: 0 credits** _Check out official [Python client](https://github.com/Pearch-ai/pearch-client)_ security: - bearerAuth: [] parameters: - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 1000 default: 100 description: Maximum number of jobs to return example: 50 responses: "200": description: Jobs list retrieved successfully content: application/json: schema: type: object properties: status: type: string description: Status of the operation example: "success" jobs: type: array description: List of job objects in the user's index items: type: object properties: job_id: type: string description: Unique identifier for the job example: "engineer-001" job_description: type: string description: Job description text example: "Senior Software Engineer for AI startup" created_at: type: string format: date-time description: ISO 8601 timestamp when job was created example: "2024-01-15T10:30:45" total_count: type: integer description: Total number of jobs in the user's index example: 150 returned_count: type: integer description: Number of jobs returned in this response example: 50 "400": description: Invalid parameter values "401": description: Invalid API key /v1/delete_jobs: post: operationId: post_v1-delete-jobs summary: Delete jobs tags: - Jobs description: | Delete specific jobs from the user's job index by providing a list of job IDs. This operation permanently removes the specified jobs from your index. **Cost: 0 credits** _Check out official [Python client](https://github.com/Pearch-ai/pearch-client)_ security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: job_ids: type: array description: List of job IDs to delete items: type: string example: ["job-001", "job-002", "old-position-123"] minItems: 1 required: - job_ids responses: "200": description: Jobs deletion completed content: application/json: schema: type: object properties: status: type: string description: Status of the operation example: "success" deleted_count: type: integer description: Number of jobs actually deleted (may be less than requested if some job IDs don't exist) example: 2 errors: type: array description: List of error messages if any occurred during deletion items: type: string example: [] "400": description: Invalid request data (e.g., empty job_ids list, invalid format) "401": description: Invalid API key /v1/api_call_history: get: operationId: v1-api-call-history summary: Get API call history tags: - Account description: | Retrieve the API call history for the authenticated user. Returns a list of previous API calls including their parameters, results, and metadata. By default, history includes calls made with every API key assigned to the authenticated user. Pass `api_key` to return calls made with one specific key only. This endpoint returns history for the following endpoints: - `/v1/search` - `/v2/search` - `/v2/search/submit` - `/v2/search_company_leads` **Cost: 0 credits** _Check out official [Python client](https://github.com/Pearch-ai/pearch-client)_ security: - bearerAuth: [] parameters: - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 1000 default: 10 description: The maximum number of API call history entries to return. example: 10 - name: paths in: query required: false schema: type: array items: type: string style: form explode: false description: List of API endpoint paths to filter the history by. If provided, only API calls to the specified paths will be returned. example: ["/v2/search", "/v2/search_company_leads"] - name: api_key in: query required: false schema: type: string description: Return only calls made with this exact API key. The key must belong to the authenticated user or their selected organization scope. example: "pk_abc123" responses: "200": description: API call history retrieved successfully content: application/json: schema: type: object properties: api_call_history: type: array description: List of API call history entries ordered by creation date (most recent first). items: $ref: '#/components/schemas/ApiCallHistoryEntry' user: type: string description: Email address of the authenticated user. example: "dev@dev.co" total_credits_used: type: integer description: Total credits used across all returned API calls. example: 150 "400": description: Invalid parameter values. "401": description: Invalid API key "429": description: Rate limit exceeded. JSON body contains the triggered window, current value, and limit. /v2/search/feedback: post: operationId: post_v2-search-feedback summary: Submit search result feedback tags: - Search Feedback description: | Tell Pearch whether a profile returned by a search was right, and why. Pearch uses feedback to measure and improve search quality. **Identify the result** with the `/v2/search` response's `thread_id` and the profile's `search_results[].profile.linkedin_slug`. You can send feedback at any time later: `search_id` (the response's `uuid`) is optional and defaults to the thread's latest completed search. **Three levels; send as much as you have:** 1. *Rating.* `rating` is `up`, `down` or `maybe`. This is all a thumbs button needs. 2. *Profile feedback: why.* `profile_feedback` is a string or a list. A string is free text, for example `"15 years of experience, we need 3-5"`. An object carries a `code`: a preset from `GET /v2/search/feedback/reasons` when one fits, otherwise your own code, up to three codes per profile. Add `unstated: true` when the criterion was not in the search request, such as an employer you exclude. 3. *Requirement feedback: which requirements.* `requirement_feedback` gives a `verdict` for each requirement you checked, by its `requirement_index`. A recruiter who marks the requirements a profile misses sends `does_not_meet` for each of them. **Only requirement feedback refers to requirements.** `requirement_index` is the position of the requirement in the `/v2/search` response's `search_requirements`, where every entry carries its `requirement_index`. Searches made from a natural-language query list the requirements Pearch parsed from it. You never send requirement text. **Each submission replaces the stored feedback** for that `(thread_id, linkedin_slug)`, whoever sends it, so send the rating, profile feedback and requirement feedback together. To send many decisions at once, for example from an ATS, use `POST /v2/search/feedback/batch`. A rejected request returns 400 or 404 with the reason in `status`, for example `'rating': rating must be 'up', 'down' or 'maybe'`. String values are trimmed; `rating`, `author_type` and codes are case-insensitive. Unknown fields are rejected. Older names are still accepted: `chat_thread_id` and `search_call_uuid` for `thread_id` and `search_id`, `reasons` and `verdicts` for `profile_feedback` and `requirement_feedback`, and a top-level `comment` or `reason` as a free-text profile feedback item. security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchFeedbackInput' examples: thumbs: summary: A thumbs-down with one line of text value: thread_id: "ec191bf9-99ff-4989-8383-c97c71fafb6d" linkedin_slug: "jason-tysl" rating: "down" profile_feedback: "Based in Canada" profile_feedback: summary: Codes and text, with the requirement the profile misses value: thread_id: "ec191bf9-99ff-4989-8383-c97c71fafb6d" linkedin_slug: "jason-tysl" rating: "down" profile_feedback: - "Works at our client" - code: "wrong_location" - code: "excluded_employer" unstated: true requirement_feedback: - requirement_index: 1 verdict: "does_not_meet" requirement_feedback: summary: Verdicts on individual requirements value: thread_id: "ec191bf9-99ff-4989-8383-c97c71fafb6d" linkedin_slug: "jason-tysl" rating: "up" author_type: "agent" requirement_feedback: - requirement_index: 0 verdict: "meets" - requirement_index: 2 verdict: "partial" comment: "Go only in side projects" responses: "200": description: Feedback saved content: application/json: schema: allOf: - type: object properties: status: type: string example: "success" - $ref: '#/components/schemas/SearchFeedback' "400": description: "Invalid request: an invalid value, a preset code that does not match the rating, or a requirement index outside the search's requirements. `status` names the field and the rule." "401": description: Invalid API key "403": description: Invalid API key "404": description: No completed search in the thread (or none with this `search_id`), or the profile is not in that search's ranking. `status` says which. get: operationId: get_v2-search-feedback summary: List search result feedback tags: - Search Feedback description: | List every feedback stored for a thread, whoever submitted it, together with the thread's requirements that `requirement_index` refers to. A thread with no feedback and an unknown thread both return an empty `feedback` array. security: - bearerAuth: [] parameters: - in: query name: thread_id required: true schema: type: string format: uuid description: The `/v2/search` response's `thread_id`. example: "ec191bf9-99ff-4989-8383-c97c71fafb6d" responses: "200": description: Feedback stored for the thread content: application/json: schema: type: object properties: status: type: string example: "success" thread_id: type: string format: uuid requirements: type: array description: The thread's current requirements, in index order. items: $ref: '#/components/schemas/FeedbackRequirement' feedback: type: array items: $ref: '#/components/schemas/SearchFeedback' "400": description: Invalid parameter values "401": description: Invalid API key "403": description: Invalid API key delete: operationId: delete_v2-search-feedback summary: Remove search result feedback tags: - Search Feedback description: | Remove the feedback stored for a profile in a thread, whoever submitted it. Removing feedback that does not exist is not an error: `deleted` is `false`. security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - thread_id - linkedin_slug properties: thread_id: type: string format: uuid linkedin_slug: type: string example: thread_id: "ec191bf9-99ff-4989-8383-c97c71fafb6d" linkedin_slug: "jason-tysl" responses: "200": description: Feedback removed content: application/json: schema: type: object properties: status: type: string example: "success" deleted: type: boolean example: true thread_id: type: string format: uuid linkedin_slug: type: string "400": description: Invalid parameter values "401": description: Invalid API key "403": description: Invalid API key /v2/search/feedback/batch: post: operationId: post_v2-search-feedback-batch summary: Submit search result feedback in bulk tags: - Search Feedback description: | Submit up to 100 feedback items in one call, for example when syncing recruiter decisions from an ATS or results reviewed by an agent. Each item has exactly the shape of a `POST /v2/search/feedback` body, items may belong to different threads, and each item succeeds or fails on its own: the response is `200` with one result per item, in the order sent. A failed item carries the status `code` and the `error` message the single endpoint would have returned; retry only items with a 5xx code. security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - items properties: items: type: array minItems: 1 maxItems: 100 items: $ref: '#/components/schemas/SearchFeedbackInput' example: items: - thread_id: "ec191bf9-99ff-4989-8383-c97c71fafb6d" linkedin_slug: "jason-tysl" rating: "down" author_type: "agent" profile_feedback: - code: "experience_above_max" unstated: true - "Max 12 years, has 15" - thread_id: "ec191bf9-99ff-4989-8383-c97c71fafb6d" linkedin_slug: "ada-lovelace" rating: "up" author_type: "agent" responses: "200": description: One result per item content: application/json: schema: type: object properties: status: type: string example: "success" saved: type: integer example: 1 failed: type: integer example: 1 results: type: array items: type: object properties: index: type: integer description: Position of the item in `items`. status: type: string enum: [success, error] code: type: integer description: For failed items, the status code the single endpoint would return. example: 404 error: type: string feedback: $ref: '#/components/schemas/SearchFeedback' "400": description: The body is not an object with 1–100 `items` "401": description: Invalid API key "403": description: Invalid API key /v2/search/feedback/reasons: get: operationId: get_v2-search-feedback-reasons summary: List feedback codes tags: - Search Feedback description: | Preset codes for `profile_feedback[].code` in `POST /v2/search/feedback`. Use a preset when one fits; any other code is accepted as your own. Show `label` to users and `description` as a hint, and offer the codes whose `rating` matches the user's rating (both lists for `maybe`). A preset code with the opposite rating is rejected. `version` changes whenever the lists change; codes are never reused with a different meaning. security: - bearerAuth: [] responses: "200": description: Reason codes content: application/json: schema: type: object properties: status: type: string example: "success" version: type: string example: "2026-10" max_reason_codes: type: integer example: 3 profile_reasons: type: array items: type: object properties: code: type: string example: "too_senior" rating: type: string enum: [up, down] example: "down" label: type: string example: "Too senior" description: type: string example: "More senior or more experienced than the role needs, including founders and executives." requirement_flags: type: array description: Used by Pearch's own review tools; API clients can ignore it. items: type: object properties: code: type: string example: "compound" label: type: string example: "Compound" description: type: string example: "Several independent conditions are bundled into one requirement." example: status: success version: 2026-10 profile_reasons: - code: wrong_role rating: down label: Wrong role or function description: The current role or function is not the one the search asks for. - code: too_senior rating: down label: Too senior description: More senior or more experienced than the role needs, including founders and executives. - code: too_junior rating: down label: Too junior description: Less senior or less experienced than the role needs. - code: missing_skill rating: down label: Missing a required skill or experience description: A specific skill, technology or kind of experience the role needs is missing. - code: wrong_industry rating: down label: Wrong industry or domain description: Experience comes from a different industry or domain. - code: wrong_location rating: down label: Wrong location description: Based outside the wanted area, or the shown location is wrong. - code: not_currently_employed rating: down label: Not employed or independent description: Retired, on a career break, a student, a freelancer or running their own business. - code: short_tenure rating: down label: Just joined or changes jobs often description: Too little time in the current role or a pattern of short tenures. - code: excluded_employer rating: down label: Excluded employer description: Works for the client, used to work for the client, or works at a company that should be excluded. - code: profile_data_issue rating: down label: Profile empty, outdated or wrong description: The profile has too little information, is out of date, or belongs to someone else. - code: already_seen rating: down label: Already seen description: This person was already shown or contacted before. - code: other rating: down label: Other description: Something else; describe it in the comment. - code: strong_match rating: up label: Strong match description: Meets what the search asks for overall. - code: right_role rating: up label: Right role description: The current role or title is the one the search asks for. - code: key_skill rating: up label: Has the key skill or experience description: Shows the skill or experience that matters most for the role. - code: request_too_strict rating: up label: Good even though my request was stricter description: A good candidate although the search asked for more than the role really needs. - code: other rating: up label: Other description: Something else; describe it in the comment. max_reason_codes: 3 requirement_flags: - code: ambiguous label: Ambiguous description: The requirement can be read in more than one way. - code: compound label: Compound description: Several independent conditions are bundled into one requirement. - code: wrong_must_have label: Wrong must-have description: It should be a nice-to-have instead of a must-have, or the other way round. - code: extra label: Not asked for description: The requirement was added although the request did not ask for it. - code: misread label: Misread description: The requirement changes the meaning of what the query asked for. "401": description: Invalid API key "403": description: Invalid API key /v1/profile: get: operationId: get_v1-profile summary: Enrich profile tags: - Enrichment description: | - Test this endpoint in the [playground](https://platform.pearch.ai/dashboard?tab=profile-enrichment) - Check out official [Python client](https://github.com/Pearch-ai/pearch-client) Retrieve an enriched profile using a LinkedIn profile ID, profile UUID, or email address. A LinkedIn profile ID is the part after `https://www.linkedin.com/in/` in the profile URL. Provide a LinkedIn profile ID in `docid`, a profile UUID in either `uuid` or `docid`, or an `email`. If only `email` is provided, the system attempts to resolve it to a LinkedIn profile. A UUID in either field uses masked profile enrichment and includes the full profile and available emails and phones. To retrieve a US healthcare provider from the `healthcare` source (**beta**), pass `docid=npi:`. Registry records are not refreshed in real time, so leave `high_freshness` off for them. Set `fast=true` to prioritize speed when retrieving requested emails and phone numbers. This can reduce response time but may return fewer contacts than standard enrichment. The default is `false`. This option is separate from `/v2/search`'s `type`. **Costs: A UUID in `uuid` or `docid` costs 25 credits for masked enrichment. For a LinkedIn slug in `docid`, costs are additive: `with_profile` costs 1 credit, `high_freshness` costs 2 credits, and `reveal_emails` and `reveal_phones` cost 6 credits each when contact data is found. Looking up a profile by `email` costs 6 credits and is separate from `reveal_emails`.** **Rate limit: 60 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. security: - bearerAuth: [] parameters: - name: docid in: query required: false schema: type: string description: "LinkedIn profile slug (the part after `https://www.linkedin.com/in/`), `npi:` for a healthcare registry record (beta), or a profile UUID. Slugs and `npi:` IDs use additive profile and contact pricing. A UUID uses masked enrichment, as with `uuid`. **Cost: 25 credits for UUID lookup**" example: "hrachik" - name: uuid in: query required: false schema: type: string format: uuid description: "Profile UUID, including one from a masked search result. Uses masked enrichment, as does a UUID in `docid`. **Cost: 25 credits for UUID lookup**" example: "550e8400-e29b-41d4-a716-446655440000" - name: email in: query required: false schema: type: string format: email description: "Email address to look up. If provided without `docid`, the system will resolve the email to a LinkedIn profile. This lookup is separate from `reveal_emails`. **Cost: 6 credits for email lookup**" example: "mz@pearch.ai" - name: high_freshness in: query required: false schema: type: boolean description: "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, turn off high_freshness. Refreshed roles include `employment_type` when the source provides it. **Cost: 2 credits**" example: false - name: fast in: query required: false schema: type: boolean default: false description: "Prioritize speed when retrieving requested emails and phone numbers. Can reduce response time, but may return fewer contacts than standard enrichment. This option is separate from `/v2/search`'s `type`." example: false - name: reveal_emails in: query required: false schema: type: boolean description: "Include email addresses in the profile if available. **Cost: 6 credits, only charged if the profile has at least one email address**. Deprecated name: `show_emails`" example: false - name: reveal_phones in: query required: false schema: type: boolean description: "Include phone numbers in the profile if available. **Cost: 6 credits, only charged if the profile has at least one phone number**. Deprecated name: `show_phone_numbers`" example: false - name: with_profile in: query required: false schema: type: boolean description: "Include full profile data in the response. **Cost: 1 credit**" example: false responses: "200": description: Profile retrieved successfully content: application/json: schema: type: object properties: uuid: type: string description: Unique identifier for the query example: "ec191bf9-99ff-4989-8383-c97c71fafb6d" profile: $ref: '#/components/schemas/Profile' "401": description: Invalid API key "404": description: Profile not found "400": description: Invalid parameter values or missing required parameters. At least one of `docid`, `uuid`, or `email` must be provided. JSON body contains the error message. "429": description: Rate limit exceeded. JSON body contains the triggered window, current value, and limit. /v1/profile/batch: post: operationId: post_v1-profile-batch summary: Enrich profiles in a batch tags: - Enrichment description: | Enrich between 1 and 100 profiles in one request. Each item must provide exactly one `docid`, `uuid`, or `email`; enrichment options apply to the entire batch. Results preserve input order, and `reference_id` can be used to correlate results with client records. A valid batch returns HTTP 200 even when individual profiles are not found. Inspect each result's `http`, `profile`, and `error` fields. Request validation and infrastructure errors remain top-level HTTP errors. A UUID in either `uuid` or `docid` uses masked profile enrichment, matching `GET /v1/profile` with either field. A LinkedIn slug in `docid` uses additive pricing per successful item. **Costs: A UUID in either `uuid` or `docid` costs 25 credits per successful item for masked enrichment. For a LinkedIn slug in `docid`, costs are additive per successful item: `with_profile` costs 1 credit, `high_freshness` costs 2 credits, `reveal_emails` costs 6 credits and `reveal_phones` costs 6 credits when the corresponding contact data is found, and resolving an `email` costs 6 credits.** **Rate limit: 180 batch requests per user per 60 seconds.** A batch counts as one request regardless of its number of items. Batches containing email identifiers also count as one request against the account's daily email-lookup limit. security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProfileBatchRequest' example: profiles: - reference_id: "candidate-1" docid: "vslaykovsky" - reference_id: "candidate-2" email: "person@example.com" with_profile: true reveal_emails: true responses: "200": description: Batch processed. Individual items can still contain 404 outcomes. content: application/json: schema: $ref: '#/components/schemas/ProfileBatchResponse' example: uuid: "ec191bf9-99ff-4989-8383-c97c71fafb6d" results: - reference_id: "candidate-1" input: docid: "vslaykovsky" http: 200 profile: linkedin_slug: "vslaykovsky" first_name: "Vlad" - reference_id: "candidate-2" input: email: "person@example.com" http: 404 error: status: "Could not find LinkedIn profile for the provided email" profiles_succeeded: 1 profiles_failed: 1 credits_remaining: 993 credits_used: 7 credits_breakdown: version: 1 total: 7 items: [] "400": description: Invalid JSON, batch size, identifier, duplicate, or option. "401": description: Invalid API key "402": description: Insufficient credits "429": description: Rate limit exceeded. JSON body contains the triggered window, current value, and limit. "500": description: Batch enrichment failed /v1/user: get: operationId: get_v1-user summary: Get account information tags: - Account description: | Retrieve information about the authenticated user including their account details, remaining credits, and current pricing configuration for different operations. The returned user is resolved from the exact bearer API key supplied to this request. The `user.api_key` field echoes that credential. This endpoint provides: - User account information (email, API key details) - Current credit balance - Pricing details for all available operations with descriptions **Cost: 0 credits** _Check out official [Python client](https://github.com/Pearch-ai/pearch-client)_ security: - bearerAuth: [] responses: "200": description: User information retrieved successfully content: application/json: schema: type: object properties: user: type: object description: User account information properties: api_key: type: string description: User's API key example: "pk_abc123" email: type: string description: User's email address example: "user@example.com" sub_client: type: object description: Sub-client configuration object if applicable additionalProperties: true credits_remaining: type: integer description: Number of credits remaining for the user example: 950 pricing: type: array description: List of pricing information for different operations items: type: object properties: id: type: string description: Identifier for the pricing item example: "pro_search_cost" credits: type: number description: Credit cost for this operation example: 5 description: type: string description: Description of what this pricing item covers example: "Cost per candidate for pro search" "401": description: Invalid API key /v1/api_keys/capabilities: get: operationId: get_v1-api-key-capabilities summary: Get API key management capabilities tags: - Account description: | Return the API key management capabilities available to the authenticated user. **Cost: 0 credits** security: - bearerAuth: [] responses: "200": description: API key management capabilities retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ApiKeyCapabilitiesResponse' "401": description: Invalid API key /v1/organizations/{org_id}/members: get: operationId: get_v1-organization-members summary: List organization members tags: - Account description: | List active members and pending invitations for an organization. Only organization owners can use this endpoint. **Cost: 0 credits** security: - bearerAuth: [] parameters: - name: org_id in: path required: true description: Organization identifier schema: type: string format: uuid responses: "200": description: Organization members retrieved successfully content: application/json: schema: $ref: '#/components/schemas/OrganizationMembersResponse' "401": description: Invalid API key "403": description: Only organization owners can manage members post: operationId: post_v1-organization-member-invite summary: Invite an organization member tags: - Account description: | Invite a member to an organization. Only organization owners can use this endpoint. **Cost: 0 credits** security: - bearerAuth: [] parameters: - name: org_id in: path required: true description: Organization identifier schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InviteOrganizationMemberRequest' responses: "201": description: Organization member invitation created successfully content: application/json: schema: $ref: '#/components/schemas/InviteOrganizationMemberResponse' "400": description: Invalid invitation request "401": description: Invalid API key "403": description: Only organization owners can manage members "409": description: The invited user is already an organization member /v1/organizations/{org_id}/members/{member_id}: patch: operationId: patch_v1-organization-member-role summary: Update an organization member role tags: - Account description: | Update an organization member's role. Only organization owners can use this endpoint. **Cost: 0 credits** security: - bearerAuth: [] parameters: - name: org_id in: path required: true description: Organization identifier schema: type: string format: uuid - name: member_id in: path required: true description: Organization member user identifier schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateOrganizationMemberRoleRequest' responses: "200": description: Organization member role updated successfully content: application/json: schema: $ref: '#/components/schemas/UpdateOrganizationMemberRoleResponse' "400": description: Invalid role update request "401": description: Invalid API key "403": description: Only organization owners can manage members "404": description: Organization member not found "409": description: The last organization owner cannot be demoted delete: operationId: delete_v1-organization-member summary: Remove an organization member tags: - Account description: | Remove a member from an organization. Only organization owners can use this endpoint. **Cost: 0 credits** security: - bearerAuth: [] parameters: - name: org_id in: path required: true description: Organization identifier schema: type: string format: uuid - name: member_id in: path required: true description: Organization member user identifier schema: type: string format: uuid responses: "204": description: Organization member removed successfully "401": description: Invalid API key "403": description: Only organization owners can manage members "404": description: Organization member not found "409": description: The last organization owner cannot be removed and owners cannot remove themselves /v1/organizations/{org_id}/members/invites/{invite_id}: delete: operationId: delete_v1-organization-member-invite summary: Delete a pending organization invitation tags: - Account description: | Delete a pending organization member invitation. Only organization owners can use this endpoint. **Cost: 0 credits** security: - bearerAuth: [] parameters: - name: org_id in: path required: true description: Organization identifier schema: type: string format: uuid - name: invite_id in: path required: true description: Pending invitation identifier schema: type: string format: uuid responses: "204": description: Pending organization invitation deleted successfully "401": description: Invalid API key "403": description: Only organization owners can manage members "404": description: Pending organization invitation not found /v1/organizations/{org_id}/api_keys: get: operationId: get_v1-organization-api-keys summary: List organization member API keys tags: - Account description: | List organization members and the masked metadata for their API keys. Only organization owners can use this endpoint. **Cost: 0 credits** security: - bearerAuth: [] parameters: - name: org_id in: path required: true description: Organization identifier schema: type: string format: uuid responses: "200": description: Organization member API keys retrieved successfully content: application/json: schema: $ref: '#/components/schemas/OrganizationApiKeysResponse' "401": description: Invalid API key "403": description: Only organization owners can manage member API keys "404": description: Owner-managed member API keys are unavailable /v1/organizations/{org_id}/members/{member_id}/api_keys: post: operationId: post_v1-organization-member-api-key summary: Create an organization member API key tags: - Account description: | Create an API key for an organization member. The secret is returned only in this response. Only organization owners can use this endpoint. **Cost: 0 credits** security: - bearerAuth: [] parameters: - name: org_id in: path required: true description: Organization identifier schema: type: string format: uuid - name: member_id in: path required: true description: Organization member user identifier schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateApiKeyRequest' responses: "201": description: Organization member API key created successfully content: application/json: schema: $ref: '#/components/schemas/CreateOrganizationApiKeyResponse' "400": description: Invalid API key name "401": description: Invalid API key "403": description: Only organization owners can manage member API keys "404": description: Organization member not found or owner-managed member API keys are unavailable /v1/organizations/{org_id}/api_keys/{key_id}: delete: operationId: delete_v1-organization-api-key summary: Delete an organization member API key tags: - Account description: | Revoke an organization member API key. Only organization owners can use this endpoint. **Cost: 0 credits** security: - bearerAuth: [] parameters: - name: org_id in: path required: true description: Organization identifier schema: type: string format: uuid - name: key_id in: path required: true description: API key identifier schema: type: string format: uuid responses: "204": description: Organization member API key deleted successfully "401": description: Invalid API key "403": description: Only organization owners can manage member API keys "404": description: API key not found or owner-managed member API keys are unavailable components: schemas: ResponseSearchRequirement: type: object properties: requirement_index: type: integer minimum: 0 description: Position of the requirement; feedback refers to it by this number. example: 0 requirement: type: string example: "5+ years of Python in production" must_have: type: boolean example: true FeedbackRequirement: type: object additionalProperties: false required: [requirement] properties: requirement: type: string maxLength: 2000 example: "5+ years of Python in production" must_have: type: boolean default: false SearchProfileFeedbackItem: description: Free text as a plain string, or an object with a code. oneOf: - type: string maxLength: 500 example: "15 years of experience, we need 3-5" - $ref: '#/components/schemas/SearchProfileFeedbackCode' SearchProfileFeedbackCode: type: object additionalProperties: false required: [code] properties: code: type: string maxLength: 64 description: A preset code from `GET /v2/search/feedback/reasons` when one fits, otherwise your own code. A preset code must match the feedback's rating (either list for `maybe`); your own codes are stored as sent, lowercased. example: "too_senior" unstated: type: boolean default: false description: "`true` when the criterion was not in the search request." SearchRequirementFeedback: type: object additionalProperties: false required: [requirement_index, verdict] properties: requirement_index: type: integer minimum: 0 description: The requirement's `requirement_index` in the `/v2/search` response's `search_requirements`. verdict: type: string enum: [meets, partial, does_not_meet, cannot_tell] comment: type: string maxLength: 500 description: Free text about this verdict. search_verdict: type: string enum: [meets, partial, does_not_meet, cannot_tell] nullable: true readOnly: true description: The search's own verdict on the requirement for this profile, filled in by Pearch from the result's insights. SearchFeedbackInput: type: object additionalProperties: false required: - thread_id - linkedin_slug - rating properties: thread_id: type: string format: uuid description: The `thread_id` returned by `/v2/search`. `chat_thread_id` is accepted as its older name. linkedin_slug: type: string description: The rated profile's `search_results[].profile.linkedin_slug` value. search_id: type: string format: uuid nullable: true description: The `uuid` returned by `/v2/search`. Optional; defaults to the thread's latest completed search. `search_call_uuid` is accepted as its older name. rating: type: string enum: [up, down, maybe] description: "`maybe` marks a borderline profile." profile_feedback: description: Why the profile fits or not, as one string or a list; up to three items with a code. `reasons` is accepted as its older name. oneOf: - type: string maxLength: 500 - type: array maxItems: 10 items: $ref: '#/components/schemas/SearchProfileFeedbackItem' requirement_feedback: type: array maxItems: 50 description: Verdicts on the requirements you checked; each requirement at most once. `verdicts` is accepted as its older name. items: $ref: '#/components/schemas/SearchRequirementFeedback' author_type: type: string enum: [person, agent, mixed] default: person description: Who produced the rating; `mixed` for a person confirming an agent's rating. SearchFeedback: type: object properties: id: type: integer example: 123 thread_id: type: string format: uuid search_id: type: string format: uuid nullable: true linkedin_slug: type: string example: "jason-tysl" rating: type: string enum: [up, down, maybe] profile_feedback: type: array description: Free text first, as one string, then the items with a code. items: $ref: '#/components/schemas/SearchProfileFeedbackItem' requirement_feedback: type: array items: $ref: '#/components/schemas/SearchRequirementFeedback' requirements: type: array nullable: true description: The search's requirements that `requirement_index` refers to. items: $ref: '#/components/schemas/FeedbackRequirement' author_type: type: string enum: [person, agent, mixed] created_by: type: string nullable: true description: Author of the latest submission. created_at: type: string format: date-time nullable: true updated_at: type: string format: date-time nullable: true ProfileBatchItem: type: object additionalProperties: false description: One profile identifier and an optional client reference. Provide exactly one of `docid`, `uuid`, or `email`. oneOf: - required: [docid] - required: [uuid] - required: [email] properties: reference_id: type: string minLength: 1 maxLength: 512 description: Optional client-defined value copied to the corresponding result. example: "candidate-123" docid: type: string minLength: 1 maxLength: 512 description: "LinkedIn profile slug (the part after `https://www.linkedin.com/in/`), `npi:` for a healthcare registry record (beta), or a profile UUID. Slugs and `npi:` IDs use additive profile and contact pricing; UUIDs use masked enrichment. **Cost: 25 credits for UUID lookup**" example: "vslaykovsky" uuid: type: string format: uuid description: "Profile UUID, including one from a masked search result. Uses masked enrichment, as does a UUID in `docid`. **Cost: 25 credits for UUID lookup**" example: "550e8400-e29b-41d4-a716-446655440000" email: type: string format: email maxLength: 512 description: Email address to resolve to a LinkedIn profile. This lookup is separate from `reveal_emails`. example: "person@example.com" ProfileBatchRequest: type: object additionalProperties: false required: - profiles properties: profiles: type: array minItems: 1 maxItems: 100 description: Profiles to enrich. Results preserve this input order. Duplicate identifiers are rejected. items: $ref: '#/components/schemas/ProfileBatchItem' high_freshness: type: boolean default: false description: "Enable realtime profile updates for every non-UUID item. Refreshed roles include `employment_type` when the source provides it. **Cost: 2 credits per successfully returned profile**" reveal_emails: type: boolean default: false description: "Include email addresses when available. **Cost: 6 credits per profile for which email data is found**. Deprecated name: `show_emails`" reveal_phones: type: boolean default: false description: "Include phone numbers when available. **Cost: 6 credits per profile for which phone data is found**. Deprecated name: `show_phone_numbers`" with_profile: type: boolean default: false description: "Include full stored profile data. **Cost: 1 credit per successfully returned profile**" short_response: type: boolean default: false description: Return the compact profile representation. omit_fields: type: array description: Profile fields to remove from every successful result. items: type: string show_emails: type: boolean deprecated: true description: Deprecated alias for `reveal_emails`. show_phone_numbers: type: boolean deprecated: true description: Deprecated alias for `reveal_phones`. ProfileBatchItemResult: type: object required: - input - http properties: reference_id: type: string description: Client-defined reference copied from the request item. input: type: object additionalProperties: type: string description: Identifier supplied for this item. example: {"docid": "vslaykovsky"} http: type: integer description: Item-level outcome code. Currently 200 or 404. enum: [200, 404] profile: $ref: '#/components/schemas/Profile' error: type: object required: - status properties: status: type: string example: "Profile not found" ProfileBatchResponse: type: object required: - uuid - results - profiles_succeeded - profiles_failed - credits_remaining - credits_used - credits_breakdown properties: uuid: type: string format: uuid description: Unique identifier for the batch API call. results: type: array description: Item results in the same order as the request. items: $ref: '#/components/schemas/ProfileBatchItemResult' profiles_succeeded: type: integer minimum: 0 profiles_failed: type: integer minimum: 0 credits_remaining: type: integer description: Credits remaining after the batch charge. credits_used: type: integer description: Total credits charged for successful items. credits_breakdown: type: object nullable: true description: Aggregate itemized credit charge, or null when no credits were charged. additionalProperties: true OrganizationRole: type: string enum: - owner - admin - billing - member - viewer description: Organization member role OrganizationMember: type: object required: - user_id - email - name - role - invited_by - created_at properties: user_id: type: string format: uuid description: Member user identifier email: type: string format: email description: Member email address name: type: string nullable: true description: Member display name role: $ref: '#/components/schemas/OrganizationRole' invited_by: type: string format: uuid nullable: true description: User who invited the member created_at: type: string format: date-time description: Membership creation timestamp OrganizationPendingInvite: type: object required: - id - email - role - expires_at - invited_by properties: id: type: string format: uuid description: Invitation identifier email: type: string format: email description: Invited email address role: $ref: '#/components/schemas/OrganizationRole' expires_at: type: string format: date-time description: Invitation expiration timestamp invited_by: type: string format: uuid nullable: true description: User who created the invitation OrganizationMembersResponse: type: object required: - organization_id - members - pending_invites properties: organization_id: type: string format: uuid description: Organization identifier members: type: array items: $ref: '#/components/schemas/OrganizationMember' pending_invites: type: array items: $ref: '#/components/schemas/OrganizationPendingInvite' InviteOrganizationMemberRequest: type: object additionalProperties: false required: - email properties: email: type: string format: email description: Email address to invite role: allOf: - $ref: '#/components/schemas/OrganizationRole' default: member expires_in_days: type: integer minimum: 1 maximum: 30 default: 7 description: Number of days before the invitation expires InviteOrganizationMemberResponse: type: object required: - invite_id - email - role - expires_at - invite_token - invite_url properties: invite_id: type: string format: uuid description: Invitation identifier email: type: string format: email description: Invited email address role: $ref: '#/components/schemas/OrganizationRole' expires_at: type: string format: date-time description: Invitation expiration timestamp invite_token: type: string description: Invitation token invite_url: type: string format: uri description: URL used to accept the invitation UpdateOrganizationMemberRoleRequest: type: object additionalProperties: false required: - role properties: role: $ref: '#/components/schemas/OrganizationRole' UpdateOrganizationMemberRoleResponse: type: object required: - organization_id - user_id - updated - previous_role - role properties: organization_id: type: string format: uuid description: Organization identifier user_id: type: string format: uuid description: Member user identifier updated: type: boolean description: Whether the member role was updated previous_role: $ref: '#/components/schemas/OrganizationRole' role: $ref: '#/components/schemas/OrganizationRole' ApiKeyMetadata: type: object description: Masked API key metadata required: - id - name - preview - created_at - last_used_at - revoked_at properties: id: type: string format: uuid description: API key identifier name: type: string description: API key name preview: type: string description: Masked API key preview example: "pk_abc…1234" created_at: type: string format: date-time description: API key creation timestamp last_used_at: type: string format: date-time nullable: true description: Most recent API key usage timestamp revoked_at: type: string format: date-time nullable: true description: API key revocation timestamp OrganizationMemberApiKeys: type: object description: Organization member and their API keys required: - user_id - email - role - api_keys properties: user_id: type: string format: uuid description: Member user identifier email: type: string format: email nullable: true description: Member email address role: type: string description: Member organization role api_keys: type: array description: Masked API key metadata items: $ref: '#/components/schemas/ApiKeyMetadata' ApiKeyCapabilitiesResponse: type: object required: - owner_managed_member_keys - version properties: owner_managed_member_keys: type: boolean description: Whether owner-managed member API keys are enabled version: type: integer description: API key management contract version example: 2 OrganizationApiKeysResponse: type: object required: - organization_id - members properties: organization_id: type: string format: uuid description: Organization identifier members: type: array description: Organization members and their API keys items: $ref: '#/components/schemas/OrganizationMemberApiKeys' CreateApiKeyRequest: type: object additionalProperties: false required: - name properties: name: type: string minLength: 1 maxLength: 100 description: API key name CreateOrganizationApiKeyResponse: type: object required: - api_key - id - name - preview - created_at - member_user_id - organization_id properties: api_key: type: string description: API key secret returned only once id: type: string format: uuid description: API key identifier name: type: string description: API key name preview: type: string description: Masked API key preview example: "pk_abc…1234" created_at: type: string format: date-time description: API key creation timestamp member_user_id: type: string format: uuid description: Member user identifier organization_id: type: string format: uuid description: Organization identifier SearchCountStats: type: object required: - matched_profiles - sample_limit - top_values_limit - sample_size - truncated - fields properties: matched_profiles: type: integer description: Full number of profiles matching the count filter. sample_limit: type: integer example: 1000 top_values_limit: type: integer example: 10 sample_size: type: integer description: Number of matching profiles used to compute field statistics. truncated: type: boolean description: True when more profiles matched than were included in the sample. fields: type: object description: | Statistics keyed by profile-field name. Includes locations, countries, regions, canonical skills and titles, companies and industries, education, languages, age and experience distributions, gender, LinkedIn audience size, decision-maker status, contact availability, current-company attributes, record counts, top-university status, and last-activity recency. Raw title, raw skill, and raw company counterparts are excluded when canonical fields are available. Open-to-work, profile-created, certifications, programming languages, and profile-achievement fields are excluded. additionalProperties: $ref: '#/components/schemas/SearchCountFieldStats' SearchCountFieldStats: type: object required: - profiles_total - coverage_pct properties: profiles_total: type: integer profiles_non_empty: type: integer profiles_empty: type: integer coverage_pct: type: number values_total: type: integer unique_values: type: integer top_values: type: array items: type: object required: - value - profile_count - percentage properties: value: type: string profile_count: type: integer percentage: type: number min: type: number nullable: true max: type: number nullable: true mean: type: number nullable: true median: type: number nullable: true buckets: type: array items: type: object required: - label - profile_count - percentage properties: label: type: string profile_count: type: integer percentage: type: number counts: type: object additionalProperties: type: integer SearchRequirement: type: object description: A structured search requirement with text and whether it is mandatory. additionalProperties: false required: - search_requirement properties: search_requirement: type: string description: Requirement text to match against candidate profiles. example: "software engineer" must_have: type: boolean default: false description: "Whether this requirement is mandatory. If false, the requirement is treated as a nice-to-have. Use `must_have` sparingly: too many mandatory requirements can make the search overly restrictive and result in fewer returned profiles." example: true CustomFiltersMode: type: string enum: [exact, smart] description: "Mode for handling custom filters. 'exact' uses only the supplied custom filters; 'smart' merges them with LLM-generated filters." LocationCoordinateFilter: type: object additionalProperties: false required: - lat - lng - radius_miles properties: lat: type: number format: double minimum: -90 maximum: 90 description: Latitude of the search-radius center. lng: type: number format: double minimum: -180 maximum: 180 description: Longitude of the search-radius center. radius_miles: type: number format: double minimum: 0 exclusiveMinimum: true maximum: 500 description: Search radius in miles, greater than 0 and at most 500. Industry: type: string description: Canonical industry name for custom search filters enum: - "Archiving Service" - "Call Center" - "Collection Agency" - "College Recruiting" - "Courier Service" - "Debt Collections" - "Delivery" - "Document Preparation" - "Employee Benefits" - "Extermination Service" - "Facilities Support Services" - "Housekeeping Service" - "Human Resources" - "Knowledge Management" - "Office Administration" - "Packaging Services" - "Physical Security" - "Project Management" - "Staffing Agency" - "Trade Shows" - "Virtual Workforce" - "Ad Exchange" - "Ad Network" - "Ad Retargeting" - "Ad Server" - "Ad Targeting" - "Advertising" - "Advertising Platforms" - "Affiliate Marketing" - "Local Advertising" - "Mobile Advertising" - "Native Advertising" - "Outdoor Advertising" - "SEM" - "Social Media Advertising" - "Video Advertising" - "Agriculture" - "AgTech" - "Animal Feed" - "Aquaculture" - "Equestrian" - "Farming" - "Forestry" - "Horticulture" - "Hydroponics" - "Livestock" - "App Discovery" - "Apps" - "Consumer Applications" - "Enterprise Applications" - "Mobile Apps" - "Reading Apps" - "Web Apps" - "Artificial Intelligence (AI)" - "Generative AI" - "Intelligent Systems" - "Machine Learning" - "Natural Language Processing" - "Predictive Analytics" - "Robotic Process Automation (RPA)" - "Bioinformatics" - "Biometrics" - "Biopharma" - "Biotechnology" - "Genetics" - "Life Science" - "Neuroscience" - "Quantified Self" - "Bitcoin" - "Blockchain" - "Cryptocurrency" - "Decentralized Finance (DeFi)" - "Ethereum" - "Non-Fungible Token (NFT)" - "Smart Contracts" - "Web3" - "Apparel" - "Fashion" - "Laundry and Dry-cleaning" - "Lingerie" - "Shoes" - "Auctions" - "Classifieds" - "Collectibles" - "Consumer Reviews" - "Coupons" - "E-Commerce" - "E-Commerce Platforms" - "Flash Sale" - "Gift" - "Gift Card" - "Gift Exchange" - "Gift Registry" - "Group Buying" - "Local Shopping" - "Made to Order" - "Marketplace" - "Office Supplies" - "Online Auctions" - "Personalization" - "Point of Sale" - "Price Comparison" - "Rental" - "Retail" - "Retail Technology" - "Secondhand Goods" - "Shopping" - "Shopping Mall" - "Social Shopping" - "Sporting Goods" - "Vending and Concessions" - "Virtual Goods" - "Wholesale" - "Adult" - "Baby" - "Cannabis" - "Children" - "Communities" - "Dating" - "Elderly" - "Family" - "Funerals" - "Humanitarian" - "Leisure" - "LGBT" - "Lifestyle" - "Men's" - "Online Forums" - "Parenting" - "Pet" - "Private Social Networking" - "Professional Networking" - "Q&A" - "Religion" - "Retirement" - "Sex Industry" - "Sex Tech" - "Social" - "Social Entrepreneurship" - "Teenagers" - "Virtual World" - "Wedding" - "Women's" - "Young Adults" - "Computer" - "Consumer Electronics" - "Drones" - "Electronics" - "Google Glass" - "Mobile Devices" - "Nintendo" - "Playstation" - "Roku" - "Smart Home" - "Wearables" - "Windows Phone" - "Xbox" - "Beauty" - "Card and Board Games" - "Cleaning Products" - "Comics" - "Consumer Goods" - "Cosmetics" - "DIY" - "Eyewear" - "Fast-Moving Consumer Goods" - "Flowers" - "Furniture" - "Green Consumer Goods" - "Handmade" - "Home Appliances" - "Jewelry" - "Personal Care and Hygiene" - "Tobacco" - "Toys" - "Blogging Platforms" - "Books" - "Content Delivery Network" - "Content Discovery" - "Content Syndication" - "Copywriting" - "Creative Agency" - "DRM" - "EBooks" - "Journalism" - "News" - "Photo Editing" - "Photo Sharing" - "Photography" - "Printing" - "Publishing" - "Social Bookmarking" - "Video Editing" - "Video Streaming" - "A/B Testing" - "Analytics" - "Application Performance Management" - "Big Data" - "Business Intelligence" - "Consumer Research" - "Data Collection and Labeling" - "Data Governance" - "Data Integration" - "Data Management" - "Data Mining" - "Data Visualization" - "Database" - "Facial Recognition" - "Geospatial" - "Image Recognition" - "Location Based Services" - "Market Research" - "Product Research" - "Speech Recognition" - "Test and Measurement" - "Text Analytics" - "Usability Testing" - "CAD" - "Graphic Design" - "Human Computer Interaction" - "Industrial Design" - "Interior Design" - "Mechanical Design" - "Product Design" - "UX Design" - "Web Design" - "Alumni" - "Charter Schools" - "Continuing Education" - "Corporate Training" - "E-Learning" - "EdTech" - "Education" - "Edutainment" - "Higher Education" - "Language Learning" - "MOOC" - "Music Education" - "Personal Development" - "Primary Education" - "Secondary Education" - "Skill Assessment" - "Special Education" - "STEM Education" - "Textbook" - "Training" - "Tutoring" - "Vocational Education" - "Battery" - "Biofuel" - "Biomass Energy" - "Clean Energy" - "Electrical Distribution" - "Energy" - "Energy Efficiency" - "Energy Management" - "Energy Storage" - "Fossil Fuels" - "Fuel" - "Fuel Cell" - "Geothermal Energy" - "Hydroelectric" - "Oil and Gas" - "Power Grid" - "Renewable Energy" - "Solar" - "Wind Energy" - "Concerts" - "Event Management" - "Event Promotion" - "Events" - "Nightclubs" - "Nightlife" - "Reservations" - "Ticketing" - "Accounting" - "Angel Investment" - "Asset Management" - "Auto Insurance" - "Banking" - "Bookkeeping and Payroll" - "Commercial Insurance" - "Commercial Lending" - "Consumer Lending" - "Credit" - "Credit Bureau" - "Credit Cards" - "Crowdfunding" - "Debit Cards" - "Finance" - "Financial Exchanges" - "Financial Services" - "FinTech" - "Foreign Exchange Trading" - "Fraud Detection" - "Funding Platform" - "Health Insurance" - "Hedge Funds" - "Impact Investing" - "Incubators" - "Insurance" - "InsurTech" - "Leasing" - "Lending" - "Life Insurance" - "Micro Lending" - "Mobile Payments" - "Payments" - "Personal Finance" - "Prediction Markets" - "Prepaid Cards" - "Property Insurance" - "Real Estate Investment" - "Stock Exchanges" - "Tax Consulting" - "Tax Preparation" - "Trading Platform" - "Transaction Processing" - "Venture Capital" - "Virtual Currency" - "Wealth Management" - "Alternative Protein" - "Bakery" - "Brewing" - "Catering" - "Coffee" - "Confectionery" - "Cooking" - "Craft Beer" - "Dairy" - "Dietary Supplements" - "Distillery" - "Farmers Market" - "Food and Beverage" - "Food Delivery" - "Food Processing" - "Food Trucks" - "Fruit" - "Grocery" - "Herbs and Spices" - "Meat and Poultry" - "Nutrition" - "Organic Food" - "Plant-Based Foods" - "Recipes" - "Restaurants" - "Seafood" - "Snack Food" - "Tea" - "Wine And Spirits" - "Winery" - "Casual Games" - "Console Games" - "Contests" - "Fantasy Sports" - "Gambling" - "Gamification" - "Gaming" - "MMO Games" - "Online Games" - "PC Games" - "Serious Games" - "Video Games" - "CivicTech" - "Government" - "GovTech" - "Law Enforcement" - "Military" - "National Security" - "Politics" - "Public Safety" - "Social Assistance" - "3D Technology" - "Application Specific Integrated Circuit (ASIC)" - "Audio/Visual Equipment" - "Augmented Reality" - "Cloud Infrastructure" - "Communication Hardware" - "Communications Infrastructure" - "Computer Vision" - "Data Center" - "Data Center Automation" - "Data Storage" - "Drone Management" - "DSP" - "Electronic Design Automation (EDA)" - "Embedded Systems" - "Field-Programmable Gate Array (FPGA)" - "Flash Storage" - "GPS" - "GPU" - "Hardware" - "Laser" - "Lighting" - "Network Hardware" - "NFC" - "Optical Communication" - "Private Cloud" - "Remote Sensing" - "RFID" - "RISC" - "Robotics" - "Satellite Communication" - "Semiconductor" - "Sensor" - "Telecommunications" - "Video Conferencing" - "Virtual Reality" - "Virtualization" - "Wireless" - "Addiction Treatment" - "Alternative Medicine" - "Assisted Living" - "Assistive Technology" - "Child Care" - "Clinical Trials" - "Cosmetic Surgery" - "Dental" - "Diabetes" - "Elder Care" - "Electronic Health Record (EHR)" - "Emergency Medicine" - "Fertility" - "First Aid" - "Health Care" - "Health Diagnostics" - "Home Health Care" - "Hospital" - "Medical" - "Medical Device" - "Mental Health" - "mHealth" - "Nursing and Residential Care" - "Nutraceutical" - "Oncology" - "Outpatient Care" - "Personal Health" - "Pharmaceutical" - "Precision Medicine" - "Primary and Urgent Care" - "Psychology" - "Rehabilitation" - "Telehealth" - "Therapeutics" - "Veterinary" - "Wellness" - "Business Information Systems" - "Cloud Data Services" - "Cloud Management" - "Cloud Security" - "CMS" - "Contact Management" - "CRM" - "Cyber Security" - "DevOps" - "Document Management" - "E-Signature" - "Email" - "Identity Management" - "Information and Communications Technology (ICT)" - "Information Services" - "Information Technology" - "Intrusion Detection" - "IT Infrastructure" - "IT Management" - "Management Information Systems" - "Messaging" - "Network Security" - "Penetration Testing" - "Reputation" - "Sales Automation" - "Scheduling" - "Social CRM" - "Spam Filtering" - "Technical Support" - "Unified Communications" - "Video Chat" - "VoIP" - "Cloud Computing" - "Cloud Storage" - "Darknet" - "Domain Registrar" - "Ediscovery" - "Internet" - "Internet of Things" - "ISP" - "Music Streaming" - "Online Portals" - "Product Search" - "Search Engine" - "Semantic Search" - "Semantic Web" - "SEO" - "SMS" - "Social Media" - "Social Media Management" - "Social Network" - "Vertical Search" - "Visual Search" - "Web Browsers" - "Web Hosting" - "3D Printing" - "Advanced Materials" - "Foundries" - "Industrial" - "Industrial Automation" - "Industrial Engineering" - "Industrial Manufacturing" - "Machinery Manufacturing" - "Manufacturing" - "Paper Manufacturing" - "Plastics and Rubber Manufacturing" - "Textiles" - "Wood Processing" - "Advice" - "Animation" - "Art" - "Audio" - "Audiobooks" - "Broadcasting" - "Celebrity" - "Content" - "Content Creators" - "Digital Entertainment" - "Digital Media" - "Film" - "Film Distribution" - "Film Production" - "Guides" - "In-Flight Entertainment" - "Independent Music" - "Internet Radio" - "Media and Entertainment" - "Metaverse" - "Motion Capture" - "Music" - "Music Label" - "Music Venues" - "Musical Instruments" - "Performing Arts" - "Podcast" - "Social News" - "Theatre" - "TV" - "TV Production" - "Video" - "Video on Demand" - "Meeting Software" - "Wired Telecommunications" - "Android" - "iOS" - "Mobile" - "Audio Recording and Production" - "Mineral" - "Mining" - "Mining Technology" - "Natural Resources" - "Precious Metals" - "Timber" - "Water" - "Indoor Positioning" - "Mapping Services" - "Navigation" - "Association" - "B2B" - "B2C" - "Charity" - "Collaboration" - "Collaborative Consumption" - "Commercial" - "Consumer" - "Crowdsourcing" - "Customer Service" - "Desktop Apps" - "Emerging Markets" - "Enterprise" - "Franchise" - "Freemium" - "Generation Y" - "Generation Z" - "Homeless Shelter" - "Infrastructure" - "LGBT Millennials" - "Non Profit" - "Peer to Peer" - "Professional Services" - "Real Time" - "Service Industry" - "Sharing Economy" - "Small and Medium Businesses" - "Social Impact" - "Subscription Service" - "Underserved Children" - "Universities" - "Billing" - "Facebook" - "Google" - "Linux" - "macOS" - "Operating Systems" - "Tizen" - "Twitter" - "WebOS" - "Windows" - "Corrections Facilities" - "Homeland Security" - "Privacy" - "Security" - "Advocacy" - "Business Development" - "Career Planning" - "Compliance" - "Consulting" - "Employment" - "Environmental Consulting" - "Field Support" - "Freelance" - "Innovation Management" - "Intellectual Property" - "Legal" - "Legal Tech" - "Management Consulting" - "Outsourcing" - "Quality Assurance" - "Recruiting" - "Risk Management" - "Social Recruiting" - "Translation Service" - "Architecture" - "Building Maintenance" - "Building Material" - "Commercial Real Estate" - "Construction" - "Coworking" - "Facility Management" - "Green Building" - "Heating" - "Ventilation" - "and Air Conditioning (HVAC)" - "Home and Garden" - "Home Decor" - "Home Improvement" - "Home Renovation" - "Home Services" - "Janitorial Service" - "Landscaping" - "Mortgage" - "Property Development" - "Property Management" - "PropTech" - "Real Estate" - "Real Estate Brokerage" - "Rental Property" - "Residential" - "Self-Storage" - "Smart Building" - "Smart Cities" - "Timeshare" - "Vacation Rental" - "App Marketing" - "Brand Marketing" - "Cause Marketing" - "Content Marketing" - "Digital Marketing" - "Digital Signage" - "Direct Marketing" - "Direct Sales" - "Email Marketing" - "Lead Generation" - "Lead Management" - "Local" - "Local Business" - "Loyalty Programs" - "Marketing" - "Marketing Automation" - "Multi-level Marketing" - "Personal Branding" - "Public Relations" - "Sales" - "Sales Enablement" - "Social Media Marketing" - "Sponsorship" - "Aerospace" - "Chemical" - "Chemical Engineering" - "Civil Engineering" - "Environmental Engineering" - "Marine Technology" - "Mechanical Engineering" - "Nanotechnology" - "Nuclear" - "Quantum Computing" - "Software Engineering" - "Browser Extensions" - "Business Process Automation (BPA)" - "Chatbot" - "Consumer Software" - "Developer APIs" - "Developer Platform" - "Developer Tools" - "Embedded Software" - "Enterprise Resource Planning (ERP)" - "Enterprise Software" - "File Sharing" - "IaaS" - "Open Source" - "PaaS" - "Presentation Software" - "Presentations" - "Productivity Tools" - "QR Codes" - "SaaS" - "Simulation" - "SNS" - "Software" - "Task Management" - "Virtual Assistant" - "Virtual Desktop" - "Web Development" - "American Football" - "Baseball" - "Basketball" - "Boating" - "Cricket" - "Cycling" - "Diving" - "eSports" - "Fitness" - "Golf" - "Hockey" - "Hunting" - "Motorsports" - "Outdoors" - "Racing" - "Recreation" - "Rugby" - "Sailing" - "Skiing" - "Soccer" - "Sports" - "Sports Leagues and Teams" - "Surfing" - "Swimming" - "Table Tennis" - "Tennis" - "Ultimate Frisbee" - "Volley Ball" - "Carbon Capture" - "CleanTech" - "GreenTech" - "Organic" - "Pollution Control" - "Recycling" - "Sustainability" - "Waste Management" - "Water Purification" - "Wildlife Conservation" - "Air Transportation" - "Automotive" - "Autonomous Vehicles" - "Car Sharing" - "Charging Infrastructure" - "Delivery Service" - "Electric Vehicle" - "Ferry Service" - "Fleet Management" - "Freight Service" - "Last Mile Transportation" - "Limousine Service" - "Logistics" - "Marine Transportation" - "Parking" - "Ports and Harbors" - "Procurement" - "Public Transportation" - "Railroad" - "Recreational Vehicles" - "Ride Sharing" - "Same Day Delivery" - "Shipping" - "Shipping Broker" - "Space Travel" - "Supply Chain Management" - "Taxi Service" - "Transportation" - "Warehouse Automation" - "Warehousing" - "Water Transportation" - "Adventure Travel" - "Amusement Park and Arcade" - "Business Travel" - "Casino" - "Hospitality" - "Hotel" - "Museums and Historical Sites" - "Parks" - "Resorts" - "Tour Operator" - "Tourism" - "Travel" - "Travel Accommodations" - "Travel Agency" CustomFilters: type: object description: | Custom filters in JSON format for advanced filtering. Omit the parameter to use default filtering logic. **Available on Scale with Us. Not included in Free Trial or Self-Service.** Custom filters can sharply reduce the number of matching candidates and exclude relevant people. [Contact us](mailto:support@pearch.ai) so we can help configure them for your search. Using restricted custom filters without access returns HTTP 403 with code `feature_not_enabled`. Natural-language `query` and `search_requirements` remain available on all plans. 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. `industries` and `not_industries` take canonical industry names listed under `Industry`; matching is case-insensitive. In `fast` and `superfast` search and in `/v2/search/count`, an unknown industry returns HTTP 400. In `pro` search, other strings are mapped semantically to canonical industries. An industry matches any employer in the person's career history, not only the current one. 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. properties: locations: type: array maxItems: 50 items: type: string description: Filter by location (e.g., "San Francisco", "New York", "California", "United States") example: ["San Francisco", "New York"] location_coordinates: type: array maxItems: 50 items: $ref: '#/components/schemas/LocationCoordinateFilter' description: Filter by one or more latitude/longitude radius areas. Areas within this field are combined with OR. example: [{"lat": 37.7749, "lng": -122.4194, "radius_miles": 25}] not_locations: type: array maxItems: 50 items: type: string description: Exclude profiles by location (same format as locations) example: ["Austin", "Boston"] languages: type: array items: oneOf: - type: string - $ref: '#/components/schemas/Language' description: >- Include profiles by language. Supply an exact name from the [canonical language list](https://gist.githubusercontent.com/vslaykovsky/6226be891e040939e83a19c3afa0e0d1/raw/canonical_languages.txt) as a string or as the language field of an object with optional minimum proficiency. Match the published spelling, case, and whitespace. Values outside the list return HTTP 400. example: ["Spanish", {"language": "English", "proficiency": "C1"}] not_languages: type: array items: oneOf: - type: string - $ref: '#/components/schemas/Language' description: >- Exclude profiles by language. Supply an exact name from the [canonical language list](https://gist.githubusercontent.com/vslaykovsky/6226be891e040939e83a19c3afa0e0d1/raw/canonical_languages.txt) as a string or as the language field of an object with optional minimum proficiency. Match the published spelling, case, and whitespace. Values outside the list return HTTP 400. example: ["French", {"language": "Spanish", "proficiency": "B2"}] titles: type: array items: type: string description: Filter by job titles (e.g., "Software Engineer", "Data Scientist", "CEO") example: ["software engineer", "data scientist"] not_titles: type: array items: type: string description: Exclude profiles by job titles (e.g., "Intern", "Volunteer") example: ["intern", "volunteer"] current_titles: type: array items: type: string description: Filter by current job title only example: ["software engineer", "tech lead"] not_current_titles: type: array items: type: string description: Exclude profiles by current job title (same format as current_titles) example: ["retired", "student"] industries: type: array items: $ref: '#/components/schemas/Industry' description: Filter by canonical industry names listed under Industry; case-insensitive. Matches any employer in the career history. example: ["Health Care", "Pharmaceutical"] not_industries: type: array items: $ref: '#/components/schemas/Industry' description: Exclude profiles by canonical industry names listed under Industry example: ["Retail", "Gaming"] companies: type: array items: type: string description: Filter by company names (e.g., "Google", "Microsoft", "Amazon") example: ["Google", "Microsoft"] not_companies: type: array items: type: string description: Exclude profiles by company (any experience; same format as companies) example: ["Acme Corp", "Former Employer Inc"] current_experience_companies: type: array items: type: string description: Filter by current employer only example: ["Google", "Meta"] not_current_experience_companies: type: array items: type: string description: Exclude profiles by current employer (same format as current_experience_companies) example: ["Company X", "Competitor Inc"] universities: type: array items: type: string description: Filter by universities attended (e.g., "Stanford University", "MIT", "Harvard") example: ["Stanford University", "MIT"] not_universities: type: array items: type: string description: Exclude profiles by university (same format as universities) example: ["Unknown College", "Online University"] keywords: type: array items: type: string description: Filter by keywords in full profile description example: ["machine learning", "python", "leadership"] keywords_blacklist: type: array items: type: string description: Exclude profiles containing these keywords example: ["retired", "student only"] min_linkedin_followers: type: integer description: Minimum number of LinkedIn followers example: 500 max_linkedin_followers: type: integer description: Maximum number of LinkedIn followers example: 10000 min_total_experience_years: type: number description: Minimum total years of professional experience example: 5.5 max_total_experience_years: type: number description: Maximum total years of professional experience example: 15.5 min_estimated_age: type: number description: Minimum estimated age example: 25 max_estimated_age: type: number description: Maximum estimated age example: 45 studied_at_top_universities: type: boolean description: Filter for candidates who attended top-tier universities example: true first_name: type: string description: Filter by first name (exact match) example: "John" middle_name: type: string description: Filter by middle name (exact match) example: "Michael" last_name: type: string description: Filter by last name (exact match) example: "Smith" gender: type: string enum: [male, female] description: Filter by gender example: "male" has_startup_experience: type: boolean description: Filter for candidates who have worked at startups example: true has_saas_experience: type: boolean description: Filter for candidates who have worked at SaaS companies example: true has_b2b_experience: type: boolean description: Filter for candidates who have worked at B2B companies example: true has_b2c_experience: type: boolean description: Filter for candidates who have worked at B2C companies example: true min_current_experience_years: type: number description: Minimum years in current role example: 1 max_current_experience_years: type: number description: Maximum years in current role example: 5 degrees: type: array items: type: string enum: [associate, bachelor, master, MBA, doctor, postdoc] description: Filter by degree types example: ["bachelor", "master"] not_degrees: type: array items: type: string enum: [associate, bachelor, master, MBA, doctor, postdoc] description: Exclude profiles by degree types (same enum as degrees) example: ["bachelor"] specialization_categories: type: array items: type: string enum: - "Business & Management" - "Finance" - "Engineering" - "Computer Science & IT" - "Health & Medicine" - "Social Sciences" - "Natural Sciences" - "Mathematics" - "Education" - "Communication & Media" - "Arts, Design & Architecture" - "Humanities & Liberal Arts" - "Law & Criminal Justice" description: "Filter by specialization categories. Allowed values include: Business & Management, Finance, Engineering, Computer Science & IT, Health & Medicine, Social Sciences, Natural Sciences, Mathematics, Education, Communication & Media, Arts, Design & Architecture, Humanities & Liberal Arts, Law & Criminal Justice." example: ["Computer Science & IT", "Engineering"] not_specialization_categories: type: array items: type: string enum: - "Business & Management" - "Finance" - "Engineering" - "Computer Science & IT" - "Health & Medicine" - "Social Sciences" - "Natural Sciences" - "Mathematics" - "Education" - "Communication & Media" - "Arts, Design & Architecture" - "Humanities & Liberal Arts" - "Law & Criminal Justice" description: Exclude profiles by specialization category (same enum as specialization_categories) example: ["Arts, Design & Architecture"] additionalProperties: false example: industries: ["Health Care", "Pharmaceutical"] locations: ["San Francisco", "New York"] titles: ["software engineer", "data scientist"] min_total_experience_years: 5.5 studied_at_top_universities: true Language: type: object description: Language with proficiency level properties: language: type: string description: Language name example: "English" proficiency: type: string description: "Proficiency level: A1, A2, B1, B2, C1, C2" enum: [A1, A2, B1, B2, C1, C2, unknown] example: "C1" FundingRound: type: object description: Information about a company's funding round properties: value_usd: type: integer description: Funding amount in USD example: 2000000 date: type: string format: date description: Date of the funding round example: "2023-06-15" round_name: type: string description: Name of the funding round example: "Series A" CompanyInfo: type: object description: Comprehensive company information and metadata properties: name: type: string description: The name of the company example: "Dragoonitcn" domain: type: string description: Company's primary domain example: "dragoonitcn.com" website: type: string description: The official website of the company example: "http://www.dragoonitcn.com" linkedin_url: type: string description: The LinkedIn URL of the company example: "https://linkedin.com/company/dragoon-itcn" linkedin_slug: type: string description: LinkedIn slug identifier example: "dragoon-itcn" crunchbase_url: type: string description: The Crunchbase URL of the company example: "https://www.crunchbase.com/organization/dragoonitcn" social_urls: type: array description: List of social media URLs items: type: string example: ["https://twitter.com/dragoonitcn", "https://facebook.com/pages/Dragoonitcn/125328487521849"] emails: type: array description: List of company email addresses items: type: string example: ["contact@dragoonitcn.com", "sales@dragoonitcn.com"] phone_number: type: string description: Company phone number example: "+1-555-123-4567" phone_numbers: type: array description: List of company phone numbers items: type: string example: ["+1-555-123-4567", "+1-555-987-6543"] short_address: type: string description: Brief address information example: "Dayton, OH" locations: type: array description: List of company locations items: type: string example: ["Dayton, Ohio", "San Francisco, CA"] type: type: string description: Type of company example: "Private" description: type: string description: A brief description of the company's business example: "Targeting Complex Aerospace Issues with Precision Test Tools" industries: type: array description: The industries the company operates in items: type: string enum: ['Archiving Service', 'Call Center', 'Collection Agency', 'College Recruiting', 'Courier Service', 'Debt Collections', 'Delivery', 'Document Preparation', 'Employee Benefits', 'Extermination Service', 'Facilities Support Services', 'Housekeeping Service', 'Human Resources', 'Knowledge Management', 'Office Administration', 'Packaging Services', 'Physical Security', 'Project Management', 'Staffing Agency', 'Trade Shows', 'Virtual Workforce', 'Ad Exchange', 'Ad Network', 'Ad Retargeting', 'Ad Server', 'Ad Targeting', 'Advertising', 'Advertising Platforms', 'Affiliate Marketing', 'Local Advertising', 'Mobile Advertising', 'Native Advertising', 'Outdoor Advertising', 'SEM', 'Social Media Advertising', 'Video Advertising', 'Agriculture', 'AgTech', 'Animal Feed', 'Aquaculture', 'Equestrian', 'Farming', 'Forestry', 'Horticulture', 'Hydroponics', 'Livestock', 'App Discovery', 'Apps', 'Consumer Applications', 'Enterprise Applications', 'Mobile Apps', 'Reading Apps', 'Web Apps', 'Artificial Intelligence (AI)', 'Generative AI', 'Intelligent Systems', 'Machine Learning', 'Natural Language Processing', 'Predictive Analytics', 'Robotic Process Automation (RPA)', 'Bioinformatics', 'Biometrics', 'Biopharma', 'Biotechnology', 'Genetics', 'Life Science', 'Neuroscience', 'Quantified Self', 'Bitcoin', 'Blockchain', 'Cryptocurrency', 'Decentralized Finance (DeFi)', 'Ethereum', 'Non-Fungible Token (NFT)', 'Smart Contracts', 'Web3', 'Apparel', 'Fashion', 'Laundry and Dry-cleaning', 'Lingerie', 'Shoes', 'Auctions', 'Classifieds', 'Collectibles', 'Consumer Reviews', 'Coupons', 'E-Commerce', 'E-Commerce Platforms', 'Flash Sale', 'Gift', 'Gift Card', 'Gift Exchange', 'Gift Registry', 'Group Buying', 'Local Shopping', 'Made to Order', 'Marketplace', 'Office Supplies', 'Online Auctions', 'Personalization', 'Point of Sale', 'Price Comparison', 'Rental', 'Retail', 'Retail Technology', 'Secondhand Goods', 'Shopping', 'Shopping Mall', 'Social Shopping', 'Sporting Goods', 'Vending and Concessions', 'Virtual Goods', 'Wholesale', 'Adult', 'Baby', 'Cannabis', 'Children', 'Communities', 'Dating', 'Elderly', 'Family', 'Funerals', 'Humanitarian', 'Leisure', 'LGBT', 'Lifestyle', "Men's", 'Online Forums', 'Parenting', 'Pet', 'Private Social Networking', 'Professional Networking', 'Q&A', 'Religion', 'Retirement', 'Sex Industry', 'Sex Tech', 'Social', 'Social Entrepreneurship', 'Teenagers', 'Virtual World', 'Wedding', "Women's", 'Young Adults', 'Computer', 'Consumer Electronics', 'Drones', 'Electronics', 'Google Glass', 'Mobile Devices', 'Nintendo', 'Playstation', 'Roku', 'Smart Home', 'Wearables', 'Windows Phone', 'Xbox', 'Beauty', 'Card and Board Games', 'Cleaning Products', 'Comics', 'Consumer Goods', 'Cosmetics', 'DIY', 'Eyewear', 'Fast-Moving Consumer Goods', 'Flowers', 'Furniture', 'Green Consumer Goods', 'Handmade', 'Home Appliances', 'Jewelry', 'Personal Care and Hygiene', 'Tobacco', 'Toys', 'Blogging Platforms', 'Books', 'Content Delivery Network', 'Content Discovery', 'Content Syndication', 'Copywriting', 'Creative Agency', 'DRM', 'EBooks', 'Journalism', 'News', 'Photo Editing', 'Photo Sharing', 'Photography', 'Printing', 'Publishing', 'Social Bookmarking', 'Video Editing', 'Video Streaming', 'A/B Testing', 'Analytics', 'Application Performance Management', 'Big Data', 'Business Intelligence', 'Consumer Research', 'Data Collection and Labeling', 'Data Governance', 'Data Integration', 'Data Management', 'Data Mining', 'Data Visualization', 'Database', 'Facial Recognition', 'Geospatial', 'Image Recognition', 'Location Based Services', 'Market Research', 'Product Research', 'Speech Recognition', 'Test and Measurement', 'Text Analytics', 'Usability Testing', 'CAD', 'Graphic Design', 'Human Computer Interaction', 'Industrial Design', 'Interior Design', 'Mechanical Design', 'Product Design', 'UX Design', 'Web Design', 'Alumni', 'Charter Schools', 'Continuing Education', 'Corporate Training', 'E-Learning', 'EdTech', 'Education', 'Edutainment', 'Higher Education', 'Language Learning', 'MOOC', 'Music Education', 'Personal Development', 'Primary Education', 'Secondary Education', 'Skill Assessment', 'Special Education', 'STEM Education', 'Textbook', 'Training', 'Tutoring', 'Vocational Education', 'Battery', 'Biofuel', 'Biomass Energy', 'Clean Energy', 'Electrical Distribution', 'Energy', 'Energy Efficiency', 'Energy Management', 'Energy Storage', 'Fossil Fuels', 'Fuel', 'Fuel Cell', 'Geothermal Energy', 'Hydroelectric', 'Oil and Gas', 'Power Grid', 'Renewable Energy', 'Solar', 'Wind Energy', 'Concerts', 'Event Management', 'Event Promotion', 'Events', 'Nightclubs', 'Nightlife', 'Reservations', 'Ticketing', 'Accounting', 'Angel Investment', 'Asset Management', 'Auto Insurance', 'Banking', 'Bookkeeping and Payroll', 'Commercial Insurance', 'Commercial Lending', 'Consumer Lending', 'Credit', 'Credit Bureau', 'Credit Cards', 'Crowdfunding', 'Debit Cards', 'Finance', 'Financial Exchanges', 'Financial Services', 'FinTech', 'Foreign Exchange Trading', 'Fraud Detection', 'Funding Platform', 'Health Insurance', 'Hedge Funds', 'Impact Investing', 'Incubators', 'Insurance', 'InsurTech', 'Leasing', 'Lending', 'Life Insurance', 'Micro Lending', 'Mobile Payments', 'Payments', 'Personal Finance', 'Prediction Markets', 'Prepaid Cards', 'Property Insurance', 'Real Estate Investment', 'Stock Exchanges', 'Tax Consulting', 'Tax Preparation', 'Trading Platform', 'Transaction Processing', 'Venture Capital', 'Virtual Currency', 'Wealth Management', 'Alternative Protein', 'Bakery', 'Brewing', 'Catering', 'Coffee', 'Confectionery', 'Cooking', 'Craft Beer', 'Dairy', 'Dietary Supplements', 'Distillery', 'Farmers Market', 'Food and Beverage', 'Food Delivery', 'Food Processing', 'Food Trucks', 'Fruit', 'Grocery', 'Herbs and Spices', 'Meat and Poultry', 'Nutrition', 'Organic Food', 'Plant-Based Foods', 'Recipes', 'Restaurants', 'Seafood', 'Snack Food', 'Tea', 'Wine And Spirits', 'Winery', 'Casual Games', 'Console Games', 'Contests', 'Fantasy Sports', 'Gambling', 'Gamification', 'Gaming', 'MMO Games', 'Online Games', 'PC Games', 'Serious Games', 'Video Games', 'CivicTech', 'Government', 'GovTech', 'Law Enforcement', 'Military', 'National Security', 'Politics', 'Public Safety', 'Social Assistance', '3D Technology', 'Application Specific Integrated Circuit (ASIC)', 'Audio/Visual Equipment', 'Augmented Reality', 'Cloud Infrastructure', 'Communication Hardware', 'Communications Infrastructure', 'Computer Vision', 'Data Center', 'Data Center Automation', 'Data Storage', 'Drone Management', 'DSP', 'Electronic Design Automation (EDA)', 'Embedded Systems', 'Field-Programmable Gate Array (FPGA)', 'Flash Storage', 'GPS', 'GPU', 'Hardware', 'Laser', 'Lighting', 'Network Hardware', 'NFC', 'Optical Communication', 'Private Cloud', 'Remote Sensing', 'RFID', 'RISC', 'Robotics', 'Satellite Communication', 'Semiconductor', 'Sensor', 'Telecommunications', 'Video Conferencing', 'Virtual Reality', 'Virtualization', 'Wireless', 'Addiction Treatment', 'Alternative Medicine', 'Assisted Living', 'Assistive Technology', 'Child Care', 'Clinical Trials', 'Cosmetic Surgery', 'Dental', 'Diabetes', 'Elder Care', 'Electronic Health Record (EHR)', 'Emergency Medicine', 'Fertility', 'First Aid', 'Health Care', 'Health Diagnostics', 'Home Health Care', 'Hospital', 'Medical', 'Medical Device', 'Mental Health', 'mHealth', 'Nursing and Residential Care', 'Nutraceutical', 'Oncology', 'Outpatient Care', 'Personal Health', 'Pharmaceutical', 'Precision Medicine', 'Primary and Urgent Care', 'Psychology', 'Rehabilitation', 'Telehealth', 'Therapeutics', 'Veterinary', 'Wellness', 'Business Information Systems', 'Cloud Data Services', 'Cloud Management', 'Cloud Security', 'CMS', 'Contact Management', 'CRM', 'Cyber Security', 'DevOps', 'Document Management', 'E-Signature', 'Email', 'Identity Management', 'Information and Communications Technology (ICT)', 'Information Services', 'Information Technology', 'Intrusion Detection', 'IT Infrastructure', 'IT Management', 'Management Information Systems', 'Messaging', 'Network Security', 'Penetration Testing', 'Reputation', 'Sales Automation', 'Scheduling', 'Social CRM', 'Spam Filtering', 'Technical Support', 'Unified Communications', 'Video Chat', 'VoIP', 'Cloud Computing', 'Cloud Storage', 'Darknet', 'Domain Registrar', 'Ediscovery', 'Internet', 'Internet of Things', 'ISP', 'Music Streaming', 'Online Portals', 'Product Search', 'Search Engine', 'Semantic Search', 'Semantic Web', 'SEO', 'SMS', 'Social Media', 'Social Media Management', 'Social Network', 'Vertical Search', 'Visual Search', 'Web Browsers', 'Web Hosting', '3D Printing', 'Advanced Materials', 'Foundries', 'Industrial', 'Industrial Automation', 'Industrial Engineering', 'Industrial Manufacturing', 'Machinery Manufacturing', 'Manufacturing', 'Paper Manufacturing', 'Plastics and Rubber Manufacturing', 'Textiles', 'Wood Processing', 'Advice', 'Animation', 'Art', 'Audio', 'Audiobooks', 'Broadcasting', 'Celebrity', 'Content', 'Content Creators', 'Digital Entertainment', 'Digital Media', 'Film', 'Film Distribution', 'Film Production', 'Guides', 'In-Flight Entertainment', 'Independent Music', 'Internet Radio', 'Media and Entertainment', 'Metaverse', 'Motion Capture', 'Music', 'Music Label', 'Music Venues', 'Musical Instruments', 'Performing Arts', 'Podcast', 'Social News', 'Theatre', 'TV', 'TV Production', 'Video', 'Video on Demand', 'Meeting Software', 'Wired Telecommunications', 'Android', 'iOS', 'Mobile', 'Audio Recording and Production', 'Mineral', 'Mining', 'Mining Technology', 'Natural Resources', 'Precious Metals', 'Timber', 'Water', 'Indoor Positioning', 'Mapping Services', 'Navigation', 'Association', 'B2B', 'B2C', 'Charity', 'Collaboration', 'Collaborative Consumption', 'Commercial', 'Consumer', 'Crowdsourcing', 'Customer Service', 'Desktop Apps', 'Emerging Markets', 'Enterprise', 'Franchise', 'Freemium', 'Generation Y', 'Generation Z', 'Homeless Shelter', 'Infrastructure', 'LGBT Millennials', 'Non Profit', 'Peer to Peer', 'Professional Services', 'Real Time', 'Service Industry', 'Sharing Economy', 'Small and Medium Businesses', 'Social Impact', 'Subscription Service', 'Underserved Children', 'Universities', 'Billing', 'Facebook', 'Google', 'Linux', 'macOS', 'Operating Systems', 'Tizen', 'Twitter', 'WebOS', 'Windows', 'Corrections Facilities', 'Homeland Security', 'Privacy', 'Security', 'Advocacy', 'Business Development', 'Career Planning', 'Compliance', 'Consulting', 'Employment', 'Environmental Consulting', 'Field Support', 'Freelance', 'Innovation Management', 'Intellectual Property', 'Legal', 'Legal Tech', 'Management Consulting', 'Outsourcing', 'Quality Assurance', 'Recruiting', 'Risk Management', 'Social Recruiting', 'Translation Service', 'Architecture', 'Building Maintenance', 'Building Material', 'Commercial Real Estate', 'Construction', 'Coworking', 'Facility Management', 'Green Building', 'Heating', 'Ventilation', 'and Air Conditioning (HVAC)', 'Home and Garden', 'Home Decor', 'Home Improvement', 'Home Renovation', 'Home Services', 'Janitorial Service', 'Landscaping', 'Mortgage', 'Property Development', 'Property Management', 'PropTech', 'Real Estate', 'Real Estate Brokerage', 'Rental Property', 'Residential', 'Self-Storage', 'Smart Building', 'Smart Cities', 'Timeshare', 'Vacation Rental', 'App Marketing', 'Brand Marketing', 'Cause Marketing', 'Content Marketing', 'Digital Marketing', 'Digital Signage', 'Direct Marketing', 'Direct Sales', 'Email Marketing', 'Lead Generation', 'Lead Management', 'Local', 'Local Business', 'Loyalty Programs', 'Marketing', 'Marketing Automation', 'Multi-level Marketing', 'Personal Branding', 'Public Relations', 'Sales', 'Sales Enablement', 'Social Media Marketing', 'Sponsorship', 'Aerospace', 'Chemical', 'Chemical Engineering', 'Civil Engineering', 'Environmental Engineering', 'Marine Technology', 'Mechanical Engineering', 'Nanotechnology', 'Nuclear', 'Quantum Computing', 'Software Engineering', 'Browser Extensions', 'Business Process Automation (BPA)', 'Chatbot', 'Consumer Software', 'Developer APIs', 'Developer Platform', 'Developer Tools', 'Embedded Software', 'Enterprise Resource Planning (ERP)', 'Enterprise Software', 'File Sharing', 'IaaS', 'Open Source', 'PaaS', 'Presentation Software', 'Presentations', 'Productivity Tools', 'QR Codes', 'SaaS', 'Simulation', 'SNS', 'Software', 'Task Management', 'Virtual Assistant', 'Virtual Desktop', 'Web Development', 'American Football', 'Baseball', 'Basketball', 'Boating', 'Cricket', 'Cycling', 'Diving', 'eSports', 'Fitness', 'Golf', 'Hockey', 'Hunting', 'Motorsports', 'Outdoors', 'Racing', 'Recreation', 'Rugby', 'Sailing', 'Skiing', 'Soccer', 'Sports', 'Sports Leagues and Teams', 'Surfing', 'Swimming', 'Table Tennis', 'Tennis', 'Ultimate Frisbee', 'Volley Ball', 'Carbon Capture', 'CleanTech', 'GreenTech', 'Organic', 'Pollution Control', 'Recycling', 'Sustainability', 'Waste Management', 'Water Purification', 'Wildlife Conservation', 'Air Transportation', 'Automotive', 'Autonomous Vehicles', 'Car Sharing', 'Charging Infrastructure', 'Delivery Service', 'Electric Vehicle', 'Ferry Service', 'Fleet Management', 'Freight Service', 'Last Mile Transportation', 'Limousine Service', 'Logistics', 'Marine Transportation', 'Parking', 'Ports and Harbors', 'Procurement', 'Public Transportation', 'Railroad', 'Recreational Vehicles', 'Ride Sharing', 'Same Day Delivery', 'Shipping', 'Shipping Broker', 'Space Travel', 'Supply Chain Management', 'Taxi Service', 'Transportation', 'Warehouse Automation', 'Warehousing', 'Water Transportation', 'Adventure Travel', 'Amusement Park and Arcade', 'Business Travel', 'Casino', 'Hospitality', 'Hotel', 'Museums and Historical Sites', 'Parks', 'Resorts', 'Tour Operator', 'Tourism', 'Travel', 'Travel Accommodations', 'Travel Agency', "Administrative", "Apparel & Fashion", "Arts", "Associations", "Automation", "Aviation", "Beverage Manufacturing", "Broadcast Media", "Business", "Business Supplies and Equipment", "Computer Hardware", "Computer Networking", "Computer Software", "Consumer Services", "Defense", "Design", "Digital Accessibility", "Education Management", "Electric Power", "Electrical/Electronic Manufacturing", "Emergency", "Engineering", "Entertainment", "Events Services", "Facilities", "Food Production", "IT Services", "Import/Export", "International Affairs", "International Trade and Development", "Investment Management", "Judiciary", "Legal Services", "Libraries", "Machinery", "Maintenance", "Mapping", "Maritime", "Media", "Media Production", "Motion Pictures and Film", "Networking", "Non-profit Organizations", "Outsourcing/Offshoring", "Personal Care", "Pharmaceuticals", "Philanthropy", "Postal", "Professional Training", "Professional Training & Coaching", "Program Management", "Public Policy", "Religious Institutions", "Repair and Maintenance", "Research", "Safety", "Services", "Shipbuilding", "Social Services", "Software Development", "Staffing", "Think Tanks", "Trade", "Translation", "Urban Planning", "Utilities", "Venture Capital & Private Equity", "Vocational", "Women's Handbag Manufacturing", "Writing"] example: ["Aerospace", "GreenTech", "Information Technology"] specialties: type: array description: Company specialties items: type: string example: ["Precision Testing", "Aerospace Solutions"] keywords: type: array description: Keywords associated with the company's operations items: type: string example: ["cable fault isolation", "tdr", "comint"] technologies: type: array description: Technologies used by the company items: type: string example: ["Python", "Machine Learning", "Cloud Computing"] founded_in: type: integer description: The year the company was founded example: 1992 num_employees: type: integer description: Exact number of employees example: 25 num_employees_range: type: string description: The range of the number of employees in the company example: "11-50" annual_revenue: type: integer description: The annual revenue of the company in USD example: 33867000 followers_count: type: integer description: Number of followers on LinkedIn example: 1500 funding_total_usd: type: integer description: Total funding raised in USD example: 5000000 latest_funding_amount: type: integer description: Amount of the latest funding round in USD example: 2000000 latest_funding_round: type: string description: Latest funding round information example: "Series A" last_funding_round_year: type: integer description: Year of the last funding round example: 2023 last_funding_round_date: type: string format: date description: Exact date of the latest funding round example: "2023-09-15" valuation: type: integer description: Company valuation in USD example: 50000000 funding_rounds: type: array description: List of funding rounds items: $ref: '#/components/schemas/FundingRound' ipo_date: type: string format: date description: Date when the company went public example: "2021-04-14" has_ipo: type: boolean description: Indicates if the company has had an Initial Public Offering (IPO) example: false is_b2b: type: boolean description: Indicates if the company operates on a Business-to-Business model example: true is_b2c: type: boolean description: Indicates if the company operates on a Business-to-Consumer model example: false is_saas: type: boolean description: Indicates if the company provides Software as a Service example: false is_health_tech: type: boolean description: Indicates if the company operates in health technology example: false is_hiring: type: boolean description: Indicates if the company is currently hiring example: true backed_by_y_combinator: type: boolean description: Indicates if the company is backed by Y Combinator example: false yc_batch: type: string description: Y Combinator batch code, a season letter (W Winter, S Summer, F Fall, P Spring) plus a two-digit year example: "W22" yc_batch_year: type: integer description: Year of the Y Combinator batch example: 2022 icon: type: string description: The URL to the company's icon image example: "https://zenprospect-production.s3.amazonaws.com/uploads/pictures/6768a72faa352b0001ee57ef/picture" website_score: type: integer description: Website quality/trust score example: 85 Experience: type: object description: Professional work experience properties: sequenceNo: type: integer description: Sequence number for ordering roles example: 1 company: type: string description: Name of the company for this role example: "Dragoonitcn" company_domain: type: string description: Company domain example: "dragoonitcn.com" title: type: string description: Job title for the role example: "Software Engineer II" employment_type: type: string nullable: true description: "Employment type supplied by the profile source, such as Full-time, Part-time, Contract, Freelance, or Self-employed. With high_freshness=true, refreshed profiles include this field when the source provides it. It may be absent or null when unavailable, including in older indexed profiles." example: "Contract" start_date: type: string format: date description: Start date of the role example: "2024-01-01" end_date: type: string format: date description: End date of the role example: "2024-08-01" duration_years: type: number description: Duration in years the role was held example: 0.7 age_years: type: number description: How long ago has the candidate left the role (in years). So essentially it's today - end_date in years. example: 1.2 location: type: string description: Location of the job example: "Dayton, Ohio, United States" location_info: type: object description: Structured location information, including latitude, longitude, and country code properties: lat: type: number format: float description: Latitude of the location example: 37.7749 lng: type: number format: float description: Longitude of the location example: -122.4194 country_code: type: string description: ISO 3166-1 alpha-2 country code (e.g., "US", "IN") example: "US" additionalProperties: false experience_summary: type: string description: Summary of responsibilities and accomplishments in this role example: "Designed and developed software using .NET..." is_current_experience: type: boolean description: Whether this is the current role example: true is_startup_experience: type: boolean description: Whether this role overlapped the funded company's first seven years example: true Education: type: object description: Educational experience properties: sequenceNo: type: integer description: Sequence number for ordering education entries example: 1 university_linkedin_url: type: string description: LinkedIn URL of the educational institution example: "https://linkedin.com/school/university-of-california-berkeley" campus: type: string description: Campus name or location example: "Berkeley Campus" specialization: type: string description: Field of specialization or study example: "Computer Science" specialization_category: type: string description: Category of specialization or study example: "Computer Science & IT" enum: - Business & Management - Finance - Engineering - Computer Science & IT - Health & Medicine - Social Sciences - Natural Sciences - Mathematics - Education - Communication & Media - Arts, Design & Architecture - Humanities & Liberal Arts - Law & Criminal Justice degree: type: array description: 'List of degrees obtained: "associate", "bachelor", "master", "MBA", "doctor", "postdoc"' items: type: string enum: - associate - bachelor - master - MBA - doctor - postdoc example: ["bachelor", "doctor"] major: type: string description: Major field of study example: "Computer Science" start_date: type: string format: date description: Start date of the education example: "2018-09-01" end_date: type: string format: date description: End date of the education example: "2022-06-01" Certification: type: object description: Professional certification properties: title: type: string description: Certification title example: "AWS Certified Solutions Architect" issuer: type: string description: Issuing organization as listed on the profile example: "Amazon Web Services (AWS)" issuer_url: type: string description: Link to the issuing organization, when listed example: "https://www.linkedin.com/company/amazon-web-services/" certificate_url: type: string description: Link to the certificate or badge, when listed example: "https://www.credly.com/badges/00000000-0000-0000-0000-000000000000" begin_date: type: string format: date description: Issue date example: "2023-05-01" end_date: type: string format: date description: Expiry date. Absent when the profile lists no expiry, which means unknown, not expired. example: "2026-05-01" Recommendation: type: object description: LinkedIn recommendation written by a colleague properties: recommendation: type: string description: Recommendation text example: "Jane led our data platform migration and mentored three junior engineers." referee_name: type: string description: Name of the person who wrote the recommendation example: "John Smith" referee_url: type: string description: LinkedIn profile URL of the person who wrote the recommendation example: "https://www.linkedin.com/in/john-smith" Activity: type: object description: LinkedIn post the person wrote or reposted properties: title: type: string description: Truncated snippet of the post text example: "Excited to share how we cut our Kubernetes costs by 40%..." action: type: string description: "\"Posted by\" when the person wrote the post, \"Shared by\" for a repost" enum: ["Posted by", "Shared by"] example: "Posted by" activityUrl: type: string description: Link to the post example: "https://www.linkedin.com/feed/update/urn:li:activity:0000000000000000000" Patent: type: object description: Patent information properties: title: type: string description: Patent title example: "Machine Learning Algorithm for Data Processing" reference: type: string description: Patent reference number example: "US10123456B2" description: type: string description: Patent description example: "A novel approach to processing large datasets using machine learning techniques" date: type: string format: date description: Patent date example: "2023-05-15" url: type: string description: URL to patent documentation example: "https://patents.uspto.gov/patent/10123456" CompanyExperienceGroup: type: object description: Group of experiences at the same company properties: company_info: $ref: '#/components/schemas/CompanyInfo' company_roles: type: array description: Roles held by the candidate in this company items: $ref: '#/components/schemas/Experience' HealthcareInfo: type: object nullable: true description: Registry data of a US healthcare provider, set on registry records from the `healthcare` source (beta). It comes from the CMS NPPES registry as of `snapshot_date`. properties: primary_taxonomy_code: type: string description: NUCC taxonomy code of the provider's primary specialty. example: "207LP3000X" primary_specialty: type: string description: Name of the primary specialty. example: "Pediatric Anesthesiology Physician" primary_classification: type: string description: NUCC classification of the primary specialty. example: "Anesthesiology" occupation_group: type: string description: NUCC grouping of the primary specialty. example: "Allopathic & Osteopathic Physicians" credentials: type: array items: type: string description: Credentials reported to the registry. example: ["MD"] is_sole_proprietor: type: boolean description: Whether the provider is registered as a sole proprietor. example: false enumeration_date: type: string format: date description: Date the NPI was issued. example: "2008-04-02" last_updated_date: type: string format: date description: Date the provider last updated the registry record. example: "2026-05-15" snapshot_date: type: string format: date description: Date of the registry snapshot this record comes from. example: "2026-11-02" taxonomies: type: array description: Specialties reported to the registry, one entry per specialty and license state. items: type: object properties: code: type: string description: NUCC taxonomy code. example: "207LP3000X" display_name: type: string example: "Pediatric Anesthesiology Physician" classification: type: string example: "Anesthesiology" specialization: type: string example: "Pediatric Anesthesiology" taxonomy_group: type: string example: "Allopathic & Osteopathic Physicians" is_primary: type: boolean description: Whether this is the provider's primary specialty. example: true license_state: type: string description: Two-letter code of the state that issued the license reported with this specialty. example: "TX" license_number: type: string description: License number reported with this specialty. example: "P0303" licenses: type: array description: Distinct state licenses reported to the registry. items: type: object properties: state_code: type: string description: Two-letter code of the issuing state. example: "TX" license_number: type: string example: "P0303" Profile: type: object description: Structured profile of the candidate based on StrictProfile schema. properties: docid: type: string description: Unique document ID of the candidate profile. For a registry record from the `healthcare` source (beta), it is `npi:`. example: "jason-tysl" linkedin_slug: type: string nullable: true description: LinkedIn profile slug/identifier. This is the part that comes after `https://www.linkedin.com/in/` in the profile URL. Because index freshness varies, the slug may not always resolve to a publicly visible profile. If fully up-to-date data is critical, enable the high_freshness parameter. Null for registry records from the `healthcare` source. example: "jason-tysl" npi: type: string nullable: true description: National Provider Identifier of a US healthcare provider. Set on registry records from the `healthcare` source (beta). example: "1023555992" sources: type: array items: type: string description: Data sources this search result comes from, such as `linkedin` or `healthcare`. Returned on `/v2/search` results. example: ["healthcare"] healthcare: $ref: '#/components/schemas/HealthcareInfo' first_name: type: string description: First name of the candidate. example: "Jason" middle_name: type: string description: Middle name of the candidate. example: "Michael" last_name: type: string description: Last name of the candidate. example: "Tysl" picture_url: type: string description: URL to the candidate's profile picture. example: "https://example.com/profile.jpg" title: type: string description: Current job title or headline. example: "Software Engineer II" summary: type: string description: Professional summary or bio. example: "Experienced software engineer with expertise in..." gender: type: string description: 'Gender of the candidate. As of now only two genders are supported: male, female' enum: - male - female example: "male" is_decision_maker: type: number description: Whether the candidate is a decision maker in their organization 0 means no, 1 means yes. example: 1. languages: type: array description: List of languages the candidate knows with proficiency levels. items: $ref: '#/components/schemas/Language' inferred_languages: type: array description: Languages inferred from the candidate's profile with proficiency levels. items: $ref: '#/components/schemas/Language' location: type: string description: Current location of the candidate. example: "Bristol, England, United Kingdom" location_coordinates: type: object description: Coordinates of the candidate's current location, when available. properties: lng: type: number format: double example: -2.6 lat: type: number format: double example: 51.5 country_code: type: string description: Country code associated with the coordinates, when available. example: "GB" location_country_code: type: string description: ISO 3166-1 alpha-2 country code of the candidate's current location. example: "GB" location_regions: type: array description: Geographic regions associated with the candidate's current location. items: type: string example: ["Europe", "EMEA"] is_top_universities: type: boolean description: Whether the candidate attended a top university. example: true is_opentowork: type: boolean description: Whether the candidate is open to work opportunities. Only when realtime profiles are enabled. This field is only available for profiles that opened their "open to work" status publicly. example: false is_hiring: type: boolean description: Whether the candidate is currently hiring. Only when realtime profiles are enabled. example: false total_experience_years: type: number description: Total years of professional experience. example: 3.5 estimated_age: type: number description: Estimated age of the candidate. example: 28.0 expertise: type: array description: Areas of expertise or skills. items: type: string example: ["Python", "Machine Learning", "Software Engineering"] has_emails: type: boolean description: Whether the candidate has any email addresses available. example: true emails: type: array description: List of all email addresses associated with the candidate. items: type: string example: ["jtysl@agileblue.com", "jason.tysl@gmail.com"] best_personal_email: type: string description: Best personal email address for the candidate. example: "jason.tysl@gmail.com" best_business_email: type: string description: Best business email address for the candidate. example: "jtysl@agileblue.com" personal_emails: type: array description: List of personal email addresses. items: type: string example: ["jason.tysl@gmail.com"] business_emails: type: array description: List of business email addresses. items: type: string example: ["jtysl@agileblue.com"] has_phone_numbers: type: boolean description: Whether the candidate has any phone numbers available. example: true phone_numbers: type: array description: List of phone numbers associated with the candidate. items: type: string example: ["+1-555-123-4567"] phone_types: type: array description: List of phone number types available for the candidate. items: type: string enum: - mobile example: ["mobile"] websites: type: array description: List of social profile URLs found during phone or email enrichment. items: type: string example: ["https://twitter.com/johndoe", "https://github.com/johndoe"] followers_count: type: integer description: Number of followers on LinkedIn. example: 150 connections_count: type: integer description: Number of connections on LinkedIn. example: 500 experiences: type: array description: List of professional work experiences grouped by company. items: $ref: '#/components/schemas/CompanyExperienceGroup' educations: type: array description: List of educational experiences. items: $ref: '#/components/schemas/Education' awards: type: array description: List of awards or recognitions received. items: type: string example: ["The Morrill Scholarship Program"] certifications: type: array description: List of certifications. items: $ref: '#/components/schemas/Certification' recommendations: type: array description: LinkedIn recommendations colleagues wrote about this person. items: $ref: '#/components/schemas/Recommendation' activities: type: array description: LinkedIn posts the person wrote or reposted, as truncated snippets. Liked posts written by others are not returned. items: $ref: '#/components/schemas/Activity' memberships: type: array description: List of professional memberships. items: type: object description: Membership object with flexible structure. additionalProperties: true patents: type: array description: List of patents. items: $ref: '#/components/schemas/Patent' publications: type: array description: List of publications. items: type: object description: Publication object with flexible structure. additionalProperties: true ScoredProfile: type: object description: A single search result object containing candidate profile and analysis properties: docid: type: string description: Unique document ID of the candidate profile. example: "jason-tysl" insights: type: object description: Analysis and insights relevant to the query. properties: overall_summary: type: string description: General summary of the candidate's fit for the role. example: "Jason Tysl is qualified engineer with 3+ years of experience." query_insights: type: array description: Insights derived from the query, broken down by subquery. items: type: object properties: match_level: type: string description: 'The degree to which the candidate matches the requirement: Exceeds Expectations,Meets Expectations,Partially Meets,Insufficient Data,Does Not Meet' example: "Exceeds Expectations" priority: type: string description: 'Indicates how important this subquery: Essential, Important, Optional' example: "Essential" short_rationale: type: string description: Concise version of the rationale. example: "3+ years as a SWE" rationale: type: string description: Full version of the rationale. example: "3+ years as a Software Engineer" subquery: type: string description: Specific subquery analyzed for this insight. example: "software engineer" short_quotes: type: array description: Short quotes from the candidate's profile. items: type: string example: "I have 3+ years of experience in software development." score: type: integer description: | Coarse candidate relevance grade from 1 to 4, returned independently of `profile_scoring` in Fast and Pro. It is not the full ranking value or a match percentage. Fast's current binary scoring path assigns 4 to candidates that pass all mandatory requirements and rejects candidates that fail one (grade 1). Accepted candidates can therefore all have grade 4 while their internal ranking scores differ. Optional requirements can influence ranking without changing this grade. Other scoring paths can produce intermediate grades: 3 indicates partial mandatory-requirement alignment, and 2 can identify a low-confidence fill result. The grade alone is not a universal quality threshold across search modes. Preserve the API's returned order rather than re-ranking by this field. example: 4 enum: [1, 2, 3, 4] credits_charged: type: integer description: Credits charged for this search result. example: 5 profile: $ref: '#/components/schemas/Profile' outreach_message: type: string description: Personalized outreach message for the candidate. example: "Hi Jason, I noticed your expertise in Python and machine learning..." CompanyLeadResult: type: object description: A company search result with associated leads properties: company: $ref: '#/components/schemas/CompanyInfo' leads: type: array description: List of leads found within this company. items: $ref: '#/components/schemas/ScoredProfile' score: type: number format: float description: Relevance score for the company match (0..100). 100 means the company is a perfect match for the query. example: 85 ApiCallHistoryEntry: type: object description: A single API call history entry representing a previous API call properties: uuid: type: string description: Unique identifier for the API call example: "ec191bf9-99ff-4989-8383-c97c71fafb6d" thread_id: type: string description: Thread identifier for the API call example: "thread_abc123" path: type: string description: The API endpoint path that was called example: "/v2/search" parameters: type: object description: The parameters that were sent with the API call additionalProperties: true example: {"query": "software engineer", "limit": 10, "type": "pro"} items_count: type: integer description: Number of items returned in the search results example: 15 created_at: type: string format: date-time description: ISO 8601 timestamp when the API call was made example: "2024-01-15T10:30:00Z" response_time: type: number format: float description: Response time in seconds for the API call example: 2.45 response_status: type: integer description: HTTP response status code example: 200 error_message: type: string description: Error message if the API call failed example: "Invalid query parameter" task_status: type: string description: Status of the task (for async endpoints). Valid values are `pending`, `completed`, `failed`. example: "completed" credits_used: type: integer description: Number of credits used for the API call example: 10 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT security: - bearerAuth: []