SOURCE_ID: find_companies_by_tech_stack NAME: Find Companies by Tech Stack CATEGORY: List Building Build a static list of companies that use a given technology on their website, optionally narrowed by country and first-detected date. 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_tech_stack`. POST /api/v1/sources/find_companies_by_tech_stack/preview Scope: sources:read Returns a sample of companies (up to 30) that WOULD be imported for the given filters, without creating anything. Use this to validate the technology spelling and filter combination before committing. `metadata.total_results` reports the estimated total coverage. POST /api/v1/sources/find_companies_by_tech_stack 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 Tech Stack 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; `tech` 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, max 60000 The `filters` object has only three recognized keys: `tech` (required), `country` / `countries`, and `since`. `tech` is required — a preview or create with no technology is rejected. Example create body: { "name": "US companies using Shopify", "max_count": 5000, "filters": { "tech": "Shopify", "countries": ["US", "CA"], "since": "2025-01-01" } } Preview response envelope: { "status": 200, "data": { "data": [ { "domain": "acme.com", "website": "https://www.acme.com", "name": "Acme Corporation", "city": "San Francisco", "state": "CA", "country": "US", "vertical": "Software", "tech": "Shopify" } ], "metadata": { "total_results": 240000 } } } Rows are plain key/value objects: domain, website, name, city, state, country, vertical, and the matched `tech`. Preview returns up to 30 rows; `metadata.total_results` is the estimated total companies running the technology (live coverage), so it is typically much larger than the preview sample. Create response envelope: { "status": 201, "data": { "source_instance_id": "", "name": "US companies using Shopify", "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: tech (string | string[]) REQUIRED The technology to match (the product/tool detected on the company's website). Free text; spelling is normalized server-side (e.g. "google analytics" → "Google-Analytics"). Accepts a string or an array. NOTE: the company list is built from the FIRST technology in the array; when you pass multiple values, the additional entries widen the reported `total_results` coverage estimate but the imported companies come from the first technology. To target several technologies, create one source per technology. Examples: "Shopify" | ["Salesforce"] | "Google Analytics" country (string | string[]) optional countries (string | string[]) optional (alias of `country`) Restrict to companies in these countries. Accepts ISO-3166 alpha-2 codes ("US", "GB") or full country names (resolved to ISO-2 server-side); "UK" is accepted. Multiple countries are OR-combined. Examples: "US" | ["US", "CA"] | "United Kingdom" since (string) optional Only include companies first detected running the technology on/after this date. ISO date string (YYYY-MM-DD). Example: "2025-01-01" Examples: Companies running Shopify, US + Canada, detected since 2025: { "filters": { "tech": "Shopify", "countries": ["US", "CA"], "since": "2025-01-01" } } Companies running HubSpot (worldwide): { "filters": { "tech": "HubSpot" } } ================================================================================ 4. DYNAMIC OPTIONS ================================================================================ No dynamic-options endpoint is registered for this source. `tech` is free text — pass the technology/product name and let the server normalize it; preview to confirm the spelling resolves to results. Country values are ISO-3166 alpha-2 codes (or full names). `since` is a free date. ================================================================================ 5. HOW TO CONFIGURE END-TO-END ================================================================================ Step 1 — Preview before committing POST /api/v1/sources/find_companies_by_tech_stack/preview Body: { "filters": { "tech": "Shopify", "countries": ["US"] } } Check `data[]` (confirm the tech matched real companies) and `metadata.total_results` (coverage estimate). Adjust the spelling / country until you're happy — preview never creates anything. Step 2 — Create the source POST /api/v1/sources/find_companies_by_tech_stack Body: { "name": "US companies using Shopify", "max_count": 5000, "filters": { "tech": "Shopify", "countries": ["US"] } } Set `max_count` to how many companies you actually want imported (the total coverage can be very large). 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": "website" }, "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. - `tech` is required. A preview or create with no technology is rejected. - `tech` accepts a string or an array, but the imported list is built from the FIRST technology. For multiple technologies, create one source each. - `country` and `countries` are aliases — pass either. Full country names are resolved to ISO-2 codes server-side; "UK" is accepted. - `metadata.total_results` is a live coverage estimate of how many companies run the technology, NOT the number you'll import. Use `max_count` to choose the import size. - One-time static import. There is no `pull_mode` or `schedule`; re-run Create for a fresh pull. `max_count` defaults to 100 when omitted. - Preview does not import anything and does not consume credits. Create starts the real import and consumes credits; insufficient balance → 402. ================================================================================ 7. WHEN TO USE ================================================================================ - Technographic prospecting: "Companies running Shopify in the US": filters: tech + countries. - Competitive displacement: "Companies using ": filters: tech. - Recent adopters: "Companies that added since 2025": filters: tech + since. - Combine with Sync to enrich + score + reach out to each company in a workflow. When you want firmographic/headcount/industry filters instead of (or in addition to) a single technology, use `find_companies` — it supports a technology filter alongside size, revenue, industry, and location. ================================================================================ Last updated: 2026-06-02. Reference: https://floqer.com/docs/reference