> ## Documentation Index
> Fetch the complete documentation index at: https://documents.xobito.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Fields

> Store any extra data you need about a contact — plan tier, birthday, account number — using six field types.

**Custom fields** let you extend a contact's record with any data point that matters to your business. Think birthday, account number, subscription tier, loyalty points, preferred language — anything you'd otherwise keep in a separate spreadsheet.

## Why custom fields matter

Custom fields are what make WhatsApp messaging feel personal at scale. Once a field exists, you can:

* **Show the data on the contact form** for every team member.
* **Import the data in bulk** from CSV.
* **Capture the data via Bot Flows** and store it back on the contact.

Custom field values are stored on each contact in a single JSON object keyed by the field's slug.

## The six field types

Xobito supports six custom-field types — pick the right one when you create the field:

| Type                        | What it stores                    | Typical use                               |
| --------------------------- | --------------------------------- | ----------------------------------------- |
| **Text Field**              | Single-line free text (max 255)   | Short notes, IDs, short labels            |
| **Text Area**               | Multi-line text (max 2000)        | Longer notes, addresses, descriptions     |
| **Number Field**            | Numeric value                     | Loyalty points, account balance, age      |
| **Date Field**              | A calendar date                   | Birthday, renewal date, sign-up date      |
| **Dropdown**                | One value from a fixed list       | Plan tier, region, priority               |
| **Multi-select Checkboxes** | Multiple values from a fixed list | Preferences, interests, opt-in categories |

<Tip>
  Use **Dropdown** whenever the values come from a short, fixed list — it keeps your data clean and prevents typos like "pro", "PRO", and "proo". Use **Checkboxes** when more than one value can apply at once (e.g. "Interested in: Offers, Newsletter, Events").
</Tip>

## What's on a custom field

Each custom field has these attributes:

| Attribute             | Description                                                                                     |
| --------------------- | ----------------------------------------------------------------------------------------------- |
| **Field label**       | The human-readable name shown on the contact form.                                              |
| **Field name (slug)** | The machine-friendly name — used as the CSV column name and the key in the contact's JSON data. |
| **Field type**        | One of the six types above.                                                                     |
| **Options**           | For Dropdown and Checkboxes — the list of allowed values.                                       |
| **Placeholder**       | Grey hint text shown inside empty inputs.                                                       |
| **Description**       | Help text shown below the field on the contact form.                                            |
| **Default value**     | Pre-filled when creating a new contact.                                                         |
| **Is required**       | If on, the field must be filled before a contact can be saved.                                  |
| **Display order**     | Determines where the field appears on the form — managed automatically per workspace.           |
| **Is active**         | Lets you hide a field without deleting it.                                                      |
| **Show on table**     | Whether the field appears as a column on the main contact list.                                 |

## Open the Custom Fields library

In the sidebar, go to **Contacts → Custom Fields**. You'll see every custom field your workspace has defined, along with its slug, field type, and options.

## Create a custom field

<Steps>
  <Step title="Click 'Add Custom Field'">
    Opens the field form.
  </Step>

  <Step title="Enter a label">
    The human-readable name, e.g. "Birthday" or "Plan Tier".
  </Step>

  <Step title="Set the slug">
    The slug is auto-generated from the label (e.g. `birthday`). It's used as the CSV column name and is how the value is stored on each contact. Use lowercase letters, digits, and underscores.
  </Step>

  <Step title="Choose the field type">
    Pick from Text, Text Area, Number, Date, Dropdown, or Multi-select Checkboxes.
  </Step>

  <Step title="Add options (Dropdown / Checkboxes only)">
    If you picked Dropdown or Checkboxes, list the allowed values one per line.
  </Step>

  <Step title="Fill in helper settings (optional)">
    Placeholder, description, and default value to guide your team as they fill out contacts.
  </Step>

  <Step title="Mark as required (optional)">
    If this field must be filled for every new contact, tick **Required**. Required fields block saving a contact if left empty, and reject CSV rows that don't include the column.
  </Step>

  <Step title="Toggle 'Show on table' (optional)">
    If you want this field to appear as a column on the main contact list, turn this on.
  </Step>

  <Step title="Save">
    The field appears immediately on the contact form, CSV imports, and (if enabled) the contact-list columns.
  </Step>
</Steps>

## Edit or delete a custom field

<Steps>
  <Step title="Open Custom Fields library">
    Find the field in the list.
  </Step>

  <Step title="Edit or Delete">
    Editing lets you change the label, options, placeholder, description, required, active, or show-on-table settings. Deleting removes the field **and every contact's value for it** permanently.
  </Step>
</Steps>

<Warning>
  Deleting a custom field wipes all values stored for it across every contact. Export your contacts first if you might need the data later.
</Warning>

## Fill in a custom field value

### On the contact form

Every active custom field appears below the standard fields on the add-contact and edit-contact forms. Fill them in when adding or editing a contact.

### During CSV import

Add a column whose header matches the field's **slug** (not the label). See [Import from CSV](/contacts/import-csv).

```csv theme={null}
firstname,lastname,type,phone,status_id,source_id,plan,birthday,loyalty_points
Alex,Morgan,customer,+14155551234,2,1,Pro,1990-05-12,500
Priya,Shah,lead,+919876543210,1,3,Basic,1988-11-02,120
```

### Via a Bot Flow

A **Bot Flow** can ask the contact a question and store their reply in a custom field. Example: "What's your account number?" → store the reply in the `account_number` field. See [Bot Flows](/automations/bot-flows).

## Data type rules

| Type                    | Accepted input                                                              |
| ----------------------- | --------------------------------------------------------------------------- |
| Text Field              | Any text up to 255 characters.                                              |
| Text Area               | Any text up to 2000 characters.                                             |
| Number Field            | Numeric values only — `500`, `49.99`. Text like "five hundred" is rejected. |
| Date Field              | A valid date. Invalid dates are rejected on the form and skipped in CSV.    |
| Dropdown                | Must match one of the options you defined.                                  |
| Multi-select Checkboxes | One or more values from the defined options.                                |

Invalid values on the contact form show an inline error. Invalid values in a CSV cause the row to be skipped — with the exact reason in the import log.

## Custom fields in the API

<Note>
  Custom fields are stored on each contact, but are **not currently serialised into the contact API response**. If you call Xobito's contact list or read API, the custom-field values will not be included in the payload. This is a known limitation — for now, custom fields are most useful inside the Xobito UI, in CSV imports, and in Bot Flows. See [Developer API](/developers/overview) for the latest details.
</Note>

## Best practices

<AccordionGroup>
  <Accordion title="Plan your fields before importing">
    Create every custom field you need **before** your first CSV import. Retrofitting fields after import means re-uploading data.
  </Accordion>

  <Accordion title="Prefer Dropdown / Checkboxes over free text for finite values">
    If the value has a handful of possible options, use Dropdown or Checkboxes. Dirty free-text ("pro", "Pro", "PRO") ruins segmentation.
  </Accordion>

  <Accordion title="Use slug-friendly labels">
    Slugs like `plan_tier` or `last_purchase_date` are easier to use in CSV and in automations than "Plan Tier (2026)".
  </Accordion>

  <Accordion title="Be careful with 'required'">
    Required custom fields block manual entry and reject CSV rows without the column. Only mark a field required if you truly have data for every contact, every time.
  </Accordion>

  <Accordion title="Avoid storing sensitive data">
    Don't store passwords, full payment details, or government ID numbers in custom fields. Xobito is a messaging platform — not a secure vault.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Dynamic templates" icon="wand-magic-sparkles" href="/templates/dynamic-templates">
    Merge contact data into template variables at send time.
  </Card>

  <Card title="Import from CSV" icon="file-csv" href="/contacts/import-csv">
    Populate custom fields in bulk from a spreadsheet.
  </Card>

  <Card title="Bot flows" icon="diagram-project" href="/automations/bot-flows">
    Capture contact replies and store them in custom fields.
  </Card>

  <Card title="Developer API" icon="code" href="/developers/overview">
    Read and write contact data programmatically.
  </Card>
</CardGroup>