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: ‘text’, ‘int’ (whole number), ‘numeric’ (decimal) or ‘boolean’ (yes/no). Unknown values 400.
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
True when this column already existed (same name, same scope), so the existing column was returned instead of a new one.
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.
Non-blocking notices for this column (e.g. same name exists org-wide).
How many requested columns already existed and were returned as-is.
Columns returned by this call, INCLUDING ones that already existed (unchanged meaning). total_already_existed says how many of them were existing columns.
object
Whether there are more pages
Items per page
Current page number (1-indexed)
Total number of items
422
Validation Error