Fields

A field is a registered attribute key on one audience. It gives the attribute a label, a type and a fallback, and makes its {{merge_tag}} available in campaigns.

You rarely create one. Fields register themselves when a contact arrives with a new attribute key, same as CSV import. Unlike Mailchimp merge fields, there’s nothing to declare first. Create one explicitly only to set label, type or fallback up front.

The Field object


{
  "id": "fld_1x9k4m2v0dz7",
  "object": "field",
  "key": "company",
  "label": "Company",
  "type": "text",
  "fallback": null,
  "created_at": "2026-04-02T11:00:00.000Z",
  "updated_at": "2026-04-02T11:00:00.000Z"
}

Field	Notes
`key`	The attribute key. Immutable. Normalized to `snake_case`.
`label`	Shown in the app. Defaults from the key.
`type`	`text`, `number` or `date`.
`fallback`	Used when a contact has no value for this key.

type drives segment operators and formatting in the app. The stored value is always a string: a number field still takes "5", not 5. See Contacts.

Addressing a field

By id or by key:

/fields/fld_1x9k4m2v0dz7
/fields/company

List fields

GET/v1/audiences/{audience_id}/fields


curl https://go.day3.app/api/v1/audiences/aud_123/fields \
  -H "Authorization: Bearer $DAY3_API_KEY"

Create a field

POST/v1/audiences/{audience_id}/fields


curl -X POST https://go.day3.app/api/v1/audiences/aud_123/fields \
  -H "Authorization: Bearer $DAY3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key": "plan", "label": "Plan", "type": "text", "fallback": "free" }'

Field	Type	Required	Notes
`key`	string	Yes	Normalized to `snake_case`.
`label`	string	No	Defaults from the key.
`type`	string	No	`text` (default), `number` or `date`.
`fallback`	string	No	Used when a contact has no value.

Retrieve a field

GET/v1/audiences/{audience_id}/fields/{id_or_key}

Update a field

PATCH/v1/audiences/{audience_id}/fields/{id_or_key}

label, type and fallback can change.

key is immutable. Renaming it would orphan every stored value, so a PATCH containing key is 422 immutable_field. To rename: create the new field, rewrite the contacts, delete the old one.

Delete a field

DELETE/v1/audiences/{audience_id}/fields/{id_or_key}

Removes the registry row only. Values in contact attributes stay, and the field re-registers the next time a contact arrives with that key. To clear the values, PATCH the contacts with the key set to null.


{ "id": "fld_1x9k4m2v0dz7", "deleted": true }

Errors

Status	Code	Cause
422	`immutable_field`	A `PATCH` tried to change `key`.