Skip to main content
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.
Before you start: you need the Administrator role in the space to create, rename or reset custom fields. See Space roles.

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:
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 below.

Cometly API

The List Contacts 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 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).
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.
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 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 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

Still have questions or need a hand? We’re happy to help. Reach our team at support@cometly.com.