{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://artifacts.apis.io/generect-com/json-schema/generect-com-realtime-lead-search-request-schema.json", "title": "RealtimeLeadSearchRequest", "x-generated": "2026-11-09", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/generect-com-openapi.yaml#/components/schemas/RealtimeLeadSearchRequest", "allOf": [ { "$ref": "#/$defs/LeadSearchRequest" }, { "type": "object", "properties": { "personas": { "type": "array", "description": "List of persona tuples. Each persona: [name, functions, seniorities, prohibits, priority?].", "items": { "type": "array" } }, "first_name": { "type": "array", "items": { "type": "string" }, "description": "Exact first names to match; a lead is included if their first name matches at least one." }, "last_name": { "type": "array", "items": { "type": "string" }, "description": "Exact last names to match; a lead is included if their last name matches at least one." }, "lead_industries": { "type": "array", "items": { "type": "string" }, "description": "Industries of the lead themselves (their own profile industry), as opposed to company_industries, which filters by the employer's industry." }, "exclude_lead_industries": { "type": "array", "items": { "type": "string" }, "description": "Lead industries to exclude." }, "past_job_titles": { "type": "array", "items": { "type": "string" }, "description": "Titles the lead held in a previous role; a lead is included if their history matches at least one." }, "exclude_functions": { "type": "array", "items": { "type": "string" }, "description": "Job functions to exclude — same value set as functions." }, "past_company_ids": { "type": "array", "items": { "type": "string" }, "description": "LinkedIn company IDs the lead previously worked at; ID-based counterpart of past_company_names." }, "exclude_past_company_ids": { "type": "array", "items": { "type": "string" }, "description": "Skip leads who previously worked at these LinkedIn company IDs." }, "exclude_current_company_ids": { "type": "array", "items": { "type": "string" }, "description": "Skip leads currently working at these LinkedIn company IDs." }, "groups_keywords": { "type": "array", "items": { "type": "string" }, "description": "Resolve LinkedIn groups by name instead of by numeric ID — each keyword is matched against group names and the matches are added to groups." }, "years_of_experience": { "type": "array", "items": { "type": "integer" }, "description": "Total years of work experience: 1 = under 1y, 2 = 1-2y, 3 = 3-5y, 4 = 6-10y, 5 = 10y+." }, "num_of_connections": { "type": "object", "description": "Connection-count range applied to the lead's profile. Leads outside the range are dropped from the results.", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } } }, "mentioned_in_news": { "type": "boolean", "description": "Filter for leads recently mentioned in the news.", "default": false }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Free-text keywords searched across lead profiles (headline, current job description, skills, summary); a lead is included if their profile contains at least one. Realtime mode only — database mode does not support free-text search. Examples: \"machine learning\", \"growth marketing\", \"kubernetes\"." }, "functions": { "type": "array", "items": { "type": "string" }, "description": "Job functions — categorize roles by business area, independent of seniority or title; a lead is included if their function matches at least one. Common values: Sales, Marketing, Engineering, Operations, Finance, HR, Product, Customer Success, Legal, Data. Combine with seniorities for function-by-seniority targeting." }, "past_company_names": { "type": "array", "items": { "type": "string" }, "description": "Filter by companies where the lead previously worked; a lead is included if their work history contains at least one. Useful for alumni outreach (e.g. ex-Google engineers) or targeting people who left a competitor. Examples: \"Google\", \"Meta\", \"Stripe\"." }, "schools": { "type": "array", "items": { "type": "integer" }, "description": "School IDs to filter by." }, "groups": { "type": "array", "items": { "type": "integer" }, "description": "LinkedIn group IDs to filter by." }, "years_in_position": { "type": "array", "items": { "type": "integer" }, "description": "Time in current position: 1 = under 1y, 2 = 1-2y, 3 = 3-5y, 4 = 6-10y, 5 = 10y+." }, "years_in_company": { "type": "array", "items": { "type": "integer" }, "description": "Time at current company: 1 = under 1y, 2 = 1-2y, 3 = 3-5y, 4 = 6-10y, 5 = 10y+." }, "changed_jobs": { "type": "boolean", "description": "Filter for leads who recently changed jobs.", "default": false }, "posted_on_linkedin": { "type": "boolean", "description": "Filter for leads who recently posted on LinkedIn.", "default": false }, "linkedin_filter_link": { "type": "string", "description": "Pre-built LinkedIn or Sales Navigator search URL to extract filters from." }, "include_full_profile": { "type": "boolean", "default": false, "description": "Return the complete lead profile instead of the standard field set — roughly thirty extra fields, including skills, industry and social links. Priced as one lead enrichment per returned lead, charged on top of the search itself, so a request that returns N leads is billed twice: once for the search and once for the profiles. Each returned lead carries `is_full_data` so you can confirm what you received." }, "find_by_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Find the people behind these known addresses, up to 500 per request. Every address must share one domain: that domain is used as the company anchor, so the request resolves to leads at that company and cannot be combined with an unanchored search. Realtime only." }, "include_total_count": { "type": "boolean", "default": false, "description": "Include `results_count` in the response; without it the response carries only the page itself. The figure is an estimate, not an exact total. For a search anchored to one company it may come back as the string `\"within limit\"` rather than a number, meaning the whole match set fits inside the page you asked for — handle both types. A filter-only search reports `results_count` anyway, without this flag." }, "max_profiles_scanned": { "type": "integer", "description": "Hard ceiling on how many profiles the search opens while assembling results. Bounds the time and cost of a broad query; a `limit_by` above this value is lowered to it. Unset means no ceiling." } } } ], "$defs": { "LeadSearchRequest": { "type": "object", "properties": { "job_titles": { "type": "array", "items": { "type": "string" }, "description": "Job titles held by the people you want to find. A lead only needs to match one of the titles you provide — adding more expands your search. Results may also include similar titles (e.g. \"marketing manager\" can return \"content marketing manager\"). Combine with seniorities to target both function and level. Examples: \"sales development representative\", \"marketing manager\", \"software engineer\"." }, "seniorities": { "type": "array", "items": { "type": "string" }, "description": "Job seniority levels at the lead's current employer (current position only, not previous roles). A lead needs to match at least one; adding more values expands your search. Allowed values: owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern. Combine with job_titles to narrow targeting." }, "locations": { "type": "array", "items": { "type": "string" }, "description": "Geographic locations where leads currently live — matches across cities, states/regions and countries. A lead needs to match at least one. To filter by the employer's HQ location, use company_locations. Examples: \"San Francisco, California, United States\", \"Germany\", \"London\"." }, "exclude_locations": { "type": "array", "items": { "type": "string" }, "description": "Locations to exclude from results." }, "company_locations": { "type": "array", "items": { "type": "string" }, "description": "Headquarters location of the lead's current employer; a lead is included if their company's HQ matches at least one. Filters by where the company is based — distinct from locations, which is where the lead personally lives." }, "exclude_company_locations": { "type": "array", "items": { "type": "string" }, "description": "Company locations to exclude." }, "company_industries": { "type": "array", "items": { "type": "string" }, "description": "Industries of the lead's current employer; a lead is included if their company matches at least one. Values follow LinkedIn's industry taxonomy. Examples: \"Software Development\", \"Financial Services\", \"Information Technology\"." }, "exclude_company_industries": { "type": "array", "items": { "type": "string" }, "description": "Company industries to exclude." }, "company_headcounts": { "type": "array", "items": { "type": "string" }, "description": "Size of the lead's current employer, as employee-count ranges; a lead is included if their company falls into at least one. Allowed values: \"1-10\", \"11-50\", \"51-200\", \"201-500\", \"501-1000\", \"1001-5000\", \"5001-10000\", \"10 000+\"." }, "exclude_company_headcounts": { "type": "array", "items": { "type": "string" }, "description": "Company size ranges to exclude." }, "company_types": { "type": "array", "items": { "type": "string" }, "description": "Company types: \"Public Company\", \"Privately Held\", \"Non Profit\", \"Government Agency\", \"Educational\", \"Self Employed\", \"Partnership\", \"Self Owned\"." }, "company_name": { "type": "string", "description": "Target company name (mutually exclusive with company_link and company_id)." }, "company_link": { "type": "string", "description": "LinkedIn company URL (mutually exclusive with company_name and company_id)." }, "company_id": { "type": "integer", "description": "LinkedIn company numeric ID (mutually exclusive with company_name and company_link)." }, "exclude_names": { "type": "array", "items": { "type": "string" }, "description": "Skip leads by full name." }, "exclude_ids": { "type": "array", "items": { "type": "string" }, "description": "Skip leads by Sales Navigator ID." }, "filter_empty_vars": { "type": "array", "items": { "type": "string" }, "description": "Skip leads where these fields are empty. Options: job_started_on, profile_photo, started_at_position, company_website." }, "limit_by": { "type": "integer", "description": "Maximum number of leads to return. For filter-only searches (no company_id/company_link/company_name) the maximum is 2400." }, "offset_by": { "type": "integer", "description": "Number of leads to skip (for pagination). For filter-only searches the maximum is 2399." }, "strict": { "type": "array", "items": { "type": "string" }, "description": "Fields to apply strict matching on (e.g. \"company_locations\")." }, "skip_truncated_names": { "type": "boolean", "default": false, "description": "Drop leads whose first or last name is a single character or empty. LinkedIn abbreviates surnames for members who restrict their profile, so these rows carry a name that cannot be personalised. Applies to both database and realtime search." } } } } }