Custom Fields — Docs

Beyond name and email, a contact can carry any number of custom fields — a plan, a renewal date, a region, whether they want the weekly digest. Settings → Custom fields is where those fields are declared: each has a key, a label and a type, and the page shows how many contacts carry each one.

What a custom field is

A field has three parts:

Key — the machine name, letters, digits and underscores only, for example renewal_date. It is what you type everywhere: {{custom_fields.renewal_date}} in an email, custom_fields.renewal_date in a segment or automation rule, renewal_date as a CSV column header, a form input or an API key.
Label — what the app shows: on the contact page, in pickers, on forms. Change it whenever you like.
Type — what a value may be. See below.

Managing fields

Open Settings → Custom fields. The table lists every declared field with its label, key, type and how many contacts have a value. Add a field takes a key, a label (filled in from the key) and a type; Edit on a row changes its label, type or options; Delete removes it.

Keys your contacts already carry that no field names are listed under Keys in use without a field. Scan contacts declares them all at once, inferring a type only where every stored value agrees (all yes/no, all numbers, all dates) and using Text otherwise — a scan never picks a type a stored value would break.

Types

Text — anything up to 200 characters.
Number — a number. Segments compare it numerically ("is greater than 3").
Yes / No — true or false. The contact page offers Yes, No or not set; the API takes a boolean or yes/no/true/false.
Date — a real calendar date, stored as YYYY-MM-DD. The contact page shows a date picker; the API and CSV imports also accept an ISO date-time (its calendar date is kept) and DD/MM/YYYY. This is the type the Anniversary of a date and On a specific date automation triggers read, and their date-field picker offers only Date fields.
Dropdown — one of a fixed list of options you write, one per line. Values must match an option exactly (case is corrected for you).

Keys cannot be renamed

Once a field exists its key is fixed. The key is embedded in every email you have sent or drafted, every template, every form, every segment and automation rule, every contact's record and every integration that writes to the API — most of which a rename here could not reach, and a half-renamed field would be worse than none. Change the label instead: it is what people see. If a key really must change, add a new field and delete the old one.

Changing a type

Changing a field's type never alters stored values. If some contacts hold a value that does not fit the new type — "soon" in what is becoming a Date field — SendBeam tells you how many (with examples) and asks before changing anyway. Those values are kept exactly as they are, shown on the contact page with a Does not fit mark, and asked for again the next time that contact is saved. Segments and automations keep comparing the stored text as before. Through the API the same request is refused with 409 and a violations count until you send confirm_violations: true.

Deleting a field

Deleting a field removes it and its value from every contact, and takes it off any signup form that collected it. Segment rules, automation rules and merge tags that name it are left in place and simply stop matching or resolving — the pre-send check will point them out. This cannot be undone. A key that an integration keeps sending comes back as a new Text field the next time a value arrives.

Where values come from

Every way a value can arrive checks it against the field's type and says what is wrong:

The contact page — each field has the right input: a date picker, Yes/No, a list, a number box.
CSV import — a cell that does not fit is left out of that row (the row itself is still imported) and the import summary says which column, how many rows and an example.
Signup forms — the embed renders a date picker, a checkbox, a select or a number box to match, and the visitor is told which field needs fixing.
The API — 400 with custom_fields.<key> must be …. See the API reference, Custom fields.
Automations — a Set Field step offers only values of the field's type; a value that does not fit is reported on the automation rather than stored.

A key that has not been declared — a new CSV column, a new field on a form, a key an integration starts sending — is registered automatically as a Text field, so nothing breaks and the key becomes visible in Settings, where you can give it a type.

Using a field

Emails — the merge-tag bar in the campaign wizard and the template editor lists your fields; one click inserts {{custom_fields.key}}. Add a fallback after a pipe: {{custom_fields.plan|free}}. The pre-send check flags a tag that names a field that does not exist and suggests the one you probably meant.
Segments — pick the field from the list; the value box matches its type. See Using segments.
Automations — conditions, trigger filters, the Field changes trigger, the date triggers and Set Field all pick from the same list. Activation warns about a rule that names a field that does not exist.
Forms — tick the fields a signup form should collect; they appear as inputs on the embed and the hosted page.