Discovering Real Audience Fields with the Clay CLI

List every field id and data type actually available on people or companies before writing a filter, a signal, or sequence copy, using Clay's real audiences fields list command, which is the single source of truth for what key values a filter AST can reference.

What you will build

A field discovery pass over both entity types, plus creating and updating a custom field of your own.

clay audiences fields list --entity-type <type> --include-system
    ↓
{ id, name, dataType, isDefaultField, isSystemField } per field
    ↓
clay audiences fields create / update

AI Prompt

Using the Clay CLI, discover real field ids and data types on Audiences
entity types, and create/update a custom field.

Requirements:
- `clay audiences fields list --entity-type <people|companies>
  [--include-system]` -- system fields (created_at, updated_at,
  origin_source_id, etc.) are hidden unless --include-system is passed.
- Each field's "id" is what filter ASTs and record payloads key on -- NOT
  its "name" (display name). Companies has real fields like org_name,
  industry, employee_count, domain, revenue, linkedin_url; people has name,
  first_name, title, email, linkedin_url, seniority, department.
- `clay audiences fields create --entity-type <type> --name <name>
  [--data-type <type>] [--field-type <type>]` creates a new field. A name
  already in use is auto-suffixed (e.g. "Tier (2)") rather than rejected --
  always read the RETURNED name, don't assume the one you passed stuck.
- `clay audiences fields update <fieldId> --entity-type <type> [--name]
  [--description] [--data-type] [--hidden] [--order]` changes only the
  fields you pass. Default/system fields reject --name/--data-type changes
  but allow --hidden/--order/--description.
- `clay audiences fields segments <fieldId> --entity-type <type>` lists
  every audience whose filter references that field -- check this before
  changing a field's data type or deleting it.
- Run the verification step below before finishing.

Using the Clay CLI, discover real field ids and data types on Audiences
entity types, and create/update a custom field.

Requirements:
- `clay audiences fields list --entity-type <people|companies>
  [--include-system]` -- system fields (created_at, updated_at,
  origin_source_id, etc.) are hidden unless --include-system is passed.
- Each field's "id" is what filter ASTs and record payloads key on -- NOT
  its "name" (display name). Companies has real fields like org_name,
  industry, employee_count, domain, revenue, linkedin_url; people has name,
  first_name, title, email, linkedin_url, seniority, department.
- `clay audiences fields create --entity-type <type> --name <name>
  [--data-type <type>] [--field-type <type>]` creates a new field. A name
  already in use is auto-suffixed (e.g. "Tier (2)") rather than rejected --
  always read the RETURNED name, don't assume the one you passed stuck.
- `clay audiences fields update <fieldId> --entity-type <type> [--name]
  [--description] [--data-type] [--hidden] [--order]` changes only the
  fields you pass. Default/system fields reject --name/--data-type changes
  but allow --hidden/--order/--description.
- `clay audiences fields segments <fieldId> --entity-type <type>` lists
  every audience whose filter references that field -- check this before
  changing a field's data type or deleting it.
- Run the verification step below before finishing.

Prerequisites

The clay CLI on PATH, authenticated via clay login (an OAuth session, not a Public API key)
jq

Note: JSON samples below are trimmed to the fields relevant to each step. Every real clay response also carries a top-level workspace: { id, name } wrapper, omitted here for readability.

1. List real fields on companies

clay audiences fields list --entity-type companies --include-system | jq -r '.data[] | "\(.id)  \(.dataType)"'

clay audiences fields list --entity-type companies --include-system | jq -r '.data[] | "\(.id)  \(.dataType)"'

Real output (excerpt): org_name text, industry text, employee_count number, domain url, revenue text, linkedin_url url.

2. Create a custom field

clay audiences fields create --entity-type companies --name "TPC Docs Test Tier" --data-type text

clay audiences fields create --entity-type companies --name "TPC Docs Test Tier" --data-type text

Real output:

{
  "id": "audf_0tl868ddS9GKenf9txc",
  "name": "TPC Docs Test Tier",
  "entityType": "companies",
  "fieldType": "scalar",
  "dataType": "text",
  "isDefaultField": false,
  "isSystemField": false
}

{
  "id": "audf_0tl868ddS9GKenf9txc",
  "name": "TPC Docs Test Tier",
  "entityType": "companies",
  "fieldType": "scalar",
  "dataType": "text",
  "isDefaultField": false,
  "isSystemField": false
}

3. Update the field and check what references it

clay audiences fields update audf_0tl868ddS9GKenf9txc --entity-type companies --description "TPC docs test field"
clay audiences fields segments industry --entity-type companies

clay audiences fields update audf_0tl868ddS9GKenf9txc --entity-type companies --description "TPC docs test field"
clay audiences fields segments industry --entity-type companies

Real output for fields segments industry, the one audience whose filter references industry:

{"data": [{"id": "audseg_0tl84p1ZQ8RRShHSAdX", "name": "TPC CLI Docs Test Companies", "entityType": "companies"}]}

{"data": [{"id": "audseg_0tl84p1ZQ8RRShHSAdX", "name": "TPC CLI Docs Test Companies", "entityType": "companies"}]}

Verify the result

Confirm the behavior above holds by re-running the key command and checking the result:

clay audiences fields create --entity-type companies --name "TPC Docs Test Tier" --data-type text

clay audiences fields create --entity-type companies --name "TPC Docs Test Tier" --data-type text

Expected: A new custom field is created on the companies entity type with a real generated id, confirmed to appear in a subsequent clay audiences fields list call.

How it works

Every filter-accepting command in Audiences (create, update, signals filters, records search-count/search-ids) keys on a field's id, not its display name; fields list is the one command that tells you what those ids actually are in a given workspace, since custom fields and their ids are workspace-specific. fields segments exists specifically to answer "what breaks if I change this" before you change a field's type or delete it, since a saved audience's filter can silently stop matching what it used to if the underlying field's type shifts under it.

Common issues

Guessing a field's `id` from its display name

Cause: assuming id is always a lowercased, underscored version of the display name (which happens to be true for most default fields).

Fix: it's true often enough to be misleading: always confirm with fields list rather than assuming, especially for custom fields.

Assuming `fields create --name` always uses the exact name passed

Cause: most create commands echo back exactly what you sent.

Fix: a duplicate name is auto-suffixed (e.g. "Tier (2)") rather than rejected: read the field's returned name, don't assume it matches your input.

Next steps

Reference discovered field ids directly in a new audience's filter with clay audiences create --filter.
Check fields segments before running fields update --data-type on a field any audience already filters on.

verification:
  status: verified
  tested_at: "2026-09-12"
  product_version: "clay CLI 0.19.0"
  command: "clay audiences fields create --entity-type companies --name \"TPC Docs Test Tier\" --data-type text"
  expected_result: "A new custom field is created on the companies entity type with a real generated id, confirmed to appear in a subsequent clay audiences fields list call."

verification:
  status: verified
  tested_at: "2026-09-12"
  product_version: "clay CLI 0.19.0"
  command: "clay audiences fields create --entity-type companies --name \"TPC Docs Test Tier\" --data-type text"
  expected_result: "A new custom field is created on the companies entity type with a real generated id, confirmed to appear in a subsequent clay audiences fields list call."