--- title: "Trigger a pipeline run (scoped to 1, some, or all records)" method: POST path: "/api/v1/pipeline/trigger" tags: ["pipeline"] --- # Trigger a pipeline run (scoped to 1, some, or all records) `POST /api/v1/pipeline/trigger` ## Request - Base URL: `https://app.goodleads.club` (the document declares no server; this is the origin it was published from) - URL: `https://app.goodleads.club/api/v1/pipeline/trigger` - Auth: API key in header `X-API-Key` Submit a pipeline run. Returns immediately with `job_id` for polling. **Scoping the run (1/some/all):** - **One record** — pass `entity_id` as a single UUID or GLID (e.g. `"GL-CO-00042"`) - **N specific records** — pass `entity_id` as a comma/space/newline-separated list of UUIDs or GLIDs (e.g. `"GL-CO-1, GL-CO-2, GL-FL-99"`) - **A previously-stamped batch** — pass `batch_id` (UUID) - **A filter expression** — pass `filters` (same shape as `/leads/browse`) - **The exact entity set of a previous run** — pass `manifest_id` (UUID from `GET /jobs/{id}/results`); the recovery gesture for re-running a failed run - **All records in a state** — pass none of the above Mutually exclusive: pick at most one of `entity_id`, `batch_id`, `filters`, `manifest_id` — two selectors is a 422, and so is any unknown field (a typo must fail loudly, never silently widen the run to the whole state). **Finding a record's GLID:** call `POST /api/v1/leads/browse` with `{"filters":[{"field":"lead_ref","op":"eq","value":"GL-CO-00042"}]}` to verify a GLID resolves to a real entity. The full filter field list lives at `GET /api/v1/schema/attributes`. **Stages:** pass `stages="all"` (default), a single stage name, the shortcut `"enrich"` (= skip_trace + gapfill + validate), or a comma-separated list. Canonical stage order at `GET /api/v1/pipeline/stages`. Returns 202 with a `job_id`. Poll `GET /api/v1/pipeline/jobs/{job_id}` for status. ## Request body - TriggerRequest: Submit a pipeline run, optionally scoped to one record, a set of records, a batch, or a filter expression. See `GET /api/v1/schema/attributes` for the full list of fields that can appear in `filters`. - `state` string, required: Two-letter US state code (e.g. 'CO', 'FL', 'VA', 'NY'). Must be a live state. - `stages` union: Pipeline stages to run. Either 'all', a single stage name, a comma-separated list, or an array. Shortcut: 'enrich' = skip_trace + gapfill + validate. See GET /api/v1/pipeline/stages for the canonical stage order. - string - string[] - `limit` integer, nullable: Cap the number of records this run touches. Applied at scope-resolution time, so all stages operate on the same set. - `batch_id` string, nullable: Run the pipeline on every entity in this batch (UUID). Mutually exclusive with `entity_id` and `filters`. - `entity_id` string, nullable: Scope the run to one or more specific records. Accepts a UUID, a GLID (e.g. 'GL-CO-00042'), or a comma/space/newline-separated list of either. Single ID → runs on that one record; multiple → resolves all, stamps a Batch, runs the pipeline scoped to that Batch. Mutually exclusive with `batch_id` and `filters`. - `filters` object[], nullable: Scope the run to records matching a filter expression. Same shape as POST /api/v1/leads/browse: [{field, op, value}]. Discover available fields and operators via GET /api/v1/schema/attributes. Mutually exclusive with `batch_id` and `entity_id`. - `manifest_id` string, nullable: Run the pipeline on the exact entity set of a previous run (UUID of a `run_manifest`). The natural recovery gesture after a failed or partial run: get the manifest id from GET /jobs/{id}/results and re-run any stages on precisely those entities. Mutually exclusive with `batch_id`, `entity_id`, and `filters`. - `start_date` string, nullable: YYYY-MM-DD. For the PULL stage, the earliest filing date to fetch from the Secretary of State. - `end_date` string, nullable: YYYY-MM-DD. For the PULL stage, the latest filing date to fetch from the Secretary of State. - `input_file` string, nullable: Source file for the PULL stage, for states whose feed is a portal download rather than an API (currently TX). Use the reference returned by POST /api/v1/pipeline/upload-bulk-file (an s3:// URI in production). Only valid when the run includes the `pull` stage. - `pull_mode` string, nullable: Alternate pull mode for harvest sweeps (trade_names, sole_props). trade_names stamps DBA attributes on existing entities (update-only, stages pull,reload only); sole_props mints the sole-proprietor inventory class (create-mode load + free brains); fact_backfill (FL) fills missing filing facts — the federal tax ID — on existing entities without moving batch, pulled date, name, status or filing event (stages pull,reload). Paid stages are always refused for harvest modes. Only valid for states with the mode's feed configured. - `gapfill_force` boolean: Gap-fill re-dips EVERY scoped record regardless of existing channels or prior Enformion delivery — a deliberate paid re-spend for vendor-quality evaluation. Requires the run to include the `gapfill` stage AND an explicit scope (`entity_id`, `batch_id`, `manifest_id`, or `filters`); refused on an unscoped whole-state run. Filer exclusion and 'hold' routing still apply. - `include_non_operating` boolean: Only meaningful with `filters`. Browse hides non-operating entities (`enrichment_strategy = 'hold'` — shell LLCs, single-asset holdings) by default, so a filter set copied out of Browse resolves here the same way and the manifest matches the count the operator saw. Set true to include them, exactly as the Browse toggle does. An explicit `enrichment_strategy` or `lead_ref` filter bypasses the default either way. - `include_existing` boolean: Only meaningful with `filters`. Browse holds Just started only — a brand-new business — and hides every existing business with a new filing (opening a location here, formed in another state, back in business, a new entity, moved, a new trade name), so a filter set copied out of Browse resolves here the same way. Set true to include them, exactly as the Browse checkbox does. An explicit `filing_kind`, `business_origin` or `lead_ref` filter bypasses the default either way. - `include_registrations` boolean: Deprecated alias of include_existing (kept one release so saved requests resolve). - `force_recompute` boolean: Only meaningful with `filters` scoping more than one record — `entity_id` and a single-match `filters` already always recompute (an operator who names records wants them re-answered). Bulk `filters` runs default to skip-if-current as the whole-sweep cost guard; set this to override that guard and force every SELECTED free stage to recompute even if its version is already current. Paid/metered stages (skip_trace, gapfill, validate) are exempt regardless — they own their own spend gates. The unblock for a backlog that was filter-scoped-processed under a stale ruleset and needs to re-run against today's classify rules without pasting thousands of individual entity_id values. - `days_back` integer, nullable: For the PULL stage: rolling window of N calendar days ago through today (the flag the sweep schedules use). Mutually exclusive with `start_date`/`end_date`. - `options` object, nullable: Per-run switches, flipped on THIS task only (a canary never needs a redeploy): `events_apply` — The events stage projects status / name / prior-entity onto records (ADR-061). On by default; false runs it dark. `linkage_stamp` — The family stage writes clusters into the container (ADR-060). On by default; false runs it dark. `founder_history_stamp` — The family stage also answers 'has this owner run a company before' against the state's whole book and stamps it on the record (Entrepreneur Layer, dark: no customer surface shows it). OFF by default until a production canary measures its runtime (it reads the whole state book); true runs it for one run. Booleans only. An unknown key is refused (422); a switch whose stage is not in the run is refused (400). Carried as the task's environment, so the run still goes through this endpoint and its manifest — never a raw task launch. ## Response `202` Successful Response - TriggerResponse - `job_id` string, required - `status` string, required - `status_url` string, required - `task_arn` string, nullable ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/goodleads/apis/formation-gtm-api.md) · [All operations](https://skmtc.dev/goodleads/apis/formation-gtm-api/llms.txt) · [OpenAPI document](https://skmtc.dev/goodleads/apis/formation-gtm-api/revisions/2068d13a82cf?raw)