What Are Custom Fields?
Custom fields let you add your own data points to contact profiles in Cometly. Out of the box, Cometly tracks standard information about your contacts but every business is different. Custom fields give you the flexibility to store, filter, and report on data that's unique to your business.
For example, you might create custom fields for:
Business Type (text) — to tag contacts as "E-commerce," "SaaS," "Agency," etc.
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 & Limits
Each space can create up to 30 custom fields, split across three data types:
Type | Max Fields | Best For |
Text | 15 | Labels, categories, tags, IDs, free-form text |
Number | 10 | Revenue, scores, quantities, percentages |
Date | 5 | Dates and timestamps (sign-up date, renewal date, etc.) |
Once you choose a type for a field, it cannot be changed later. Choose carefully.
Where Custom Fields Are Used
Custom fields aren't just stored, they're integrated throughout Cometly. Here's where they show up:
1. Contact Profiles (Journeys)
Every contact profile displays its custom field values. You can view and edit values directly on a contact's profile page. Text fields show a text input, number fields show a numeric input, and date fields show a date picker.
2. Reports — Group By
Custom fields are available as Group By options in the report builder. This means you can break down your metrics by any custom field. For example, group your ad performance by "Business Type" to see which segment converts best.
3. Reports — Filters
Custom fields are also available as filters in reports. The filter type matches the field type automatically:
Text fields → string-based filters (equals, contains, etc.)
Number fields → numeric filters (greater than, less than, equals, etc.)
Date fields → date range filters
4. Webhooks & Integrations
When you send event data into Cometly via webhooks, you can include custom field values in the payload. Use the field keys (profile_field_1, profile_field_2, etc.) in your webhook data, and Cometly will automatically map them to the correct contact profile. This is powerful for syncing data from your CRM, backend, or other tools.
5. Public API
The Cometly Public API supports custom fields on the List Contacts endpoint. Pass the include_custom_fields parameter to include all custom field values in the API response, useful for building external dashboards or syncing data to other platforms.
How to Set Up Custom Fields
Step 1: Navigate to Custom Fields Settings
Go to Space Setup
In the Additional Setup section, click Custom Contact Fields
You'll see a list of any fields that have already been created, along with a count of remaining slots for each type.
Step 2: Create a New Field
Click the Add Custom Field button
Enter a Field Name — this is the label that will appear throughout the app (e.g., "Business Type," "Lead Score," "Signup Date"). Keep it short and descriptive.
Select a Field Type — choose Text, Number, or Date. This cannot be changed later.
Save the field
Cometly automatically assigns the next available field slot for that type. You don't need to worry about the underlying field key, it's handled for you.
Step 3: Start Using Your Field
Once created, the field is immediately available across the app:
On contact profiles — navigate to any contact in Journeys and you'll see the new field. Click to edit and enter a value.
In reports — open the report builder and your new field will appear in both the Group By and Filter dropdowns.
Via webhooks — include the field key (shown in the settings table, e.g., profile_field_1) in your webhook payloads to populate values automatically.
Sending Events & Including Custom Fields Data
Once you've created your custom fields, the next step is getting data into them. There are three ways to populate custom field values, choose the method that fits your existing workflow for sending events to Cometly.
From Integrations (Mapping Step)
When you connect an integration in Cometly, you'll go through a field mapping step. This is where you tell Cometly which fields from your integration correspond to which fields in Cometly.
Go to Integrations and select your connected integration
During the mapping step, you'll see a list of available Cometly fields on one side and your integration's fields on the other
Your custom fields will appear in the Cometly field list by the name you gave them (e.g., "Business Type," "Lead Score")
Map the matching field from your integration to the custom field
Save the mapping
From that point on, every event that comes through that integration will automatically populate the custom field on the matching contact profile.
From Webhooks (Mapping Step)
When sending data into Cometly via webhooks, you can include any fields you want in your payload, the field names don't need to match Cometly's field keys. During the mapping step, you'll tell Cometly which of your fields correspond to which custom fields.
Go to your Webhook setup
Send a test event with your payload so Cometly can detect your fields
During the mapping step, you'll see your incoming payload fields on one side and the list of available Cometly fields on the other — including your custom fields
Map your fields to the corresponding custom fields (e.g., map your business_category to your "Business Type" custom field)
Save the mapping
Since you're mapping manually, your payload fields can be named anything. Cometly will handle the translation based on your mapping configuration.
You can find each field's key on the Custom Fields settings page next to the field name.
From the Public API
You can also send custom field values through the Cometly Public API. Unlike webhooks, the field keys in your API payload must exactly match the field keys in your account (e.g., profile_field_1, profile_field_16).
There is no mapping step, the data is matched directly by key for sending events to Cometly using the Public API.
{
"email": "jane@example.com",
"profile_field_1": "E-commerce",
"profile_field_16": 4500.00,
"profile_field_26": "2026-03-01"
}
You can find each field's exact key on the Custom Fields settings page next to the field name. Make sure your API payload uses these keys exactly as shown, otherwise the data won't be mapped.
Editing a Custom Field
You can rename a custom field at any time from the Custom Fields settings page. The underlying data is not affected, only the display label changes.
Deleting a Custom Field
You can delete a custom field from the settings page. This is permanent and irreversible. When you delete a field:
The field configuration is removed
All data stored in that field across every contact profile is erased
The field slot becomes available for reuse
Always double-check before deleting a field. There is no undo.
Tips & Best Practices
Plan your fields before creating them. Think about what data you need for reporting and segmentation. It's easier to set things up right from the start than to delete and recreate later.
Use consistent naming. If multiple team members are creating fields, agree on a naming convention so labels are clear and recognizable in reports.
Choose the right type. If a value is always numeric (like a score or dollar amount), use a Number field. This unlocks numeric filters (greater than, less than) in reports. Don't store numbers as Text.
Leverage webhooks for automation. Instead of manually editing custom fields on each contact, send the data in through your webhook integrations. This lets you automatically populate custom fields from your CRM, checkout system, or backend.
Monitor your usage. You have a fixed number of slots per type (15 text, 10 number, 5 date). The settings page shows how many remain. If you're running low, consider whether any existing fields can be cleaned up.
Custom Fields FAQ
Can I change a field's type after creating it?
No. The field type (text, number, or date) is locked once created. If you need a different type, delete the field and create a new one, but keep in mind that deleting erases all existing data for that field.
What happens to my reports if I delete a custom field?
Any reports that group by or filter on a deleted field will no longer have that data available. The field will no longer appear as an option.
Can I use custom fields with the Public API?
Yes. When calling the List Contacts endpoint, set include_custom_fields to true and all 30 profile field values will be included in the response.
How do I send custom field values through a webhook?
Include the field key (e.g., profile_field_3) in your webhook payload. Cometly will map it to the corresponding contact profile automatically. You can find the field key for each custom field on the Custom Fields settings page.
Is there a limit to how much text I can store in a text field?
Text fields support up to 255 characters.