Contact Attributes

Used for:

•  Message Content
•  Building Audiences
•  Triggering Messages
•  Analytics

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 the system for creating personalized message content, building audiences for segmentation, triggering automated messages and viewing reports and analytics.

How Contact Attributes Are Stored

Below is a simple example of how contact attributes are stored in Cordial as a JSON object. 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 channels 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

About 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
• Timezone
• Latitude and longitude

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
• Timezone
• Latitude and longitude

To set auto locate by IP address navigate to Data › Contact Attributes, hover over the arrow on the desired geo attribute and choose auto locate by IP address.

The icon will be added next to the attribute to designate the setting.

Set as primary time zone

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

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

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 contact's time zone across all messaging channels.

Adding 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 first.

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

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

• Via the UI
• Via CSV upload
• Via API

Adding attributes via the UI

1. Log into the Cordial platform and navigate to Data › Contact Attributes
   
   
   
2. Click the button labeled "New" 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.
     Note: When creating attribute keys, refrain from using math operators in place of spaces (-, +, *, etc) as they can cause errors with Smarty variables in message creation. We recommend using either camel case (firstName) or 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 (Max 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. Note that 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.

Adding 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 would like to add to the system.
   
   
2. Log into the Cordial platform and navigate to Data › Import Contacts
   
   
3. Choose the appropriate options
   • Import Source - Choose whether the source is a local or hosted file.
   • Header Row - Select this option if your data file contains a header row.  It is recommended to have a header row to make it easier to identify and map preexisting attribute names.
   • Choose Delimiter
4. Select and upload your CSV.
5. You'll then have the option to "Add Attribute" for each header row column you have created.
   
   
   Note: 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".

Adding attributes via API

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

Using Contact Attributes in a Message

Contact attributes values can be used to personalize message 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. Note that the contact attribute "first" is prepended with the word "contact" because all contact attributes are stored in the contact collection.

Using Smarty, you are able to not only display contact attributes, but also construct conditional statements that can render message content dynamically based on contact attribute values.

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

• Smarty contact variables
• Conditional "if" statements

{$utils->jsonPrettyPrint($contact)}

Building Audiences Using Attributes

Using the audience builder, you can search and segment contacts based on the 4 types of contact attributes, string, number, date, geo and array.

You are able to build complex segmentation queries by combining, including and excluding audience rules and sets of audience rules with and/or operators.

In the audience builder image below, note the highlighted rules associated with contact attributes:

Learn more about the audience builder

Triggering Messages Using Attributes

With message automations you are able to trigger message sends based on the change of 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 (i.e. silver to gold).

To trigger an automated message based on a change to a contact attribute, use the Event Triggered sending method, and choose the Trigger Event: "When a change is made to a contact attribute value".

Learn more about automated messages

Building 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

Using audience trend reports, you can view the population over time of an audience based on contact attributes.

For example, you could compare audiences of contacts based to their Member Level by creating 3 audiences (silver, gold, platinum), enabling audience trend analytics on each one, and viewing them on the audience trends chart.

Filtering 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.

For example, you can create a chart that plots message activity over time filtered by a saved audience rule where the contact attribute for member level is Gold.

Filtering event data reports

Event data reports allow you to view reports of event activity. You are able to filter reports using audience rules similar to the event dashboard charts. For example you can filter by a saved audience rule where the contact attribute for member level is Gold.

Customize Attribute Access

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

To configure, edit an existing attribute or create a new attribute and click the option for Advanced Customize Attribute Access.

Publicly editable

Selecting this option will allow unauthenticated modifications to the attribute. If you are using JavaScript listeners to automatically update the attribute, you will need to select this option. Please note that this option comes with compliance concerns as it makes it possible for malicious users to change the value.

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.

Mixing "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.
  • Note that 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 learn about lists.