Skip to main content

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.

E-mail

email

Email

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

As ISO 3166-1 alpha-2

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.

Read a general explanation of email standards 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.