Creating Additional Fields

Additional fields in contact cards store specific information about contacts, such as personal promo codes, important dates, locations, and preferences. You can use this data for advanced contact segmentation and deeper personalization of communications.

Additional Fields Tab

Additional fields are available in the account settings on the Additional fields tab. By default, the account contains only the Personal list with the Birthday and Gender fields.

The additional fields list displays:

1. Field type, such as text input or date.
2. Field name.
3. Variable used for message personalization and as the field key in SDK requests.
4. Field ID.
5. Edit field button.
6. Delete button.

You can create lists and add fields to them.

Creating a List

Lists help you group fields by purpose, such as personal data or product preferences. To create a field list:

1. Click New list of fields.

2. Enter the list name.

3. If necessary, change the personalization key generated automatically from the list name. The key is used to build variables for the fields in this list, so choose a short and clear value.

4. Click Save.

📘

Note

• The list remains inactive until you add its first field.
• Before deleting a list that contains fields, delete all fields from the list.

Adding Fields

1. Click the plus icon to create a field in the list.

2. Enter the field name and, if necessary, edit the automatically generated personalization key.

3. Select the field type. Text input is selected by default.

📘

Note

A field's type can't be changed after creation — for example, you can't switch an existing field from Date and time to Date. To use a different type, create a new field.

Field Types

Depending on the contact data type, the following field types are available:

• Text input can contain up to 1,000 characters, including letters and integers. Special characters are not supported. Use this type, for example, to store a contact's name or address.
• Text area can contain up to 5,000 characters, including letters and integers. Special characters are not supported. Use this type, for example, to store answers to open-ended questions.
• Number can contain only integer values from -2147483647 to 2147483647, such as an order ID or the number of bonuses.
• Fractional number can contain integers and decimal values, such as the total order amount.
• Date — values must use the ISO 8601 format: YYYY-MM-DD. Use the Regular date option when creating dynamic segments for communication related to recurring events, such as anniversaries or birthdays.

• Date and time — accepted formats are YYYY-MM-DDTHH:mm:ssZ for UTC and YYYY-MM-DDTHH:mm:ss±HH:mm with a UTC offset. Use this type for date-and-time values, such as promo code validity periods.
• Drop-down list contains predefined values, such as a contact's gender, status, or language.

📘

Important

Do not use a period (.) in the field name. For example, use Marital status or Marital_status instead of Marital.status.

• Checkbox allows you to store multiple selected values.

📘

Note

The set of options for a Checkbox field is fixed when the field is created — you can't add or remove options afterward. If you need a different set of options, create a new field.

📘

Note

There's no API endpoint for creating additional fields. The API below only lets you retrieve the list of existing fields (with Get additional fields) and update a contact's value for one of those fields — pass the field's numeric ID and the new value in the fields array of the Add/update contacts method, as shown below. Neither call creates a new field. You can create a field two ways: through this UI, or by importing a file with a column for it — unmapped columns are auto-created as new fields during field mapping. File import only supports the Text input, Text area, Number, Fractional number, Date, and Date and time types; Drop-down list and Checkbox fields still need to be created manually, since their predefined option lists aren't set during import.

To replicate the same field set across multiple accounts, use Get additional fields to list the field names, types, and allowed values from one account, then recreate them in each other account — manually, or for the supported types, by importing a small file (for example, one placeholder contact with a column per field) to auto-create them. The field definitions remain even after you delete the contact that created them. Avoid uploading real customer data to another account just to replicate fields — use placeholder data instead.

Working with Additional Fields via API

Retrieving the Field List

To retrieve additional field lists and their IDs, keys, types, and allowed values, use the Get additional fields method:

GET /api/v1/additionalfields

You can pass the ID returned in additionalFields[].id as fields[].id when adding or updating contacts.

After you create an additional field, synchronization may take up to one hour. Until synchronization is complete, the field may be unavailable through the API.

📘

Note

Moving an existing field to a different list also triggers a resync — the API can keep returning the field's previous values for up to 24 hours after the move, even though the UI already shows the change. There's no way to force an immediate refresh.

Updating a Checkbox Field

To write or update a Checkbox field using the Add/update contacts API method, pass the numeric field ID in the fields array. Separate multiple values in the value parameter with commas:

{
  "contacts": [
    {
      "channels": [
        {
          "type": "email",
          "value": "[email protected]"
        }
      ],
      "fields": [
        {
          "id": 87166,
          "value": "Chinese,Italian"
        }
      ]
    }
  ],
  "dedupeOn": "email",
  "customFieldsIDs": [
    87166
  ]
}

In customFieldsIDs, specify the IDs of the additional fields to update. This parameter is required when updating an existing contact. Only the fields listed in this array are updated.

Updating Additional Fields via SDK

Use contact field variables without the % characters as keys when updating additional fields through the SDK.

Android example:

val userAttributes = UserAttributes(
    email = user.email,
    fields = listOf(
        UserCustomField(
            key = "TRAININGAPP.GOAL",
            value = "lose weight"
        )
    )
)

val user = User(userAttributes = userAttributes)

Reteno.instance.setUserAttributes(
    externalUserId = "USER_ID",
    user = user
)

iOS example:

let userAttributes = UserAttributes(
    email: user.email,
    fields: [
        UserCustomField(
            key: "TRAININGAPP.GOAL",
            value: "lose weight"
        )
    ]
)

Reteno.updateUserAttributes(
    externalUserId: "USER_ID",
    userAttributes: userAttributes
)

More About the Mobile SDK →