Sign in
.md

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.