Create Fields Batch
POST /fields/batch
Create many custom columns (contacts or companies) in ONE request.
Backed by a single DB transaction with ONE view rebuild for the whole batch
— the efficient path for setting up a list with dozens of columns at once.
The single-column POST /fields is unchanged; this is purely additive.
Validation is fail-fast: data_types, duplicate titles, and every enrichment
block are checked BEFORE any column is created, so a bad request creates
nothing. Column creation itself is atomic (all columns or none).
Per-column enrichment blocks are applied AFTER the columns commit; if a
companion enrichment config fails for one column, that column still exists
and its results[] entry reports ok=false with the error — the rest of
the batch is unaffected (mirrors the single endpoint’s column-then-config
ordering, but per-field instead of failing the whole request).
Authorizations
Parameters
Header Parameters
Request Body required
Create MANY custom columns in one request.
All columns are created in a single DB transaction with a SINGLE view rebuild — at 40-50 columns this replaces 40-50 view recreations with one.
object
Target entity for ALL columns: ‘contacts’ or ‘companies’
Columns to create (1-100).
One column in a batch-create request.
title, data_type and the optional enrichment block are per-column;
list_id and entity are shared at the parent CreateFieldsBatchRequest
level (a batch targets one entity and, when enrichment is used, one list).
object
Column data type. Currently only ‘text’ is supported.
Optional enrichment-pipeline block attached at column-create time.
When supplied, POST /fields creates a companion enrichment_configs
row in the same request so the new column is immediately runnable via
POST /enrichment/waterfall/enrich. Without this block the column
exists but has no enrichment plan — calling /waterfall/enrich on it
returns 422 (waterfall_config_missing).
Currently only type='waterfall' is supported; AI / formula
enrichment will follow once the rest of the agent surface lands.
object
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
Treat catch-all responses as valid (domains that accept any address).
Enable post-enrichment email verification
Verification provider. Charges credits when use_system_credentials=True.
Use graph8-managed API keys (charges credits). False = use org’s BYOK keys.
Verification statuses to accept as valid. Typical: [‘valid’] or [‘valid’,‘catch-all’].
If true, skip rows where the target field is already populated.
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
Provider action: lookup_person, find_email, enrich_person, …
Provider-specific options (e.g. apollo reveal_phone_numbers=true).
object
Maps provider input names to graph8 column identifiers (CONTACT_*).
object
True = use graph8-managed credentials + charge credits. False = use org BYOK.
0-indexed execution order.
Optional output field remap (deprecated — prefer output_field).
object
Provider name: graph8, hunter, prospeo, dropcontact, apollo, …
Pipeline kind. Only ‘waterfall’ is supported today.
Column title, e.g. ‘Job Level’
Responses
201
Successful Response
object
object
Per-column outcome inside a batch response.
object
Echo of the companion enrichment config created by enrichment block.
True when this column was created org-GLOBAL (no list_id was supplied) and will therefore appear on EVERY list in the org. Pass list_id to scope columns to one list.
422
Validation Error