SOURCE_ID: find_companies_from_sales_navigator
NAME: Companies from Sales Navigator
CATEGORY: List Building

Build a static list of companies using LinkedIn Sales Navigator filters or
by pasting a Sales Navigator company search URL. Imported records become
available to your Floqer workflows for enrichment, scoring, and outreach.

INDEX:
  1. Endpoints
  2. Search model
  3. Import lifecycle (one-time only)
  4. Body shape (preview + create)
  5. Filter fields catalogue
  6. Dynamic options
  7. How to configure end-to-end
  8. Key notes
  9. Where it fits
 10. When to use

================================================================================
1. ENDPOINTS
================================================================================

Source identifier (used in every endpoint path):
`find_companies_from_sales_navigator`.

  POST /api/v1/sources/find_companies_from_sales_navigator/preview
    Scope: sources:read
    Returns up to 25 companies that WOULD be imported for the given search,
    without creating anything. Use this to validate filters or a search
    URL before committing.

  POST /api/v1/sources/find_companies_from_sales_navigator
    Scope: sources:write
    Creates the source and queues an import of matching companies (up to
    `max_count`). Returns `source_instance_id` (the new source's UUID). The import
    runs asynchronously.

  POST /api/v1/sources/find_companies_from_sales_navigator/options/:field_name
    Scope: sources:read
    Autocomplete values for region-style filters. Supported field name:
    `company_headquarters`. Pass search text in
    `context.search` (returns empty options when omitted).

  GET /api/v1/sources/<source_instance_id>/data
    Scope: sources:read
    Paginated rows imported into the created source.

  POST /api/v1/sources/<source_instance_id>/sync
    Scope: sources:write
    Connects the created source to a workflow and backfills rows.

No OAuth connection is required.

================================================================================
2. SEARCH MODEL
================================================================================

Every preview/create call uses ONE of two mutually exclusive modes:

  filters (default)
    Pass a `filters` array of Sales Navigator filter objects, OR
    pass flat `payloads` in the same shape (see section 4).

  sales_nav_url
    Pass a LinkedIn Sales Navigator company search URL copied from the
    browser after running a search in Sales Navigator.

You cannot send both `filters` and `sales_nav_url` in the same request.

================================================================================
3. IMPORT LIFECYCLE (ONE-TIME ONLY)
================================================================================

This is a static, one-shot list import — not a recurring monitor.

  1. Preview (optional) — validate filters / URL and inspect row shape.
  2. Create — starts the import of matching companies.
  3. Poll GET /api/v1/sources/<source_instance_id>/data until rows arrive.
  4. Sync — connect the source UUID to a workflow.

Credits: 1 credit per company imported.

================================================================================
4. BODY SHAPE (PREVIEW + CREATE)
================================================================================

── Filters mode (filter array) ───────────────────────────────────────────────

{
  "type": "filters",
  "filters": [
    {
      "filter_type": "company_headquarters",
      "operator": "in",
      "values": ["San Francisco Bay Area"]
    },
    {
      "filter_type": "industry",
      "operator": "in",
      "values": ["Software Development"]
    }
  ]
}

── Filters mode (flat payloads — same fields, key/value form) ────────────────

{
  "type": "filters",
  "payloads": {
    "company_headquarters_in": ["San Francisco Bay Area"],
    "company_headquarters_in_operator": "in",
    "industry_in": ["Software Development"],
    "industry_in_operator": "in"
  }
}

Include/exclude fields use `_in` / `_not_in` suffix keys. Range filters with
sub-filters (department headcount, annual revenue) use `{min, max}` objects
plus a `{filterKey}_subfilter` companion key.

── URL mode ──────────────────────────────────────────────────────────────────

{
  "type": "sales_nav_url",
  "sales_nav_url": "https://www.linkedin.com/sales/search/company?query=..."
}

── Create-only fields ────────────────────────────────────────────────────────

  name        (required) Display name for the new source.
  max_count   (optional) Companies to import. Default 25, max 15000. Accepts
              integer or numeric string (e.g. "100").

================================================================================
5. FILTER FIELDS CATALOGUE
================================================================================

Company Filters group
  company_headcount              Preset ranges: "1-10", "11-50", "51-200", ...
  company_headcount_growth       Percentage range (operator: between)
  company_headquarters           Region names (use options endpoint)
  industry                       Industry names (include/exclude)
  number_of_followers            "1-50", "51-100", "101-1000", ...
  fortune                        Fortune 500 tiers
  department_headcount           Range + department sub_filter (required)
  department_headcount_growth    Percentage range + department sub_filter
  annual_revenue                 Range + currency sub_filter (USD, EUR, ...)

Spotlights group
  job_opportunities              "Hiring on Linkedin"
  recent_activities              "Senior leadership changes...", "Funding events..."
  keywords                       Description keyword (single value)

================================================================================
6. DYNAMIC OPTIONS
================================================================================

  POST .../options/company_headquarters
    Body: { "context": { "search": "london" } }
    Returns autocomplete region names for HQ include/exclude pickers.

Companies do not expose a `location` options endpoint (person-only filter).

================================================================================
7. HOW TO CONFIGURE END-TO-END
================================================================================

  1. Autocomplete HQ regions via options/company_headquarters.
  2. Preview with filters or sales_nav_url.
  3. Create with name + max_count.
  4. Poll GET /api/v1/sources/<source_instance_id>/data.
  5. Sync to a workflow.

================================================================================
8. KEY NOTES
================================================================================

- Company search URLs must match `/sales/search/company`.
- Larger imports run asynchronously; rows arrive over time as the import
  progresses.
- Invalid URLs return HTTP 400, not 500.

================================================================================
9. WHERE IT FITS
================================================================================

Static list-building source for LinkedIn Sales Navigator company search.
Pairs with workflow enrichment actions (firmographics, LinkedIn enrich,
etc.) via source sync.

================================================================================
10. WHEN TO USE
================================================================================

Use when you need account lists from Sales Navigator company search —
targeting by headcount, industry, HQ, department size, revenue, or by
importing an existing SN company search URL.

================================================================================

This file is maintained manually. Last updated: 2026-06-02.
Full interactive reference: https://floqer.com/docs/reference