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. 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//data Scope: sources:read Paginated rows imported into the created source. `` 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//sync Scope: sources:write Connects the created source to a workflow and (by default) backfills it with the source's current rows. `` here is the UUID returned by Create. Body: { workflow_id, field_mapping, push_existing?, run? } — `field_mapping` keys are `input.` 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": "", "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": "", "name", "created_at" }} Step 2b — (Optional) Poll imported rows while the backfill runs GET /api/v1/sources//data?page_no=1&page_size=20 ( = UUID from Step 2) Step 3 — Sync the source into a workflow POST /api/v1/sources//sync ( = the UUID from Step 2 ) Build `field_mapping`: a. GET /api/v1/workflows → pick the destination workflow_id. b. GET /api/v1/workflows//sheets//inputs → each input has a `reference` like `{{input.website}}`. c. Map each workflow input (reference WITHOUT braces) to a source field. Body: { "workflow_id": "", "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