TriggerRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/goodleads-club/json-schema/goodleads-club-trigger-request-schema.json",
  "title": "TriggerRequest",
  "description": "Submit a pipeline run, optionally scoped to one record, a set of records,\na batch, or a filter expression. See `GET /api/v1/schema/attributes` for the\nfull list of fields that can appear in `filters`.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/goodleads-club-openapi.json#/components/schemas/TriggerRequest",
  "properties": {
    "state": {
      "type": "string",
      "title": "State",
      "description": "Two-letter US state code (e.g. 'CO', 'FL', 'VA', 'NY'). Must be a live state."
    },
    "stages": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      ],
      "title": "Stages",
      "description": "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.",
      "default": "all"
    },
    "limit": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Limit",
      "description": "Cap the number of records this run touches. Applied at scope-resolution time, so all stages operate on the same set."
    },
    "batch_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Batch Id",
      "description": "Run the pipeline on every entity in this batch (UUID). Mutually exclusive with `entity_id` and `filters`."
    },
    "entity_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Entity Id",
      "description": "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": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Filters",
      "description": "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": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Manifest Id",
      "description": "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": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Start Date",
      "description": "YYYY-MM-DD. For the PULL stage, the earliest filing date to fetch from the Secretary of State."
    },
    "end_date": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "End Date",
      "description": "YYYY-MM-DD. For the PULL stage, the latest filing date to fetch from the Secretary of State."
    },
    "input_file": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Input File",
      "description": "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": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Pull Mode",
      "description": "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); late_names (OR) loads owner names the state publishes after the entity (the monthly list) onto existing entities, update-only, then re-runs the free contact stages. Paid stages are always refused for harvest modes. Only valid for states with the mode's feed configured."
    },
    "gapfill_force": {
      "type": "boolean",
      "title": "Gapfill Force",
      "description": "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.",
      "default": false
    },
    "include_non_operating": {
      "type": "boolean",
      "title": "Include Non Operating",
      "description": "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.",
      "default": false
    },
    "include_existing": {
      "type": "boolean",
      "title": "Include Existing",
      "description": "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.",
      "default": false
    },
    "include_registrations": {
      "type": "boolean",
      "title": "Include Registrations",
      "description": "Deprecated alias of include_existing (kept one release so saved requests resolve).",
      "default": false,
      "deprecated": true
    },
    "force_recompute": {
      "type": "boolean",
      "title": "Force Recompute",
      "description": "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.",
      "default": false
    },
    "days_back": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 1.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Days Back",
      "description": "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`."
    },
    "queue_if_busy": {
      "type": "boolean",
      "title": "Queue If Busy",
      "description": "When this state already has a run in progress, wait in line behind it instead of being refused (409). The run is accepted (status 'queued') and starts when the state's other run finishes and a worker is free — visible and cancellable the whole time. Off by default: a person pressing Run usually wants to know the state is busy. Scheduled callers that must not lose the day (the delivery look-up) set it (ADR-102).",
      "default": false
    },
    "options": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "boolean"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Options",
      "description": "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. `hard_slice_stamp` — After routing, also store, per filing, the answer to 'does the filing itself tell us who decides?' with its reasons (the hard slice; dark: nothing reads it and no customer surface shows it). OFF by default; true runs it for one run. `owner_graph_write` — After routing, also run the three owner-graph stores for the run's WHOLE state, in order: agents and places with the Intermediary score, same person, then Decision Maker relationships (dark: nothing reads them and no customer surface shows them; free). A store that fails is reported and never fails the run. OFF by default; 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."
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "state"
  ]
}