Contact field definitions
The fields (attributes) listed here are created by default for every contact type in Voyado Engage.
Contact standard fields
These contact attributes exist by default when setting up a new Engage tenant and every contact created will have them.
Field name (UI) | DB name | Field type | Description / example value |
Contact type | contactType | String | The contact type for this contact, such as "Member" or "Contact" |
First name | firstName | String | Example: Jane |
Last name | lastName | String | Example: Doe |
Member Number | memberNumber | Sequence | Example: 12345678 |
Social Security Number | socialSecurityNumber | SocialSecurityNumber | Validation requires this to be either a Swedish personal identity number, a Finnish personal identity code or a Swedish samordningsnummer. If only 10 digits are specified it is assumed the contact is less than 100 years old. |
Example: jane@doe.com | |||
Mobile Phone | mobilePhone | PhoneNumber | Example: +4612345678. Country calling code is required (+46) |
Registration store | createdInStore | SingleStorePicker | Example: 1001. Once this is set it can't be updated |
Regular store | store | StorePicker | Example: 1002. If not set then this defaults to the same value as Registration store |
Street Address | street | String | Example: Janes street 12 |
Zip Code | zipCode | String | Example: 123 45 |
City | city | String | Example: Stockholm |
Care Of | careOf | String | |
Country | country | String | Example: Sweden |
Weighted RFM (1-100) | rfm | Number | Calculated and set in Engage |
Recency (1-5) | retail.keyvalue.recency | Integer | Calculated and set in Engage |
Frequency (1-5) | retail.keyvalue.frequency | Integer | Calculated and set in Engage |
Monetary (1-5) | retail.keyvalue.monetary | Integer | Calculated and set in Engage |
Age | age | Integer | Example: 28. Automatically set if socialSecurityNumber or birthDay is populated. |
Birthday | birthDay | BirthDate | Given as YYYY-MM-DD. Example: 1963-02-13 |
Gender | gender | Gender | Engage allows four options: Male, Female, Other, PreferNotToSay (as well as NotSet when no value has been chosen). |
Nps-grade | nps.grade | Integer | Set by Engage |
Nps-date | nps.datetime | DateTime | Set by Engage |
Average Nps-grade | nps.averagegrade | Number | Calculated in Engage |
External ID | externalId | String | Identification key from external systems. Used when Engage isn't the master. |
Country Code | countryCode | CountryCode | Example: SE |
Language | lang | Language | Contact's preferred language from the ISO 639-1 list (en, sv, de, nb). A filtered version of this list can be configured in the Engage back-end so that only the values you want to include are shown. |
More about Birthday
Engage automatically calculates if the current day is the contact's birthday, based on the standard contact attribute Birthday. This is the only way it is done. If birthday or age is added as an extra field, they will be ignored.
The Birthday calculations that activate the trigger are made every morning at a random time between 6:00 and 8:00.
Important
Birthday must have the format YYYY-MM-DD with dashes as shown. Using an incorrect date format when creating a contact will not stop the contact from being created, but it will cause their Birthday to be null.
Contact custom attributes
As well as the standard contact attributes listed above, there is also the option to extend the data model by adding custom contact attributes, based on the client's needs. Custom attributes can be used to store data about contacts in order to create useful segments or to personalize content in send-outs.
Both standard and custom contact attributes use the field types listed in the section below.
Contact field types
Below are the field types supported in Engage and their constraints:
Text - Standard string field
Long text - Extended text field
Number - Decimal field
Checkbox - One checkbox
Checkbox (multiple) - Several checkboxes
Dropdown menu - A dropdown menu
Social security number - The attribute socialSecurityNumber is a default attribute of this type. It is possible to add another social security number field as long as both fields don't set birthday and gender.
Store (current) - The store (current store) field will be automatically added when activating the "Stores" module in "Enable/disable modules". Adding another attribute of this type is not recommended, and if you do then both fields will be mirrored, meaning that changing one will automatically change the other.
Store (created in) - See "Store (current)Company (only with Company-module) - Deprecated
Birth date: This is type BirthDate and always given as DD/MM/YYYY, for example 13/02/1963
Date and time - For other dates and times we use ISO 8601
E-mail - We validate email according to: RFC 5322, adr-spec
Formula (Used in special cases)
Gender - The gender attribute is a default attribute of this type, and it can be calculated by either socialSecurityNumber (default), setting on the socialSecurityNumber attribute.
Integer - Maximum length of this field is 12 digits.
Sequence - Serial number, for instance memberNumber. When manually importing contacts the sequence attribute (memberNumber for instance) needs to be present but empty for Engage to set a sequence number.
List of children - It's possible to add multiple children with their age set by their birth date.
Country (countryCode) - ISO 3166, Alpha-2 (two digits).
Achievement - A date field that can be set in automation flows, currently the only attribute that can be set in automations.
Consent - The consent attribute includes title, linked text and the actual terms text (HTML).
Age (Integer) - Is set by socialSecurityNumber by default.
Caution
When using the type Sequence as a custom attribute, it should never be used as a key since this will impact performance severely.
You will never need to manually create any fields of the following types, since one of each is created by default whenever a contact is created, and duplicates are not allowed:
Store (current)
Store (created in)
Birth date
Gender
Age (integer)
More about standard fields
Mobile Phone (mobilePhone)
Each contact can only have one phone number connected to them, and the number should always be formatted as MSISDN (Mobile Station International Subscriber Directory Number), as a "+" prefix followed by [countrycode][phonenumber]. For example: +46707104603.
Voyado Engage uses libphonenumber. a Google open source library, to validate phone numbers internationally. For a deep dive into the area of phone number validation and all the issues that can occur, you can read this page.
The library libphonenumber works by setting a "default" country code, from which all numbers are validated. A number is considered valid if you, by calling that exact number from a phone in the "default" country, could succeed in placing a call.
However, this can quickly become complex, making it important to follow the standard. Consider these cases:
Case 1: If the default country is SE, the following numbers are valid: 0707104603, +46707104603, 0046707104603. This is because "00" is the international calling code from Sweden.
Case 2: If the default country is US, the same number, 0046707104603, would now not be valid, since "00" is not an international calling prefix in the US.
So, although it will sometimes work, you should never send phone numbers using only the country code (without prefixing "+"). There are many ambiguities where it is impossible to distinguish a country code from a regional code.
For example, 468211415 will be validated as a number with regional code 046 (Lund) instead of a Swedish number (46) if called from regional code 08 (Stockholm). Thereby it will be stored in the database as 46468211415. Similar things can happen with Norwegian numbers that have country code 47, but local numbers may themselves also start with "47".
Important
A phone number should always be made of a "+" prefix followed by [countrycode][phonenumber].
Important
Using "local" phone numbers based on the default country code should only be done when manually entering phone numbers in Engage, i.e. when searching, or using the LoyaltyBar, or on registration forms.
Email (email)
All emails in Engage are validated according to RFC 5322, addr-spec.
Read the details of RFC 5322 here.
Country code (countryCode)
Country codes follow the ISO 3166, alpha-2 naming standard. Some useful examples are:
SE = Sweden
NO = Norway
GB = Great Britain (and Northern Ireland)
NL = Netherlands
IE = Ireland
Language (lang)
Some markets / countries use multiple languages, for example Belgium, where Dutch and French are both used. Here, the countryCode contact attribute isn't enough to identify the end-user's language. In cases like this, the lang (language) standard contact attribute can be used.
The lang contact attribute is of type Language, and follows the ISO 639-1 standard. Examples:
en = English
sv = Swedish
nb = Norwegian (bokmål)
de = German
Since the list of languages is very long and can be troublesome to navigate when manually setting a contact's language, a custom-made shorter version of the list can be configured for your tenant, showing only the languages you intend to use for your contacts. Contact your Voyado team to do this.
Preferences and accept flags
A contact also has several optional preference fields defining how they wish to be contacted, known as accept flags.
Field name (UI) | DB name | Field type | Description & example value |
Accepts Email | acceptsEmail | Bool | True / False |
Accepts Postal | acceptsPostal | Bool | True / False |
Accepts SMS | acceptsSms | Bool | True / False |
Important
If these accept flags are used, they must be set to either true or false, and never to null.