---
title: 'Custom Fields (Metadata)'
description: 'Store any extra key/value information on a customer — beyond the built-in fields — and fill it from a capture form, the customer screen, or the API.'
---

# Custom Fields (Metadata)

Guper customers have a set of **built-in fields** (name, e-mail, phone, document,
birthday, gender…). **Custom fields** let you store *anything else* you need about a
customer as free **key/value metadata** — for example `shirt_size`, `favorite_store`
or `kid_birthday`.

Each customer has one value per key. Values are plain text; a number or a date is
recognized automatically (useful for future reporting).

## Where custom fields show up

Every customer's metadata appears on the **Customer 360** page, in the
**Metadata** card. That's where you can read them and — with edit permission —
change them by hand.

## Three ways to fill custom fields

### 1. Capture them with a Data Capture form

When you build a **Data Capture** form (Settings → Data Capture → Forms), each
field has a **"Save as metadata"** switch:

1. Add a field (e.g. name `shirt_size`, label *Shirt size*).
2. Turn on **Save as metadata**.
3. Optionally set a **Meta Key** — the storage key. If you leave it blank, the
   field name is used. It's automatically normalized to lower-case with
   underscores (e.g. *Shirt Size* → `shirt_size`).
4. Save the form.

From then on, every submission of that form writes the captured value to the
customer's metadata.

> The form's **identifier field** (the one that matches the customer, usually
> e-mail or phone) can't be turned into metadata — it always maps to the built-in
> field.

### 2. Edit them on the Customer 360 screen

Open a customer, find the **Metadata** card and click the **pencil**. You can:

- edit the value of an existing key,
- **Add** a new key/value row,
- **remove** a row (deletes that value for this customer),

then click **Save**. New keys you type here are created automatically.

### 3. Write them through the API

Developers can read and write metadata directly:

- `GET /api/register/customer/{id}/metadata` — the customer's metadata map.
- `PUT /api/register/customer/{id}/metadata` — upsert a `{ "key": "value" }` object
  (send `null` or `""` to delete a key).

The map is also embedded as `metadata` in `GET /api/register/customer/{id}`. See the
API reference for details.

## Managing your keys (Settings → General → Custom Fields)

Keys are **created automatically** the first time a value is written for them, so
there's usually nothing to set up. The **Settings → General → Custom Fields** screen lists
every key your organization uses and lets you:

- give a key a **friendly label** (for internal clarity),
- **delete** a key — which also **removes that value from every customer**.

> Deleting a key is permanent and affects all customers. Use it only to clean up
> keys created by mistake.

## Good to know

- **Key names** are normalized to `a–z`, `0–9` and `_` (max 64 characters). *Shirt
  Size* and `shirt_size` are the same key.
- A key **can't reuse a built-in field name** (like `email` or `gender`).
- **One value per key** per customer. To keep a history or multiple values, model
  them as separate keys.
- **Segmentation:** filtering audiences by custom fields isn't available yet — it's
  planned for a future release.
