Overview

Contact attributes contain information specific to each contact and are stored in the contact collection as strings, numbers, dates, geo fields (addresses), and arrays. They are used throughout Cordial to:

• Create personalized message content 
• Build audiences for segmentation 
• Trigger automated messages
• View reports and analytics

How Cordial stores contact attributes

Below is a simple example of how contact attributes are stored in Cordial as JSON objects. (Some data has been omitted for display purposes.)

{
    "channels": {
      "email": {
        "address": "fredgarvin@example.com",
        "subscribeStatus": "subscribed",
        "unsubscribedAt": ""
      }
    },
    "first_name": "Fred",
    "last_name": "Garvin",
    "customer_number": "3728",
    "birthday": "1980-05-22T07:00:00+0000",
    "home_address": {
      "street_address": "555 Truss Ave",
      "postal_code": "92108",
      "country": "United States of America",
      "state": "CA",
      "city": "San Diego",
      "tz": "America/Los_Angeles",
      "loc": {
        "lat": "32.7773",
        "lon": "-117.1008"
      },
      "countryISO": "US",
      "auto": false
    },
    "favorite_fruits": [
    "apple",
    "peach",
    "pear"
  ]
  }

Notice in the above example:

• The channel's object contains the email address and is the primary key for the contact.
• The attribute keys that were created for the contact:
  • first_name: string value
  • last_name: string value
  • customer_number: number value
  • birthday: date value
  • home_address: geo object with a reserved set of field names
  • favorite_fruits: array of values

Geo attributes

Geo attributes store information about a contact's address. Multiple geo attributes can be created to represent multiple addresses (billing address, shipping address, etc.). Geo attributes contain the following reserved set of field names that cannot be edited:

• street_address
• street_address2
• city
• state
• postal_code
• country
• tz (time zone)
• loc
  • lat (latitude)
  • lon (longitude)

When a zip code is added, the following fields will be automatically added by the system:

• City
• State
• Country
• Time zone
• Latitude and longitude

Automatically populating geo attributes based on zip code is currently limited to U.S. zip codes only. Foreign zip codes may not populate geo attributes accurately.

You can provide your own values for the above fields and override automatic assignment based on the zip code. A value for the Country field must be provided in order for the override to occur.

Auto locate by IP address

When Auto Locate by IP Address is set for a geo attribute, the following geo attribute data will be auto-populated based on the IP of the most recently observed behavior (opens, clicks, or any custom events).

• City
• State
• Zip code
• Country
• Time zone
• Latitude and longitude

Some email inbox providers (such as Gmail) may not pass the appropriate IP address for accurate auto location. This is generally due to the provider caching and opening emails on proxy servers.

Auto-populated data will overwrite any existing data for this attribute. To store location-based data explicitly provided by the contact (such as shipping or billing addresses), consider using a geo attribute that is not set to auto-locate.

To set Auto Locate by IP, navigate to Data > Contact Attributes, hover over the arrow on the desired geo attribute, and choose Auto Locate by IP. The icon will be added next to the attribute to designate the setting.

Geo attribute data will only be auto populated on live message sends. Data will not be populated when a message is sent as a test message.

Set as primary time zone

A string or geo location attribute can be set as a contact's primary time zone for scheduled sending.

The time zone must adhere to the "Area/Location" format (e.g. "America/New_York"). View the full list of recognized time zone identifiers here.

To set an attribute as the primary time zone, navigate to Data > Contact Attributes, hover over the arrow on the desired attribute, and choose Set As Primary Time Zone. The icon will be added next to the attribute as the primary time zone designation.

Once the primary time zone attribute is set, you will have the option to send based on the contact's time zone across all messaging channels.

If sending according to contact's time zone is not enabled, your message will be sent based on your Cordial account default time zone.

Add contact attributes

Before contacts and their associated attribute data can be added to the Cordial system, each attribute's name and key must be added.

The contact email address is a reserved attribute key and does not need to be added to the system like other attribute keys. Its key is referenced as channels.email.address.

Contact attribute keys can be added to the Cordial platform three different ways:

• Via the UI
• Via CSV upload
• Via API

Tip

If you have a large amount of attributes, we recommend that you create them in the UI prior to uploading contacts. This creates a better user experience.

Add attributes via the UI

1. Log into the Cordial platform and navigate to Data > Contact Attributes

2. Select the New button to create a new contact attribute.

3. Fill out the form to add the contact attribute to the system.

• • • Attribute name: Use this "friendly name" to reference the attribute within the application when searching and building audiences.
    • Attribute key: This is the Attribute's ID and is referenced when personalizing content in messages and making API calls.

      Attribute keys and names are limited to 60 characters.

      When creating attribute keys, refrain from using math operators in place of spaces (-, +, *, etc.) because they can cause errors with Smarty variables in message creation. We recommend using either camel case (firstName) or snake case/underscores (first_name).

    • Attribute type: Choose the data type of the attribute.
      • String: Any combination of characters
      • Number: Only numeric values
      • Date: Only date values (Examples: 01/30/2000, 2000-01-30, or 2000-01-30T00:00:00Z)
      • Array: A comma-separated list of values (the maximum number of items is 25)
      • Geo: Contains the following reserved system fields:
        • street_address
        • street_address2
        • city
        • state
        • postal_code
        • country
        • tz (time zone)
        • loc
          • lat (latitude)
          • lon (longitude)
      • Advanced: Customize Attribute Access: Provides additional control over how attributes are treated with contact deletions, as well how they are updated using JavaScript listeners. This functionality is for advanced usage only. Please contact your Client Success Manager before making changes. Learn more about customizing attribute access below.

Depending on the type of attribute selected, there may be additional information required:

• Searchable: Checking this box will allow the attribute to be searchable within the system and available to build audience rules.
• Required: Checking this box will make the attribute value required when importing or editing contact records. Only select Required if you never want to have a contact without this value. When importing, contact records that do not have this value will be rejected.

Add attributes via CSV upload

Contact attributes can also be added to the system when importing contact records.

1. Prepare a CSV file where the header row contains the names of the attribute keys you want to add to the system.

2. Follow the steps described in this article to import contacts via data job.

3. While configuring the Data Mapping for your import file, click the plus icon to add a column. 

3. In the Select column type dropdown, choose Populate an attribute and then select Create new attribute from the second dropdown.

4. Complete the fields for Attribute name, Attribute key, and Attribute type and click Save.

Preexisting attributes and lists with the same name will already be mapped. If you need to map to a preexisting attribute with a different name, use the dropdown labeled "choose."

Add attributes via API

For information about creating contact attributes via the API, visit this article about Account Contact Attributes.

Use contact attributes in a message

Contact attributes can be used to personalize messages using Smarty contact variables. For example, you could display a contact's first name using the following Smarty code:

{$contact.first}

The above code assumes that the contact attribute "first" is in the system. The contact attribute "first" is prepended with the word "contact" because all contact attributes are stored in the contact collection.

Using Smarty, you can display contact attributes and also construct conditional statements that render message content dynamically based on contact attribute values.

For guidance on using contact attributes to personalize message content using Smarty, see the following articles:

• Smarty Contact Variables
• Conditional "if" Statements

During message creation, it is useful to use the following Smarty utility to view the contact record in JSON format:

{$utils->jsonPrettyPrint($contact)}

By pasting the above code into the HTML editor and clicking the Preview button, you can view the specified contact's record with all attributes, list association, and cart items (if available).

Build audiences using attributes

Using Cordial's Audience Builder, you can search and segment contacts based on the five types of contact attributes: array, date, geo, number, string. You can build complex segmentation queries by combining, including, and excluding audience rules and sets of audience rules with and/or operators.

1. Navigate to Contacts > Audiences.

2. Select Attributes from the Rules dropdown on the right side of the Audience Builder.

3. Drag the contact attributes you want to use into your audience.

In the Audience Builder image below, note the rules associated with contact attributes.

You can learn more about Cordial's Audience Builder here.

Trigger messages using attributes

With message automations, you can trigger message sends based on changes to a contact attribute. For example, if you have a contact attribute called Member Level, you could trigger a message when the value for Member Level changes.

1. To trigger an automated message based on a change to a contact attribute, select or create a message automation: Cordial Dashboard > Message Automation. 

2. In the Message creation dashboard, navigate to Sending Methods > Event Triggered in the left sidebar.

3. From the Trigger Events pane, choose the trigger event, "When a change is made to a contact attribute value."

You can learn more about automated messages here.

Build reports using attributes

Audiences based on contact attributes can be saved as audience rules and either visualized over time with audience trend reports, or used as filters for event data dashboards and event data reports.

Audience Trend reports

To access audience trend reports, log into Cordial and navigate to Analytics > Audience Trends. From here, you can view the population of an audience over time based on contact attributes.

As an example, you could compare audiences of contacts based on their member level by creating three audiences (in the example below: Silver, Gold, and Platinum), enabling audience trend analytics on each one, and viewing them on the Audience Trends chart.

Filter event dashboards

Event dashboards provide a way to visualize event activity over time by creating customizable charts. You can take advantage of contact attributes in event dashboard charts using audience filters.

To edit an event chart (also called time series chart), navigate to Analytics > Event Dashboards and select Chart Settings in the upper right corner of the chart.

Use case: You could create a chart that plots message activity over time filtered by a saved audience rule where the contact attribute for member level is Gold_Status_100_SD.

Filter event data reports

Event Data Reports—navigation: Analytics > Event Data Reports—allow you to view reports of event activity. You can filter reports using audience rules similar to the event dashboard charts.

You could filter by a saved audience rule where the contact attribute for member level is Gold_Status_100_SD.

Customize attribute access

To provide additional control for privacy compliance (i.e. GDPR), you can customize how attributes are accessed and deleted.

This functionality is for advanced usage only. Please contact your Client Success Manager before making any changes.

1. To configure, navigate to Data > Contact Attributes and edit an existing attribute or create a new attribute. 

2. From the Edit a Contact Attribute pane, select the option for Advanced: Customize Attribute Access.

Publicly editable

Selecting this option allows unauthenticated modifications to the attribute. If you are using JavaScript listeners to automatically update the attribute, you need to select this option.

This option comes with compliance concerns because it makes it possible for malicious users to change attribute values.

This feature requires explicit consent for proper functionality. Please contact your Client Success Manager or submit a support request before making any changes.

Retain data on delete

This functionality gives you the ability to control how attribute data is treated when a contact is deleted from the system.

• Destroy: This is the default option. All contact attribute data is deleted.
• Anonymize: Replaces attribute data with a random value. Please contact your Client Success Manager before choosing this option.
• Retain the data as is: This option keeps the attribute data. There are possible security concerns with this option. Please contact your Client Success Manager before choosing this option.

Mix retain data on delete options across multiple attributes

If you choose to mix the options for retaining data across multiple attributes and then delete the contact, the following will occur:

• The channels.email.address value will be anonymized.
• Any attributes set to Destroy will be permanently deleted.
• Any attributes set to Anonymize will be given a random value.

  The same random value will be given to anonymized attributes with identical anonymized attribute values. For example, if a contact has a value of "blue" for the anonymized attribute of eye_color, it could be given a random value of "abcdefkkl" upon deletion. If multiple contacts are deleted with the anonymized eye_color attribute value of "blue," then they would also be given the same random value of "abcdefkkl."

• Any attributes set to Retain data as is will retain their values.
• The anonymized contact record with the above changes will be retained in the database.

In the next article, you can learn about lists.