All docs

Start here

API basics

SDK

CLI

MCP

Agent setups

Data pipeline

Webhooks

Webhooks

What's new

What's New

Fields

List, create, and write custom field definitions and values for contacts and companies

Fields are the column definitions for contacts and companies. Use these endpoints to discover available fields — both built-in and custom — and to create new custom columns, populate their values, and optionally provision enrichment pipelines that fill them automatically.

List Contact Fields

GET /fields

Returns all contact field definitions, including base fields and any custom fields. Pass list_id to include list-specific custom fields.

Query Parameters

Parameter	Type	Default	Description
`list_id`	integer	—	Include custom fields specific to this list

Example

cURL

curl "https://be.graph8.com/api/v1/fields" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": [
    {
      "id": 1,
      "title": "Job Level",
      "name": "job_level",
      "data_type": "text",
      "is_global": true
    }
  ]
}

List Company Fields

GET /fields/companies

Returns all company field definitions, including base fields and any custom fields. Same response shape as GET /fields.

Query Parameters

Parameter	Type	Default	Description
`list_id`	integer	—	Include custom fields specific to this list

Example

cURL

curl "https://be.graph8.com/api/v1/fields/companies" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": [
    {
      "id": 1,
      "title": "Company Name",
      "name": "COMPANY_NAME",
      "data_type": "text",
      "is_global": true
    }
  ]
}

Create a Custom Field

POST /fields → 201

Creates a single custom column for contacts or companies. Optionally provisions a waterfall enrichment pipeline alongside the column in the same request.

Request Body

Field	Type	Required	Description
`title`	string	R	Display name for the column
`data_type`	string	O	Column data type. Default `"text"`
`list_id`	integer	O	Scope to a specific list. `null` or omitted = global. Required when `enrichment` is set.
`entity`	string	O	`"contacts"` or `"companies"`. Default `"contacts"`
`enrichment`	object	O	When present, provisions a waterfall pipeline alongside the column. See enrichment fields below.

`enrichment` object fields

Field	Type	Required	Description
`type`	string	O	Pipeline kind. Default `"waterfall"` (only supported kind today)
`name`	string	O	Pipeline display name. Default `"<title> Enrichment"`
`field_to_enrich`	string	O	Column slug to target. Defaults to the new column’s slug
`skip_existing_values`	boolean	O	Skip contacts that already have a value. Default `true`
`providers`	array of strings	O	Shorthand provider list. Mutually exclusive with `steps`. Allowed: `graph8`, `hunter`, `prospeo`, `dropcontact`, `icypeas`, `leadmagic`, `emaillistverify`, `apollo`, `lusha`, `rocketreach`
`steps`	array of objects	O	Full step DTOs. Mutually exclusive with `providers`
`email_verification`	object	O	Post-enrichment validation config. See below.

`email_verification` object fields

Field	Type	Description
`enabled`	boolean	Enable email verification
`provider`	string	`zerobounce`, `hunter`, `icypeas`, or `leadmagic`
`use_system_credentials`	boolean	Use graph8’s system credentials for the provider
`accept_catchall`	boolean	Treat catch-all addresses as valid
`valid_statuses`	array of strings	Which statuses to accept (e.g. `["valid"]`)

Example

cURL

# Simple column (no enrichment)
curl -X POST "https://be.graph8.com/api/v1/fields" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Job Level",
    "data_type": "text",
    "list_id": 12345,
    "entity": "contacts"
  }'

# Column + enrichment pipeline
curl -X POST "https://be.graph8.com/api/v1/fields" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Job Level",
    "data_type": "text",
    "list_id": 12345,
    "entity": "contacts",
    "enrichment": {
      "type": "waterfall",
      "name": "Job Level Enrichment",
      "field_to_enrich": "job_level",
      "skip_existing_values": true,
      "providers": ["hunter", "prospeo"],
      "email_verification": {
        "enabled": true,
        "provider": "zerobounce",
        "use_system_credentials": true,
        "accept_catchall": false,
        "valid_statuses": ["valid"]
      }
    }
  }'

Response (no enrichment)

{
  "data": {
    "id": 1,
    "title": "Job Level",
    "data_type": "text",
    "name": "job_level",
    "list_id": 12345,
    "is_global": false,
    "enrichment": null
  }
}

Response (with enrichment)

{
  "data": {
    "id": 1,
    "title": "Job Level",
    "data_type": "text",
    "name": "job_level",
    "list_id": 12345,
    "is_global": false,
    "enrichment": {
      "column_id": "job_level",
      "config_id": "uuid",
      "name": "Job Level Enrichment",
      "type": "waterfall",
      "providers": ["hunter", "prospeo"],
      "email_verification": {
        "enabled": true,
        "provider": "zerobounce"
      }
    }
  }
}

Create Multiple Custom Fields

POST /fields/batch → 201

Creates many custom columns in a single request. All columns are created in a single DB transaction with a single view rebuild — far more efficient than calling POST /fields in a loop when setting up a list with many columns.

entity and list_id are shared across the entire batch. title, data_type, and enrichment are per-column.

Request Body

Field	Type	Required	Description
`entity`	string	O	`"contacts"` or `"companies"`. Applies to all columns. Default `"contacts"`
`list_id`	integer	O	Shared list scope. Required if any field has `enrichment` set.
`fields`	array of objects	R	1–100 column definitions. Each item may have `title` (R), `data_type` (O), and `enrichment` (O, same shape as `POST /fields`)

Example

cURL

curl -X POST "https://be.graph8.com/api/v1/fields/batch" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "contacts",
    "list_id": 12345,
    "fields": [
      { "title": "Persona" },
      { "title": "Account Tier", "data_type": "text" },
      {
        "title": "Work Email",
        "enrichment": {
          "type": "waterfall",
          "providers": ["graph8", "hunter", "prospeo"],
          "email_verification": {
            "enabled": true,
            "provider": "zerobounce"
          }
        }
      }
    ]
  }'

Response

{
  "data": {
    "entity": "contacts",
    "list_id": 12345,
    "total_requested": 3,
    "total_created": 3,
    "results": [
      {
        "title": "Persona",
        "id": 10,
        "name": "udo_persona_1700000000",
        "ok": true,
        "error": null,
        "enrichment": null
      },
      {
        "title": "Account Tier",
        "id": 11,
        "name": "udo_account_tier_1700000000",
        "ok": true,
        "error": null,
        "enrichment": null
      },
      {
        "title": "Work Email",
        "id": 12,
        "name": "udo_work_email_1700000000",
        "ok": true,
        "error": null,
        "enrichment": {
          "column_id": "udo_work_email_1700000000",
          "config_id": "uuid",
          "name": "Work Email Enrichment",
          "type": "waterfall",
          "providers": ["graph8", "hunter", "prospeo"],
          "email_verification": {
            "enabled": true,
            "provider": "zerobounce"
          }
        }
      }
    ]
  }
}

Write a Custom Field Value

PATCH /fields/{column_id}/values

Sets (or clears) the value of a custom column for a single contact or company record.

Path Parameters

Parameter	Type	Description
`column_id`	integer	The numeric ID of the custom field (from `GET /fields`)

Request Body

Field	Type	Required	Description
`record_id`	integer	R	Contact or company ID
`value`	string	O	New value. Pass `null` or omit to clear the field
`entity`	string	O	`"contacts"` or `"companies"`. Default `"contacts"`

Example

cURL

# Set a value
curl -X PATCH "https://be.graph8.com/api/v1/fields/1/values" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "record_id": 101,
    "value": "Director",
    "entity": "contacts"
  }'

# Clear a value
curl -X PATCH "https://be.graph8.com/api/v1/fields/1/values" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "record_id": 101,
    "value": null,
    "entity": "contacts"
  }'

Response

{ "data": { "column_id": 1, "record_id": 101, "updated": true } }

Read a Custom Field Value

GET /fields/{column_id}/values

Reads the value of a custom column for a single contact or company record.

Path Parameters

Parameter	Type	Description
`column_id`	integer	The numeric ID of the custom field (from `GET /fields`)

Query Parameters

Parameter	Type	Default	Description
`record_id`	integer	—	R — Contact ID (`entity=contacts`) or company ID (`entity=companies`)
`entity`	string	`contacts`	`contacts` or `companies`

Example

cURL

curl "https://be.graph8.com/api/v1/fields/1/values?record_id=101&entity=contacts" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": {
    "column_id": 1,
    "record_id": 101,
    "entity": "contacts",
    "name": "udo_job_level_1712000000",
    "value": "Director"
  }
}

value is null when the column has not been set for this record.

Errors: 400 for an invalid entity; 404 when the column (for that entity) or the record does not exist.

List Contact Fields

Query Parameters

Example

Response

List Company Fields

Query Parameters

Example

Response

Create a Custom Field

Request Body

enrichment object fields

email_verification object fields

Example

Response (no enrichment)

Response (with enrichment)

Create Multiple Custom Fields

Request Body

Example

Response

Write a Custom Field Value

Path Parameters

Request Body

Example

Response

Read a Custom Field Value

Path Parameters

Query Parameters

Example

Response

`enrichment` object fields

`email_verification` object fields