SOURCE_ID: find_companies_by_buying_intent
NAME: Find Companies by Buying Intent
CATEGORY: List Building

Build a static list of companies showing active research/buying intent
around one or more topics. Imported records become available to your
Floqer workflows for enrichment, scoring, outreach, and the like.

INDEX:
  1. Endpoints
  2. Body shape (preview + create)
  3. Filter fields catalogue
  4. Dynamic options
  5. How to configure end-to-end
  6. Key notes
  7. When to use

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

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

  POST /api/v1/sources/find_companies_by_buying_intent/preview
    Scope: sources:read
    Returns a sample of companies (up to 50) that WOULD be imported for the
    given filters, without creating anything. Use this to validate the
    topics and intent level before committing. `metadata.total_results`
    reports the full match count.

  POST /api/v1/sources/find_companies_by_buying_intent
    Scope: sources:write
    Creates the source and starts a one-time import of matching companies
    (up to `max_count`). Returns `source_instance_id` (the new source's UUID). The
    import runs asynchronously.

  GET /api/v1/sources/<source_instance_id>/data
    Scope: sources:read
    Paginated rows imported into the created source. `<source_instance_id>` is the
    UUID returned by Create. Query: `page_no`
    (default 1), `page_size` (default 20, max 200). Source-agnostic;
    see concepts.txt §10.

  POST /api/v1/sources/<source_instance_id>/sync
    Scope: sources:write
    Connects the created source to a workflow and (by default) backfills
    it with the source's current rows. `<source_instance_id>` here is the UUID
    returned by Create. Body: { workflow_id, field_mapping, push_existing?,
    run? } — `field_mapping` keys are `input.<field>` references on the
    target workflow, values are the source fields to pull. This step is
    source-agnostic; see concepts.txt §10 for the full shape.

No connection is required. There is no dynamic-options endpoint for this
source (see §4).

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

Find Companies by Buying Intent is always a one-time static import — there
is no `pull_mode`, `schedule`, or recurring re-pull. `max_count` caps the
import size.

Preview accepts (all snake_case):
  filters              required: object; at least one topic is required (see §3)
  max_count            optional: integer | string; ignored on preview

Create accepts all the preview fields plus:
  name                 required: display name for the new source
  max_count            optional: cap on rows imported; default 100. Hard max 60000.

The `filters` object recognizes: `topics` (or `business_intent_topics`),
`topic_intent_level`, and `negate`. At least one topic is required — a
preview or create with no topics is rejected.

Example create body:

  {
    "name": "Companies researching CRM software",
    "max_count": 2000,
    "filters": {
      "topics": ["CRM software", "Sales automation"],
      "topic_intent_level": "high",
      "negate": false
    }
  }

Preview response envelope:

  {
    "status": 200,
    "data": {
      "data": [
        { "name": "Acme Corporation", "domain": "acme.com", "country": "United States", ... }
      ],
      "metadata": { "total_results": 4321 }
    }
  }

  Rows are plain key/value objects describing each company (name, domain,
  location, firmographics). Preview returns up to 50 rows;
  `metadata.total_results` is the full match count.

Create response envelope:

  {
    "status": 201,
    "data": {
      "source_instance_id": "<uuid>",
      "name": "Companies researching CRM software",
      "created_at": "2026-06-02T12:00:00.000Z"
    }
  }

================================================================================
3. FILTER FIELDS CATALOGUE
================================================================================

All filter keys live inside the `filters` object. Only these keys are
recognized:

  topics (string[])   REQUIRED (alias: business_intent_topics)
    The buying-intent topics to target — the subjects companies are
    actively researching. At least one is required. Multiple topics are
    OR-combined (a company matching ANY topic qualifies). Pass either
    `topics` or `business_intent_topics`; if both are present, `topics`
    takes precedence.
    Examples: ["CRM software"]  |  ["Cybersecurity", "SIEM", "Zero trust"]

  topic_intent_level (string)   optional
    Minimum intent strength a company must show on the topic(s). Higher
    levels narrow the list to companies showing stronger/more recent
    research activity.
    Typical values: "low" | "medium" | "high".

  negate (boolean)   optional
    When true, INVERTS the topic match — returns companies that do NOT
    show intent on the given topics. Default false.

Examples:

  Companies with high intent on CRM software:
    { "filters": {
        "topics": ["CRM software"],
        "topic_intent_level": "high"
      } }

  Companies researching any of several security topics:
    { "filters": {
        "topics": ["Cybersecurity", "SIEM", "Zero trust"]
      } }

  Companies NOT showing intent on a topic (exclusion list):
    { "filters": {
        "topics": ["Marketing automation"],
        "negate": true
      } }

================================================================================
4. DYNAMIC OPTIONS
================================================================================

No dynamic-options endpoint is registered for this source. `topics` is
free text — pass the topic names you want to target and preview to confirm
they resolve to companies. `topic_intent_level` is a small fixed
enumeration (low / medium / high).

================================================================================
5. HOW TO CONFIGURE END-TO-END
================================================================================

  Step 1 — Preview before committing
    POST /api/v1/sources/find_companies_by_buying_intent/preview
    Body:
      { "filters": { "topics": ["CRM software"], "topic_intent_level": "high" } }
    Check `data[]` and `metadata.total_results`. Adjust topics / intent
    level until you're happy — preview never creates anything.

  Step 2 — Create the source
    POST /api/v1/sources/find_companies_by_buying_intent
    Body:
      { "name": "Companies researching CRM software",
        "max_count": 2000,
        "filters": { "topics": ["CRM software"], "topic_intent_level": "high" } }
    Set `max_count` ≤ the Preview `metadata.total_results` (hard max 60000).
    Default is 100 when omitted.
    Response: { "status": 201, "data": { "source_instance_id": "<uuid>", "name", "created_at" }}

  Step 2b — (Optional) Poll imported rows while the backfill runs
    GET /api/v1/sources/<source_instance_id>/data?page_no=1&page_size=20
      (<source_instance_id> = UUID from Step 2)

  Step 3 — Sync the source into a workflow
    POST /api/v1/sources/<source_instance_id>/sync          ( <source_instance_id> = the UUID from Step 2 )
    Build `field_mapping`:
      a. GET /api/v1/workflows  → pick the destination workflow_id.
      b. GET /api/v1/workflows/<workflow_id>/sheets/<workflow_id>/inputs
         → each input has a `reference` like `{{input.website}}`.
      c. Map each workflow input (reference WITHOUT braces) to a source field.
    Body:
      { "workflow_id": "<uuid>",
        "field_mapping": { "input.company_name": "name", "input.website": "domain" },
        "push_existing": true,
        "run": "all" }
    See concepts.txt §10 for the full sync semantics (source-agnostic).

The initial import runs asynchronously — Create returns once the source is
created and the import has started, not when records have finished arriving.

================================================================================
6. KEY NOTES
================================================================================

- No connection required. This endpoint does NOT return 424.

- At least one topic is required (`topics` or `business_intent_topics`). A
  preview or create with no topics is rejected.

- Multiple topics are OR-combined. Set `topic_intent_level` to narrow to
  companies showing stronger intent; set `negate: true` to invert and build
  an exclusion list.

- One-time static import. There is no `pull_mode` or `schedule`; re-run
  Create for a fresh pull. `max_count` defaults to 100, hard max 60000;
  set it ≤ the Preview `metadata.total_results`.

- Preview does not import anything and does not consume credits. Create
  starts the real import and consumes credits; insufficient balance → 402.

- Total counts are best-effort. `metadata.total_results` may lag slightly.

================================================================================
7. WHEN TO USE
================================================================================

- Intent-based prospecting: "Companies actively researching CRM software":
  filters: topics + topic_intent_level: "high".

- Multi-topic category targeting: "Companies researching anything in our
  security category": filters: topics (several values).

- Suppression list: "Companies NOT showing intent on X":
  filters: topics + negate: true.

- Combine with Sync to enrich + score + reach out to each company in a
  workflow while intent is fresh.

When you want to build a list from firmographics/technographics rather than
research intent, use `find_companies` (firmographic filters) or
`find_companies_by_tech_stack` (technology filter).

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

Last updated: 2026-06-02. Reference: https://floqer.com/docs/reference