Set Custom Fields (Variables) on Users

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 TypeExample
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:

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.

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

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

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.