SOURCE_ID: track_companies_hiring NAME: Track Companies Hiring CATEGORY: Signals Monitor companies that start hiring for the roles you care about, filtered by the roles they post, the technologies in their job ads, firmographics, and location. Creates an ongoing source: an immediate first import of matching companies, then each newly matching company is added as it is detected, until a stop date. Imported company rows become available to your Floqer workflows for hiring-intent prospecting, account scoring, and outreach. How it relates to its siblings: - find_companies_hiring same filters, same company rows — a ONE-TIME snapshot. Use it for a list you build once. - track_job_postings ongoing too, but returns one row per JOB POSTING. This source returns one row per COMPANY. 1. ENDPOINTS Source identifier (used in every endpoint path): `track_companies_hiring`. POST /api/v1/sources/track_companies_hiring/preview Scope: sources:read Returns a sample of up to 25 companies matching the given filters, without creating anything. `metadata.total_results` reports the full match count. Does not consume Floqer credits. POST /api/v1/sources/track_companies_hiring Scope: sources:write Creates the ongoing source, starts an immediate first import of up to `max_count` matching companies, and starts watching for new matches. Returns `source_instance_id` (the new source's UUID). 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. Body: { workflow_id, field_mapping, push_existing?, run? }. Source-agnostic; see concepts.txt §10. PATCH /api/v1/sources//status Scope: sources:write Pause or resume the source. Body: {"status": "active"|"paused"}. A paused source adds no new companies until resumed. No connection is required. There is no dynamic-options endpoint for this source (see §5). 2. LIFECYCLE (ONGOING ONLY) Track Companies Hiring is always an ongoing source — there is no one-time mode (use find_companies_hiring for that). On create An immediate first import adds up to `max_count` companies (default 25) that match your filters today. It runs asynchronously — Create returns as soon as the source exists and the import has started. After create Each company that newly matches your filters is added to the source as it is detected and pushed to any connected workflows automatically. New matches are event-driven, not a fixed daily or weekly batch. start_date (optional) New matches are tracked from this date. Defaults to the moment of create. expiration_date (required on create) The source stops adding companies after this date and moves to paused. 3. BODY SHAPE (PREVIEW + CREATE) Field names are snake_case. Unknown top-level keys and unknown filter keys are rejected with 400. All field errors are returned together. Preview accepts: filters required: object with at least one filter key (§4) start_date optional: valid date string (no effect on preview) expiration_date optional: valid date string (no effect on preview) max_count optional: positive whole number (no effect on preview) Create accepts: filters required: object with at least one filter key (§4) expiration_date required: valid date string in the future start_date optional: valid date string max_count optional: positive whole number; size of the first import (default 25) name required: display name for the new source Example create body: { "name": "US SaaS companies hiring RevOps", "filters": { "company_country_code_or": ["US"], "min_employee_count": 50, "job_filters.job_title_or": ["Revenue Operations", "RevOps"], "job_filters.posted_at_max_age_days": 30 }, "expiration_date": "2027-01-31", "max_count": 500 } Preview response envelope: { "status": 200, "data": { "data": [ { "name": "Xxxxxx", "industry": "Software Development", ... } ], "metadata": { "total_results": 1234 } } } Preview masks company identity (name, domain, LinkedIn URL and similar come back as placeholders); firmographics and hiring counts are real. Create the source to see real companies. Create response envelope: { "status": 201, "data": { "source_instance_id": "", "name": "US SaaS companies hiring RevOps", "created_at": "2026-10-27T12:00:00.000Z" } } 4. FILTER FIELDS `filters` uses exactly the same keys as find_companies_hiring — see source-detail/find_companies_hiring.txt §3 for the full catalogue of field bases, operator suffixes, and range prefixes. In short: Company (flat keys) company_country_code, company_technology_slug, company_name, company_description, company_location, company_domain, industry_id, revenue_usd, funding_usd, funding_stage, company_type, company_linkedin_url, employee_count Technology (prefix `tech_filters.`) technology_category_slug, confidence, first_date_found, last_date_found, jobs Job posting (prefix `job_filters.`) posted_at, job_title, job_description, job_country_code, job_location, remote, salary_usd, job_technology_slug, scraper_name_pattern Keys combine a field base with an operator suffix (`_or`, `_not`, `_pattern_or`, …) or range prefix (`min_`, `max_`). A key whose base is not in the catalogue returns 400 naming the key. Whenever you use any `job_filters.*` key without a posted-date constraint (`job_filters.posted_at_max_age_days`, or `job_filters.posted_at_gte` / `_lte`), the last 180 days is applied. Company-only filters are used as given. Imported row fields (returned by preview and stored on create), one row per company: id, name, domain, industry, industry_id, country, country_code, city, postal_code, employee_count, employee_count_range, logo, linkedin_url, linkedin_id, founded_year, annual_revenue_usd, annual_revenue_usd_readable, total_funding_usd, last_funding_round_date, last_funding_round_amount_readable, funding_stage, investors, publicly_traded_symbol, publicly_traded_exchange, long_description, seo_description, company_keywords, company_tags, alexa_ranking, technology_slugs, num_jobs, num_jobs_last_30_days, num_technologies, jobs_found, technologies_found, yc_batch, url_source, is_recruiting_agency 5. DYNAMIC OPTIONS None. Technology slugs and industry ids use the same catalogues as find_job_postings — resolve them through that source's options (`company_technology_slug`, `job_technology_slug`, `industry_id`) and reuse them here. Country codes are ISO-3166 alpha-2. 6. CREDITS - Preview is free. - Create requires a balance that covers the first import (`max_count` companies); otherwise it returns 402 and nothing is created. - The first import consumes credits per company imported; companies added afterwards consume credits as they arrive. - When the balance runs out, the source pauses (status `paused_out_of_credits`). Top up, then resume with PATCH …/status {"status": "active"}. 7. HOW TO CONFIGURE END-TO-END Step 1 — Preview before committing POST /api/v1/sources/track_companies_hiring/preview Body: { "filters": { ...your ICP criteria... } } Iterate on `filters` until `metadata.total_results` and the row shape look right. Step 2 — Create the source POST /api/v1/sources/track_companies_hiring Body: + "name", "expiration_date", and optionally "start_date" / "max_count". Step 2b — (Optional) Poll imported companies GET /api/v1/sources//data?page_no=1&page_size=20 The count grows as the first import completes and new matches arrive. Step 3 — Sync the source into a workflow POST /api/v1/sources//sync Map workflow inputs to company fields, e.g. { "input.company_name": "name", "input.website": "domain", "input.linkedin_url": "linkedin_url" } See concepts.txt §10 for the full sync semantics. New companies added after Step 3 flow into the synced workflow automatically until `expiration_date`. 8. KEY NOTES - No connection required. - `name` and `expiration_date` are required on create; `filters` needs at least one key on both preview and create. - Unknown filter keys return 400 naming the key — the same rules as find_companies_hiring. - Preview masks company identity; create to see real companies. - Pausing stops new companies from being added; resuming restarts it. 9. WHEN TO USE - Hiring-intent alerts: be told when target-profile companies start hiring for a role that signals need for your product (e.g. RevOps, Data Engineering, Security). - Technographic + hiring: companies on a given technology that open matching roles. - Territory monitoring: scope `company_country_code_or` to your region and keep the source running to a quarter-end `expiration_date`. For a one-time list of the companies hiring today, use find_companies_hiring. For one row per job posting instead of per company, use track_job_postings. Last updated: 2026-10-27. Reference: https://floqer.com/docs/reference