DatabaseLeadSearchRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/generect-com/json-schema/generect-com-database-lead-search-request-schema.json",
  "title": "DatabaseLeadSearchRequest",
  "x-generated": "2026-11-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/generect-com-openapi.yaml#/components/schemas/DatabaseLeadSearchRequest",
  "allOf": [
    {
      "$ref": "#/$defs/LeadSearchRequest"
    },
    {
      "type": "object",
      "properties": {
        "detail": {
          "type": "string",
          "enum": [
            "full",
            "thin"
          ],
          "default": "full",
          "description": "Row shape. `full` (the default) returns full rows, billed per row. `thin` returns who, what role, where and which company at no charge, up to a daily quota per account (currently 2,000 rows per UTC day); a thin row has no LinkedIn profile URL, company domain, contacts or work history. A spent quota is refused with `429` until 00:00 UTC, never billed. Accounts on a custom API contract get `400` unless their contract includes thin search. The count endpoints ignore this field: counts are always free."
        },
        "limit_by": {
          "type": "integer",
          "default": 100,
          "description": "Maximum number of leads to return. Without it, a search returns 100 rows: `results_count` is the whole match, and `offset_by` reaches the rest. For filter-only searches (no company_id/company_link/company_name) the maximum is 2400."
        },
        "gender": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "male",
              "female",
              "unknown"
            ]
          },
          "description": "Gender of the lead; a lead is included if it matches at least one value. Case-insensitive; any other value is rejected with `400`. Gender is inferred from the lead's name, so it is an estimate, and a lead whose name does not point to one is `unknown`. To leave a gender out, list the others — e.g. `[\"female\", \"unknown\"]`.\n\nDatabase mode only. LinkedIn search has no gender facet, so realtime search rejects this field rather than accepting it and returning a wider result set than you asked for.\n\nCoverage matters here: gender is known for roughly a third of leads, and the rest are `unknown`. Filtering by `male` or `female` therefore also drops leads whose gender simply is not known, not only those of the other gender."
        }
      }
    }
  ],
  "$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."
        }
      }
    }
  }
}