To store user data, add custom fields (a.k.a. "variables" or "vars") to the user profiles of each user. These exist alongside other user data that is collected directly by Sailthru, including users' interactions with your site and emails. You can later access these custom fields through Zephyr template code, Audience Builder queries, the User API, data exports, and the User Profile page.

Setting custom fields allows you to easily personalize communications and segment lists for sends and reporting. You can set these vars through your initial list upload, and then add or update them in a number of ways, including using the API. If you ever need to download your data - any or all of the variables that exist on your users - you can perform an export.

Variable names:

• Are case sensitive. For example, if you create a variable named "Survey_Score" it will not be accessible using all lowercase letters.
• May not start with a number or be only numbers. For example, don't upload phone numbers using var name "#".
• May not contain special characters (such as %, -, ., or $).  These characters will be scrubbed from variable names upon import.
• May not contain spaces. If the variable name is submitted with a space, it will be converted to an underscore.
• May not be one of the Standard variable names or reserved words.

Variable values:

Our best practices dictate that the variable value is not longer than 140 characters.

Variable Types: the system accepts the following variable types. 

Field Type	Example
string	"first_name": "Douglas"
number	"household_size":3
Date (see Date and Time Formats for more information)	"signup_date":"1987-08-01"
boolean	"is_member":true
array	["MSFT", "AMZ", "APPL"]
object

Ways to Set a Variable

There are a few different methods below for setting vars. You can:

• • Upload a new list or update vars on an existing list via CSV upload.
  • Use the User API or Job API.

• Set vars on a user based on URL parameter values in links they click. See Set User Vars or List Membership On-Click with URL Parameters.
• Set vars from a Lifecycle Optimizer Action.
• Set a var by managing user vars directly on the User Profile Page. 
• Use Audience Builder to run a bulk update on profiles.

Regardless of the method used to add or update user variable data, the following parameters should be followed.

Note that you can view variables on individual user profiles once the list has finished by entering an email address in the User Lookup search field in My Sailthru.

Note: If you're adding vars as an array, we recommend that you add fewer than 500 values. If you need to add more than this number, reach out to your CSM.

Date and Time Formats

In order to maintain strict JSON compatibility, vars do not support a native date or time type. Instead, if you use the following naming and formatting conventions, the system will treat these values as dates and times throughout our system, for example, when performing queries in Audience Builder.

Dates

• Value: For dates, such as birthdays, store a string in the date format: YYYY-MM-DD (for example, 2013-12-15). If the year is unknown, set it to 0000 (for example, 0000-12-15). The format must be YYYY-MM-DD or the date will not be added or updated.
• Var name:_date is required at the end of the var name in order for values to be interpreted as dates. (For example, birth_date or first_login_date.)

Times

• Values: For time, such as the moment a user signed up, store in UNIX timestamp format (i.e. the number of seconds since Jan 1, 1970 00:00:00 GMT). For example, 1388087892.
• Var names: _time  or _datetime is required at the end of the var name in order for values to be interpreted as timestamps. (For example, last_discount_time or signup_datetime.)

NOTE: The above naming conventions are required to properly set the data type.

Using Zephyr, you can work with dates and times in templates using the date and time functions.

• date returns the current date -- or the date of any UNIX timestamp you pass it -- in a custom, reader-friendly format (e.g. November 8, 2016).
• time returns the current UNIX timestamp, or that of any date/time you pass it. It accepts a variety of formats of dates and or times, including relative dates and times, e.g. "-3 hours" or "+2 weeks Wednesday 3 PM".

For example, suppose a user's birth_date is stored as 1980-02-14. To render this as a formatted date, use the following syntax: {date('MMMM dd, YYYY', time(birth_date))}

Recommended Variables

Adhering to best practices allows us to tailor your analytics experience. When collecting data for your users at signup, purchase, etc., you can use the following custom vars names and values so we can provide a more customized reporting experience.

Suggested Name	Description	Example Values
name	This refers to the user's full name; the system uses this as the "to:" friendly name when emailing users. Populating it is recommended for optimal delivery rates.	John Doe
first_name	User's first/given/personal name; useful for easily personalizing templates or hosted pages without having to parse the "name" var above	John
last_name	User's last/family/surname	Doe
source	The referral source of the subscription; the sytem uses this to generate the Source Signup Report in My Sailthru. Note that this requires using the var name source in all lowercase letters.	Fall2015campaign Facebook Twitter
postal_address	Physical mailing address, line 1	123 Main Street
postal_address2	Physical mailing address, line 2; useful for apartments, floors and building numbers	Apt 6A
postal_city	Physical mailing address city	New York
postal_state	Physical mailing address state	NY
postal_code	Physical mailing address postal code (ZIP Code in US) Note: When submitted via CSV, numeric postal codes must be submitted in quotes (e.g. "01234") to preserve leading zeroes	10011 10011-1234 K8N 5W6
country	Shorthand code for country of residence as stipulated by ISO 3166-1	US AU FR
locale	Shorthand codes for spoken language and country code, use format [language code],[_country_code]. Click here for a list. Not case-sensitive.	en_US cs_CA en_AU
phone	Full phone number including international country calling code and area code	+12125551234
timezone	Timezone in country/state of residence For a full list of supported time zones, see the "TZ" column within this list, you can also reference this PHP article.	America/New York America/Chicago Canada/Eastern
gender	Gender identification	"m" for male  "f" for female  "o" for other
birth_date	Date of birth in "YYYY-MM-DD" format	1980-12-30 1978-09-16
marital	marital status	single married divorced domestic partner widowed other
income	Occupational income amount or level; wherever possible, enter exact integer value as local currency; if exact amount is not available default to the lowest value in range If you wish to not collect specific income information, use the suggested ranges below and select the lowest value of each level.Range to display to users [var value to pass] Pass "9999" for "Less than $10,000″ Pass "10000" for $10,000 to $14,999 Pass "15000" for $15,000 to $24,999 Pass "25000" for $25,000 to $49,999 Pass "50000" for $50,000 to $99,999 Pass "100000" for $100,000 to $149,999 Pass "150000" for $150,000 to $199,999 Pass "200000" for $200,000 or greater	65000 ($65,000)
education_level	Highest level of education achieved	no diploma high school ged some college associates masters
household_size	Integer value for total household size including user	4
children	Integer value for total children in household/family	3
industry	Occupational categorization; suggested values from United States Department of Labor (suggested to use only top-level "Major groups") See the above link for a complete list, using the aforementioned examples as a style guide. (i.e., lowercase, with commas)	computer and mathematical occupations management occupations legal occupations personal care and service occupations

Note: Each user profile can store up to 1000 variables.

Unsetting a Variable

There are four ways to unset a variable from a user account.

• Unset a var manually from a User Profile using the trash can icon (from the Custom Fields tab in the User Profile).
• Unset vars in bulk from Audience Builder's Bulk Update Profile option. You can find Bulk Update Profile under Other Options.
• Unset a var through a Lifecycle Optimizer Flow's Remove Custom Fields action.
• Unset a var directly through a specific user's User Profile page.