Use the `custom_field` subresource to create and store information specific to each contact beyond the standard contact resource properties.

Custom fields allow users to collect and store any type of information from their contacts. A custom field gives all contacts in a user’s account a category to store custom information. Customers use custom fields to add contact-specific details to an email and when importing a file of contacts. The custom fields can then be used to insert additional personalized content in email campaign. We provide a use case in the next section of this page.

In the API, a custom_field is a contact object subresource used to store a category of data for each contact. A custom_field subresource has three components:

  • a label or name of the custom_field (category name)
  • the type of data in the category (string or date)
  • the contact-specific custom_field value

A user has to first create the custom_field subresource, and then they can apply contact-specific custom field data to contacts in their account.

Example Use Case

Acme Auto Repair wants include customer-specific vehicle information in email campaigns they send out to their lists. The categories of information they need to store are:

  • Vehicle Make
  • Vehicle Model
  • Vehicle Year

The contact resource does not have any properties that can be used to store this information. The solution is to create custom_field subresources to store these categories of information in a contact resource. Acme Auto Repair creates four custom fields to meet their needs:

  • Vehicle1 Make and Model
  • Vehicle1 Year
  • Vehicle2 Make and Model
  • Vehicle2 Year

A large number of customers have more than one vehicle, so Acme Auto Repair created 2 sets of custom fields. The shop can now personalize content in their email campaigns using these custom fields to insert customer-specific vehicle information into their email campaigns.

Learn more about adding custom content to email campaigns here.

Limits

The custom_field subresource has the following limits:

Maximum number of custom fields in a user’s account 100
Maximum number of custom fields per contact 50
Maximum characters in a custom_field name 50

Work Flow for Creating and Applying Custom Fields

Here is a basic work flow to follow when creating and managing custom fields, and then applying them to contact resources.

Determine the information categories you need to store for contacts that are not already part of the contact resource.

Step 1 GET all existing custom_fields to verify whether any of the proposed `custom_field` categories already exist. If you need additional custom fields, proceed to Step 2.
Step 2 Create a new custom_field for each information category.
Step 3 Include custom_field data when adding new contacts.
Step 4 Update existing contacts with custom_field data.


Tags: custom_fields contacts code_samples