Skip to content

Create Default Waterfall Config

POST
/enrichment/waterfall/configs

Create (or reuse) a waterfall pipeline on a list.

Three call-styles (mutually exclusive between providers[] and steps[]):

  • Bare — pass only list_id. Builds a single-step graph8 lookup.
  • By providers — pass providers=["hunter","prospeo"]. Builds default email-finder steps in that order.
  • By steps — pass steps=[...] with full step shapes. Persisted verbatim (matches the canonical WaterfallStepDto shape the UI saves).

email_verification may be combined with any call-style.

Idempotent by (list_id, name): if a pipeline with the same name already exists on this list, returns its column_id with created=False instead of creating a duplicate. Mirrors the dedup behaviour of the UI’s POST /enrichments/waterfall/save endpoint.

Authorizations

Parameters

Header Parameters

X-Target-Org-Id
Any of:
string

Request Body required

Create (or reuse) a waterfall pipeline for a list.

Three call-styles, in increasing order of control:

  1. Bare — pass only list_id. Server builds a single-step graph8 lookup pipeline that fills name/email/company for 0 credits. Backward-compatible with the pre-2026-06 contract.
  2. By providers — pass providers=["hunter","prospeo"]. Server maps each provider to its default email-finder action (see provider matrix in docs/developer-api-reference.md) and ordered steps. Use this when you want a 1-line “try these providers, in this order” pipeline.
  3. By steps — pass steps=[...] with full step shapes. Server persists them verbatim. Use this when you need provider-specific config (e.g. apollo reveal_phone_numbers=true).

providers[] and steps[] are mutually exclusive — pass one or neither, not both. email_verification may be combined with any call-style; when set it runs after the main waterfall and follows the same credit + valid-status rules the UI uses.

list_id is required; everything else has a sensible default so callers pass the minimum. skip_existing_values defaults True so we never overwrite populated fields. Idempotent by (list_id, name).

object
credential_mode

How to resolve each provider step’s credential source. Applies to the providers[] shortcut and the bare default; steps[] payloads always honor their own per-step is_system_provider. ‘auto’ (default, matches the UI): for each provider use the org’s BYOK key when one is configured (free), otherwise graph8’s system key for funded providers (charges credits). ‘system’: force graph8 system keys for funded providers (charges credits). ‘byok’: force the org’s own keys for every non-graph8 provider (legacy behavior — steps silently skip when no key exists). graph8 is always system-funded regardless of mode.

string
default: auto
Allowed values: auto system byok
email_verification
Any of:

Email verification config attached to a waterfall pipeline.

Mirrors the canonical EmailVerificationConfigDto in enrichment/interfaces/fastapi/waterfall_dtos.py so the dev-API and the UI persist an identical settings shape (the CF worker reads settings. email_verification.* regardless of which surface saved the pipeline).

object
accept_catchall

Treat catch-all responses as valid (domains that accept any address).

boolean
enabled

Enable post-enrichment email verification

boolean
default: true
provider

Verification provider. Charges credits when use_system_credentials=True.

string
default: zerobounce
Allowed values: zerobounce hunter icypeas leadmagic
use_system_credentials

Use graph8-managed API keys (charges credits). False = use org’s BYOK keys.

boolean
default: true
valid_statuses

Verification statuses to accept as valid. Typical: [‘valid’] or [‘valid’,‘catch-all’].

Array<string>
field
Any of:
string
field_to_enrich

Target field identifier for this pipeline (legacy; ignored when field is set)

string
default: work_email
list_id
required

List ID to attach the pipeline to

integer
name

Human-readable name for the pipeline

string
default: API Auto-Created Pipeline
providers
Any of:
Array<string>
skip_existing_values

If true, the pipeline skips contacts where the target field is already populated

boolean
default: true
steps
Any of:
Array<object>

Single step in a caller-supplied waterfall sequence.

Mirrors WaterfallStepDto in enrichment/interfaces/fastapi/waterfall_dtos.py. Persisted verbatim into enrichment_configs.config.steps[] so the CF worker can resolve provider, action and credentials the same way UI-saved pipelines do.

object
action
required

Provider action: lookup_person, find_email, enrich_person, …

string
action_display_name
Any of:
string
confidence_threshold
number
<= 1
config

Provider-specific options (e.g. apollo reveal_phone_numbers=true).

object
key
additional properties
any
enabled
boolean
default: true
id
Any of:
string
input_mapping

Maps provider input names to graph8 column identifiers (CONTACT_*).

object
key
additional properties
string
is_system_provider

True = use graph8-managed credentials + charge credits. False = use org BYOK.

boolean
max_retries
integer
<= 3
order

0-indexed execution order.

integer
output_field
Any of:
string
output_mapping

Optional output field remap (deprecated — prefer output_field).

object
key
additional properties
string
provider
required

Provider name: graph8, hunter, prospeo, dropcontact, apollo, …

string
stop_on_success
boolean
default: true

Responses

201

Successful Response

object
data
required

Result of creating (or reusing) a default pipeline.

object
column_id
required
string
config_id
required
string
created

True if a new config was created; False if an existing one with the same name was reused

boolean
email_verification
Any of:
object
key
additional properties
any
list_id
Any of:
integer
missing_credentials

Providers whose step is BYOK but the org has no active key (these steps will be skipped at run time). Empty when every step is runnable.

Array<string>
name
required
string
providers

Ordered, de-duplicated provider list of the persisted (or reused) pipeline.

Array<string>
providers_detail

Per-step credential breakdown (system vs BYOK + readiness) for the persisted pipeline.

Array<object>

Per-step credential breakdown so callers can see, before running, which steps use graph8 system keys (charge credits) vs the org’s own BYOK key, and whether the required credential is actually present.

object
credential_ready
required

True if the step can actually run: system steps are always ready; BYOK steps are ready only when the org has an active key for that provider.

boolean
credential_source
required

‘system’ = graph8-funded; ‘byok’ = org’s own key.

string
Allowed values: system byok
is_system_provider
required

True = uses graph8-managed system key (charges credits). False = uses org BYOK key.

boolean
provider
required
string
pagination
Any of:
object
has_next
required

Whether there are more pages

boolean
limit
required

Items per page

integer
next_cursor
Any of:
string
page
required

Current page number (1-indexed)

integer
total
required

Total number of items

integer

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string