This guide will show you how to use the API to create Custom Fields on your Contacts, and populate those fields with data.

2228 — Example Custom Field on a Contact

Custom fields are a vital tool for adding data to your contacts. Creating the Custom Fields, assigning those fields to subscribers, and populating those fields with options and data is easily done through the API.

Glossary of Terms

Field

Fields are places for storing various types of data on Contact Record.
Custom Fields are Fields created by an organization to store unique data points that fall beyond the scope of the standard Fields already provided on a Contact record, ie: first name, last name, email, etc

Field Type

Field Types are the different types of data a Field can store, and must be set on Field creation. These types include text area, text, date, dropdown, multiselect, radio, checkbox, hidden, and datetime.

Field Option

Field Options are the available options provided for certain Field Types. Example: A dropdown Field needs to be populated with a list of options, but a text field would not need Field Options, as it is empty field for entering any type of text.

Field Value

Field Values are the actual data points stored inside the Custom Fields. Example: A Custom text Field on a Contact called "Team" could have the Field Value "Blue", or a dropdown Custom Field called "Team Selection" has the options: "Blue", "Red", "Green". If "Blue" is selected, "Blue" the Field Value for that Custom Field is "Blue".

Field Relationship

Field Relationships are the relationship between a Contact List, and a Custom Field. Example: An organization has a Contact List called "Employees" and another list named "Customers." A Custom Field called "Department" could be placed on all Contacts in the "Employees" list, and another Custom Field called "Uses Coupons" could be placed on all Contacts in the "Customers" list, these are Field Relationships to Contact Lists.

Creating Your First Custom Field

There are several different available types of Custom Fields, but we will be creating a "listbox" type for this example. Creating a Custom Field can be accomplished in three steps.

STEP 1: Create the Custom Field

Create a Custom Field by making a `POST` to `https://{{yourAccountName}}.api-us1.com/api/3/fields`.

In addition to type, there are several other options you can change inside the JSON body to manipulate the formatting, visibility, and description for the field:

{
    "field": {
        "title": "Example List Box",
        "descript": "Field description goes here",
        "type": "listbox",
        "perstag": "listBoxTagName",
        "group": 1,
        "show_in_list": true,
        "rows": 0,
        "cols": 0,
        "visible": true,
        "ordernum": 0
    }
}

The type key is what defines the type of Custom Field being created. There are multiple options, including:

358 — "listbox" - A list of options, similar to `dropdown` , enabling a single selection

770 — "radio" - A list of radio buttons/options, enable a single selection

656 — "checkbox" - A list of selectable checkboxes, enabling multiple selection

You should receive a response from your API call of 201 - CREATED upon completion. The response will contain the randomly-generated id of the Custom Field, as well as other metadata :

{
    "field": {
        "title": "Example List Box",
        "descript": "Description goes here",
        "type": "listbox",
        "perstag": "LISTBOXTAGNAME",
        "show_in_list": 1,
        "rows": 0,
        "cols": 0,
        "visible": 1,
        "ordernum": 1,
        "created_by": "1",
        "updated_by": "1",
        "cdate": "2022-06-15T15:04:11-05:00",
        "udate": "2022-06-15T15:04:11-05:00",
        "links": {
            "options": "https://yourAccountName.api-us1.com/api/3/fields/34/options",
            "relations": "https://yourAccountname.api-us1.com/api/3/fields/34/relations"
        },
        "id": "34"
    }
}

Note that for this guide, the automatically assigned id for this custom field is 34.

Your listbox should now be created, and it's existence can be verified with a GET call to
https://{{yourAccountName}}.api-us1.com/api/3/fields:

{
    "fieldOptions": [],
    "fieldRels": [],
    "fields": [
        {
            "title": "Example List Box",
            "descript": "Description goes here",
            "type": "listbox",
            "perstag": "LISTBOXTAGNAME",
            "defval": null,
            "show_in_list": "1",
            "rows": "0",
            "cols": "0",
            "visible": "1",
            "service": "",
            "ordernum": "1",
            "cdate": "2022-06-15T15:04:11-05:00",
            "udate": "2022-06-15T15:04:11-05:00",
            "created_timestamp": "2022-06-15 15:04:11",
            "updated_timestamp": "2022-06-15 15:04:11",
            "created_by": "1",
            "updated_by": "1",
            "options": [],
            "relations": [],
            "links": {
                "options": "https://yourAccountName.api-us1.com/api/3/fields/34/options",
                "relations": "https://yourAccountName.api-us1.com/api/3/fields/34/relations"
            },
            "id": "34"
        }
    ],
    "meta": {
        "total": "1",
        "selected": null
    }
}

Note that fieldOptions and fieldRels are empty lists. That is because we have not populated this field with options (step 2) or assigned this Field to a list (step 3).

STEP 2: Populate the Custom Field with Options

Populate the Custom Field created in Step 1 with a call to https://{{yourAccountName}}.api-us1.com/api/3/fieldOption/bulk, with a JSON body containing the options you want contained in this Custom Field:

{ 
     "fieldOptions": [
        {
            "orderid": 1,
            "value": "Option A",
            "label": "Option A",
            "isdefault": false,
            "field": "34"
        },
        {
            "orderid": 2,
            "value": "Option B",
            "label": "Option B",
            "isdefault": false,
            "field": "34"
        },
        {
            "orderid": 3,
            "value": "Option C",
            "label": "Option C",
            "isdefault": false,
            "field": "34"
        }
    ]
}

In this JSON body:

orderid: Edits the order these options will be displayed in
value: The value of the option
label: The label displayed in the UI for the option
isdefault: If the option should be pre-selected/default
field: The custom field these options should appear inside

You should receive a 201 - CREATED response to a successful call:

{
    "fieldOptions": [
        {
            "orderid": 1,
            "value": "Option A",
            "label": "Option A",
            "isdefault": 0,
            "field": "34",
            "cdate": "2022-06-15T15:17:14-05:00",
            "udate": "2022-06-15T15:17:14-05:00",
            "links": {
                "field": "https://yourAccountName.api-us1.com/api/3/fieldOptions/58/field"
            },
            "id": "58"
        },
        {
            "orderid": 2,
            "value": "Option B",
            "label": "Option B",
            "isdefault": 0,
            "field": "34",
            "cdate": "2022-06-15T15:17:14-05:00",
            "udate": "2022-06-15T15:17:14-05:00",
            "links": {
                "field": "https://yourAccountName.api-us1.com/api/3/fieldOptions/59/field"
            },
            "id": "59"
        },
        {
            "orderid": 3,
            "value": "Option C",
            "label": "Option C",
            "isdefault": 0,
            "field": "34",
            "cdate": "2022-06-15T15:17:14-05:00",
            "udate": "2022-06-15T15:17:14-05:00",
            "links": {
                "field": "https://yourAccountName.api-us1.com/api/3/fieldOptions/60/field"
            },
            "id": "60"
        }
    ]
}

STEP 3: Assign the Custom Field to a List

Step 1 created the field, and step 2 assigned it options, but the field isn't being displayed on any Contacts inside the ActiveCampaign user interface. That is because we need to assign this Custom Field to the contacts in a List. This connection between a List and a Custom Field is called a "field relationship."

You can get the id of the list you want to assign this Custom Field to with a GET call to https://{{yourAccountName}}.api-us1.com/api/3/lists. This call will return the Contact Lists for this account. An id is assigned to each list. For this tutorial, we will be using the id of 1

Using this Contact List id, assign the Custom Field to the list by making a POST call to https://{{yourAccountName}}.api-us1.com/api/3/fieldRels:

{
    "fieldRel": {
        "relid": 1,
        "field": "34"
    }
}

In this JSON body:

relid: The id of the Contact List you want to assign the Custom Field to
field: The id of the Custom Field created in Step 1

A 201 - Created response should return a relid when successful. This relid will be used to remove a custom field from a Contact List.

889 — The custom field should now be available on every contact subscribed to the List you assigned the Field Relationship.

Populating Custom Field Values on a Contact

To populate a Custom Field for an individual Contact, make a POST call to https://{{yourAccountName}}.api-us1.com/api/3/fieldValues

{
    "fieldValue": {
        "contact": 19,
        "field": 34,
        "value": "||Option A||Option C||"
    }
}

In this JSON body:

contact: The id of the contact
field: The id of the custom field
label: The label displayed in the UI for the option
value: The value to be entered into that custom field

In Step 1 we created a Custom Field with the type of listbox, which supports multiple selections. Therefore, value of ||Option A||Option C|| is valid data because the || divides the selections we want chosen for this Contact.

836 — This Contact's Custom Field has successfully been populated with the data sent via the API.

📘
Values not showing up? Check the following:

The Value being sent must match the type of data the field was built to accept (see step 1).

The Value being sent must match exactly to the Options provided (see step 2).

The Contact must be subscribed to the List the Custom Field has a Relationship to (see step 3).

Custom fields are a vital tool for adding data to your contacts. Creating the Custom Fields, assigning those fields to subscribers, and populating those fields with options and data is easily done through the API.

Glossary of Terms

Field

Field Type

Field Option

Field Value

Field Relationship

Creating Your First Custom Field

STEP 1: Create the Custom Field

Create a Custom Field by making a `POST` to `https://{{yourAccountName}}.api-us1.com/api/3/fields`.

STEP 2: Populate the Custom Field with Options

STEP 3: Assign the Custom Field to a List

Populating Custom Field Values on a Contact

Values not showing up? Check the following:

Additional Resources

Custom Field Documentation

Custom Field Values Documentation

Custom fields are a vital tool for adding data to your contacts. Creating the Custom Fields, assigning those fields to subscribers, and populating those fields with options and data is easily done through the API.

Glossary of Terms

Field

Field Type

Field Option

Field Value

Field Relationship

Creating Your First Custom Field

STEP 1: Create the Custom Field

Create a Custom Field by making a POST to https://{{yourAccountName}}.api-us1.com/api/3/fields.

STEP 2: Populate the Custom Field with Options

STEP 3: Assign the Custom Field to a List

Populating Custom Field Values on a Contact

Values not showing up? Check the following:

Additional Resources

Custom Field Documentation

Custom Field Values Documentation

Create a Custom Field by making a `POST` to `https://{{yourAccountName}}.api-us1.com/api/3/fields`.