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.

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.

Last updated: 2026-06-02.