Creating Custom Fields (Types: Text, Numeric, Date)

Custom contact fields let you store project-specific information on contacts beyond the built-in fields, by creating fields in Contacts → Fields (choosing the correct type like Text, Number, or Date & Time, setting agent access, and optionally featuring the field), then using the field reference in flows (for example via Update Contact with @results variables) so data stays consistent across messages, exports, and automation.
Reading time
6–7 min read
Category
Contacts
Updated on
Updated on: 23/12/2025

Create and use custom contact fields in a few steps

If you just need the essentials, follow this:

  1. Open Contacts → Fields to access Manage Contact Fields
  2. Click New Field, name it, and choose the correct type (Text/Number/Date & Time)
  3. Set Agent access (Hidden/View/Edit) and optionally enable Featured
  4. Use the field reference in flows: @contact.fields.field_name
  5. Update values on contacts or in flows using Update Contact (values up to 640 characters)

You’re done. Your workspace can now capture consistent project data and use it in automation and reporting.

Step-by-Step Process

1
Understand default vs custom fields

Contacts store information in contact fields (for example: name, phone number, district, registration date). RapidPro.app fields fall into two categories:
default fields (built-in, like Name and Language) and custom fields (fields you create for your project).
Custom fields can store different value types (such as text, number, or date & time), depending on how you configure the field.

⚙️
Note: If you plan to use a custom field in campaign scheduling, make sure the field is configured as Date & Time.

2
Create custom contact fields manually

  1. Go to Contacts.
  2. Click Fields.
  3. On the Manage Contact Fields page, click New Field (top right).

[CAPTURE: Contacts page with the “Fields” button visible.]
[CAPTURE: Manage Contact Fields page showing the fields list.]
[CAPTURE: Manage Contact Fields page with “New Field” button highlighted.]

  1. In the New Field dialog, enter a Name.
  2. Choose the Field type (Text / Number / Date & Time, etc.).
  3. Set Agent access: Hidden, View, or Edit.
  4. Optional: Enable Featured to show the field near the top of the contact page.
  5. Save.

[CAPTURE: New Field dialog showing Name, Field type, Agent access, and Featured option.]

💡
Tip: Use clear, consistent field names like district, age, registration_date so they’re easy to find in flows and exports.

3
Find the field reference for flows and messages

On the Manage Contact Fields page, each field shows how it can be referenced in flows and messages. Custom fields generally follow this format:
@contact.fields.field_name.

[CAPTURE: Manage Contact Fields page showing a field and its reference/variable format.]

⚙️
Note: Default fields may use direct references (like @contact.name), while custom fields use @contact.fields.<field>.

4
Feature a field and edit values on a contact

Mark a field as Featured

  1. Go to Contacts → Fields.
  2. Click the field you want to update.
  3. Enable Featured (Featured field).
  4. Save.

[CAPTURE: Field edit panel showing “Featured field” enabled.]

Edit custom field values on a contact

  1. Go to Contacts and open a contact.
  2. Click Fields on the contact profile.
  3. Enter or update values for the custom fields.
  4. Save.

[CAPTURE: Contact profile page with “Fields” opened showing custom field values.]

💡
Tip: Keep numeric fields numeric. If a field is set as “Number”, entering non-numeric text may fail validation or cause unexpected behavior in flows.

5
Create or update a custom field in a flow

You can create new custom fields (or update existing ones) directly inside a flow using Update Contact.
Collect data (for example using Wait for Response), then write it to a field using a results variable like @results.variable_name.

  1. In your flow, collect data from the contact.
  2. Add an Update Contact action.
  3. Choose an existing field, or type a new field name to create one.
  4. Set the value using @results.variable_name.
  5. Click OK and save the flow.

[CAPTURE: Flow editor showing a “Wait for Response” followed by “Update Contact”.]
[CAPTURE: Update Contact dialog showing a field name and value set to @results.variable_name.]
[CAPTURE: Flow canvas showing the Update Contact action saved.]

⚙️
Note: A single contact field can store up to 640 characters.

Common Issues & Quick Fixes

Problem: I can’t use a custom field in a campaign.

Fix: The field may not be a Date & Time field. Edit the field in Contacts → Fields and change the type to Date & Time (if appropriate for your use case).

Problem: Agents can’t see or edit a field.

Fix: Edit the field in Contacts → Fields and update Agent access to View or Edit.

Problem: The field exists but isn’t updating in the flow.

Fix: Confirm the results variable exists (spelling/case) and that the flow path reaches the Update Contact action.

Related Resources
Managing Contact Fields: Create, Modify, and Delete
Editing the Value of a Field (Manually or via Flow)
Bulk Import Contacts using an XLS File (Excel)