Enrichment

Create Default Waterfall Config

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.

post/enrichment/waterfall/configs

Request

  • Base URL: https://be.graph8.com/api/v1
  • URL: https://be.graph8.com/api/v1/enrichment/waterfall/configs
  • Auth: HTTP bearer

Headers

Authorizationstring nullable
X-Target-Org-Idstring nullable

Request body

list_idinteger required

List ID to attach the pipeline to

namestring

Human-readable name for the pipeline

field_to_enrichstring

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

fieldstring nullable

Canonical enrichment column to fill — CONTACT_DIRECT_PHONE, CONTACT_MOBILE_PHONE, CONTACT_WORK_EMAIL, CONTACT_PERSONAL_EMAILS, CONTACT_LINKEDIN_URL, COMPANY_PHONE, COMPANY_LINKEDIN_URL — or a friendly synonym ('phone', 'mobile', 'email', 'linkedin', 'company_phone'). When set, the pipeline is built from the server's per-field waterfall TEMPLATE, so each provider runs its CORRECT action for that column (e.g. leadmagic mobile_finder for a phone, not email_finder), and the enriched value is written into the real contact/company column — exactly like the web UI's 'enrich existing column' flow. Combine with providers[] to keep only those providers from the template (their correct per-field action is preserved). Mutually exclusive with steps[]. When omitted, the legacy bare/providers[] email-finder behavior is unchanged.

skip_existing_valuesboolean

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

providersstring[] nullable

Ordered list of provider names — server builds default email-finder steps in this order. Mutually exclusive with steps. Allowed providers: graph8, hunter, prospeo, dropcontact, icypeas, leadmagic, emaillistverify, apollo, lusha, rocketreach. Use steps[] for full control.

credential_mode'auto' | 'system' | 'byok'

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.

Response

Successful Response

Changes

No recorded changes to this operation across all 2 revisions of this API.