# Custom Fields

Declare the fields your contacts carry, give each a type, and use them everywhere by one name.

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. must be …`. See the [API reference](https://sendbeam.io/docs/api), *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](https://sendbeam.io/docs/segments/using).
- **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.

---
Source: https://sendbeam.io/docs/contacts/custom-fields