pipeline

Trigger a pipeline run (scoped to 1, some, or all records)

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.

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

Request body

statestring required

Two-letter US state code (e.g. 'CO', 'FL', 'VA', 'NY'). Must be a live state.

limitinteger nullable

Cap the number of records this run touches. Applied at scope-resolution time, so all stages operate on the same set.

batch_idstring nullable

Run the pipeline on every entity in this batch (UUID). Mutually exclusive with entity_id and filters.

entity_idstring 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.

filtersobject[] 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_idstring 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_datestring nullable

YYYY-MM-DD. For the PULL stage, the earliest filing date to fetch from the Secretary of State.

end_datestring nullable

YYYY-MM-DD. For the PULL stage, the latest filing date to fetch from the Secretary of State.

input_filestring 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_modestring 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_forceboolean

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_operatingboolean

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_existingboolean

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_registrationsboolean

Deprecated alias of include_existing (kept one release so saved requests resolve).

force_recomputeboolean

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_backinteger 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.

optionsobject 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.

Example request

{
  "summary": "Run scoring on a single record by GLID",
  "value": {
    "entity_id": "GL-CO-00042",
    "stages": "score",
    "state": "CO"
  }
}

Response

Successful Response

job_idstring required
statusstring required
status_urlstring required
task_arnstring nullable

Changes

No recorded changes to this operation across all 1 revision of this API.