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

# Custom fields

> Create custom fields in Cometly to store your own data on contacts, then filter and group reports by it and fill it from your integrations.

Custom fields in Cometly let you add your own data points to contacts. A contact is a person Cometly has tracked, such as a lead or a customer. Cometly stores standard information about each contact out of the box, and custom fields hold the data that is unique to your business.

Once a value is stored on your contacts, you can filter and group your reports by it. That lets you break down your ad performance by your own segments, for example to see which business type converts best.

> [!NOTE]
>
> **Before you start:** you need the Administrator role in the space to create, rename or reset custom fields. See [Space roles](https://docs.cometly.com/guides/account/space-roles.md).

## What are custom fields?

Custom fields are extra fields on your contacts that you name and define yourself. You can store, filter and report on the values you put in them.

For example, you might create custom fields for:

* **Business Type** (text), to tag contacts as "E-commerce", "SaaS", "Agency" and so on.
* **Lifetime Value** (number), to store a numeric value you calculate outside of Cometly.
* **Trial End Date** (date), to track when a contact's free trial expires.

## Field types and limits

Each space (a workspace in your Cometly account) can have up to **30 custom fields**, split across three data types:

| Type | Max fields | Field keys | Best for |
| - | - | - | - |
| **Text** | 15 | `profile_field_1` to `profile_field_15` | Labels, categories, tags, IDs, free-form text |
| **Number** | 10 | `profile_field_16` to `profile_field_25` | Revenue, scores, quantities, percentages |
| **Date** | 5 | `profile_field_26` to `profile_field_30` | Dates and timestamps (sign-up date, renewal date and so on) |

> [!WARNING]
>
> You cannot change a field's data type after you create it. Choose carefully. If you need a different type, reset the field and create a new one, which deletes all existing data for that field.

## Where custom fields are used

### Contacts

Every contact page has a **Custom Fields** panel that shows the contact's values. Click **Edit** in that panel to change them. Text fields show a text input, number fields a numeric input and date fields a date picker.

On the **Contacts** list, open the **Columns** menu to show custom fields as columns.

### Report Builder: Group By

Custom fields are available as **Group By** options in the Report Builder, so you can break down your metrics by any custom field. For example, group by "Business Type" to see which segment converts best.

### Report Builder: Filters

Custom fields are also available as **Filters** in reports, in the **Contact** group. The operators match the field type:

* **Text fields:** text operators (is, contains, starts with and so on)
* **Number fields:** numeric operators (is greater than, is less than, is equal to and so on)
* **Date fields:** date operators (before, after, is between and so on)

### Webhooks and integrations

When you send event data into Cometly (an event is a tracked action, such as a lead or a purchase), you can include custom field values. If your payload uses the field keys (`profile_field_1`, `profile_field_2` and so on), Cometly fills the matching custom fields on the contact. See [Send custom field data](#send-custom-field-data) below.

### Cometly API

The [List Contacts](https://docs.cometly.com/api-reference/endpoint/list-contacts.md) endpoint returns custom field values when you pass `include_custom_fields=1`. This is useful for building external dashboards or syncing data to other platforms.

## Set up custom fields

**1. Open the custom fields settings**

Click **Settings** at the bottom of the sidebar, then click **Custom contact fields** under **Workspace**.

The page lists the fields you have already created and shows how many of the 30 fields are in use.

**2. Create a new field**

1. Click **Add Custom Field**.

2. Enter a **Field Name**. This is the label shown throughout the app (for example "Business Type", "Lead Score", "Signup Date"). Keep it short and descriptive.

3. Select a **Data Type**: Text, Number or Date. The menu shows how many fields of each type you have left. The type cannot be changed later.

4. Click **Add Field**.

Cometly assigns the next free field key for that type. You do not choose the key yourself.

**3. Start using your field**

The field is available across the app straight away:

* **On contacts:** open any contact from **Contacts** and you will see the new field in the **Custom Fields** panel. Click **Edit** to enter a value.
* **In reports:** open the **Report Builder**. The field appears in both **Group By** and **Filters**.
* **In event data:** send the field with your events, as described in the next section.

## Check it worked

The new field appears in the table on the custom fields settings page with its **Label**, **Field Key** and **Data Type**, and the field count at the top of the table goes up by one. Open any contact from **Contacts** and the field is listed in the **Custom Fields** panel.

## Send custom field data

There are three ways to fill custom fields. Choose the one that fits how you already send events to Cometly.

### From an integration (mapping step)

When you set up an event for an integration in the **Events Manager**, you go through a field mapping step. This is where you tell Cometly which fields from your integration correspond to which Cometly fields.

* Your custom fields appear in the list of Cometly fields under the name you gave them (for example "Business Type", "Lead Score").
* Map the matching field from your integration to the custom field.
* Save the mapping.

From then on, every event that comes through that integration fills the custom field on the matching contact.

### From a webhook (mapping step)

When you send data into Cometly with a webhook, your payload can use any field names. They do not need to match Cometly's field keys, because you map them yourself.

* Set up the event with **Webhooks** as the integration.
* Send a test event with your payload so Cometly can detect your fields.
* In the mapping step, you see the Cometly fields (including your custom fields) next to the fields from your payload.
* Map your fields to the matching custom fields (for example, map your `business_category` to your "Business Type" custom field).
* Save the mapping.

You can find each field's key on the custom fields settings page, in the **Field Key** column.

### From the Cometly API

You can also send custom field values with the [Create Event](https://docs.cometly.com/api-reference/endpoint/create-event.md) endpoint. Unlike webhooks, there is no mapping step: the keys in your payload must exactly match the field keys in your space (for example `profile_field_1`, `profile_field_16`).

```json theme={null}
{
  "email": "jane@example.com",
  "profile_field_1": "E-commerce",
  "profile_field_16": 4500.00,
  "profile_field_26": "2026-03-01"
}
```

Each field's exact key is in the **Field Key** column on the custom fields settings page. If your payload uses a different key, the data is not saved to the field.

## Rename a custom field

Click **Edit** next to the field on the custom fields settings page, change the **Field Name** and click **Save**. Only the label changes. The field key, the data type and the stored data stay the same.

## Reset a custom field

To remove a custom field, click **Reset** next to it, then confirm with **Yes, reset this field**.

> [!WARNING]
>
> Resetting is permanent and cannot be undone. When you reset a field:
>
> * The field's name and configuration are removed.
> * All data stored in that field, on every contact in the space, is permanently deleted.
> * Webhook mappings, report filters and Group By settings that use the field stop working.
> * The field key becomes available for a new field.

## Tips and best practices

* **Plan your fields before creating them.** Think about what data you need for reporting and segmentation. It is easier to set things up right from the start than to reset and recreate fields later.
* **Use consistent naming.** If several people create fields, agree on a naming convention so labels are clear in reports.
* **Choose the right type.** If a value is always numeric (a score or a dollar amount), use a Number field. This gives you numeric filters (is greater than, is less than) in reports. Do not store numbers as Text.
* **Automate with webhooks.** Instead of editing custom fields by hand on each contact, send the data through your webhooks. This fills custom fields automatically from your CRM, checkout system or backend.
* **Watch your usage.** Each type has a fixed number of fields (15 text, 10 number, 5 date). The **Data Type** menu in the **Add Custom Field** dialog shows how many remain for each type.

## Frequently asked questions

### Is there a character limit for a custom text field in Cometly?

Yes. Text fields accept up to 10,240 characters.

### Can I update custom field values with the Cometly API without sending an event?

Yes. The [Update Contact](https://docs.cometly.com/api-reference/endpoint/update-contact.md) endpoint accepts a `custom_fields` object that uses the field keys (for example `profile_field_1`). It replaces the whole set: any field key you leave out is cleared on that contact, so send every value you want to keep.

### Can I export custom fields to my data warehouse?

Yes. The [Contacts dataset](https://docs.cometly.com/data-warehouse/datasets/contacts.md) can include your space's custom fields as columns. When you create the export, you choose whether those columns are named by field key or by the field's label.

## Next steps

* [Build a report](https://docs.cometly.com/guides/report-builder/build-a-report.md) and use your custom fields in **Group By** and **Filters**.
* [How events work](https://docs.cometly.com/guides/events/how-events-work.md), to understand the events that carry custom field values.
* [Create Event](https://docs.cometly.com/api-reference/endpoint/create-event.md), to send custom field values from your own backend.
* [List Contacts](https://docs.cometly.com/api-reference/endpoint/list-contacts.md), to read custom field values back out of Cometly.
* [Space roles](https://docs.cometly.com/guides/account/space-roles.md), to see who can manage custom fields.

Still have questions or need a hand? We're happy to help. Reach our team at [support@cometly.com](mailto:support@cometly.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.