Before you start

Things you need to know:

We recommend that the filename contains person, for example, person_import.tsv.
Supported file formats are TSV and CSV.
We recommend that data should be encoded as utf-8, however ucs-2 can also be used. If all the characters in your data can be represented in the first 127 characters, then you can use US-ASCII (sometimes called ANSI).

Import person data from a secure FTP server

The secure FTP server can be provided by you, or can be arranged for you by us.

Sample file

eid           email
5779280784    jonnyappleseed853@gmail.com
8979280787    janedoe51985@outlook.com

This file would allow Fresh Relevance to identify visitors when they click through with, for example, eid=8979280787 on the link URL.

Configure the FTP retrieval

Before you start

Only SFTP and FTPes protocols are supported to protect your data and ensure privacy. Regular FTP is not supported.
All files in the FTP directory which match the allowed files pattern are retrieved, processed and deleted from the FTP server. Therefore, the FTP account used requires read, write, and delete permissions.

Expand the User menu and go to Settings > Imports.
Select Person Import Channels.
Expand the Set up a new channel drop-down menu and select the import type you want to create, in this case FTP.
Select CREATE IMPORT CHANNEL.
Enter the details for:
- Channel name
  To identify the specific import job.
- FTP Type
- FTP Host
- FTP Port
- FTP User Name
- FTP Password
- FTP Access Interval
- FTP Directory
- FTP Allowed Files Pattern
- FTP Field Mapping
- Polling Interval
Optionally, select the Is Service Paused? checkbox to stop the processing of this import job. Clear the checkbox to restart it.
To receive an alert if the import job encounters an error, enter an email address in the Error Alert Email field.
Separate multiple email addresses with a comma. Leave blank to receive no notifications.
Optionally, clear the Keep Most Recently Imported File checkbox to prevent a copy of the file from being stored on the FTP server after import.
Select SAVE.

Import mobile numbers for SMS

Importing mobile numbers is very similar.

For example, you could use a file like this:

eid           mobile
5779280784    +12342342342
8979280787    +441231231231

The import mapping for this file would be:

{
"mobile":{"ftp_field_name":"mobile"},
"eid":{"ftp_field_name":"eid"},
}

All mobile numbers must either be either:

in E.164 format with a leading +, then the country code, then the actual number
or
a local style number, accompanied by a country code. The country code must be a 2 letter upper case ISO 3166-1 Alpha-2 country code (for example GB, FR, US, AU).

Sample file

eid           mobile        mobile_code
5779280784    2342342342    US
8979280787    01231231231   GB

The import mapping for this file would be:

{
"mobile":{"ftp_field_name":"mobile"},
"mobile_code":{"ftp_field_name":"mobile_code"},
"eid":{"ftp_field_name":"eid"},
}

If you’re uploading data which has both email and mobile numbers, just include both in the file and adjust the import mapping to match.

Import permissions

Email permissions

You can also use the system to import permissions from your other marketing systems. Email permission is stored in the field person.perm.

For example, to import a file including email permission:

{
  "email": {
    "ftp_field_name": "email"
  },
  "eid": {
    "ftp_field_name": "eid"
  },
  "perm": {
    "ftp_field_name": "email permission"
  }
}

Permission values of 0 or 1, false or true, no or yes are allowed in the file to be imported, which might look something like:

email                     email permission
test.test@example.com     1
testno.test@example.com   no
testyes.test@example.com  true

SMS and other mediums

SMS and other mediums are similar but slightly different because the permission is stored in the field person.mediums.sms.perm.

For example, to import SMS data and permission, you would use this mapping:

{
"mobile":{"ftp_field_name":"mobile"},
"eid":{"ftp_field_name":"eid"},
"person.mediums.sms.perm": {"ftp_field_name": "sms_perm"},
}

Permission values of 0 or 1, false or true, no or yes are allowed in the file to be imported, which might look something like:

email                     sms_perm
test.test@example.com     1
testno.test@example.com   no
testyes.test@example.com  true

GDPR do not process permission

There is also the permission flag do_not_process that indicates whether the person has stated that they do not permit their personal information to be processed in any way.

This is required for European GDPR regulations.

When enabled, the system is not able to be send any emails to this visitor and their data is not be used to personalize content.

An example field mapping for importing this flag might be:

{
  "email": {
    "ftp_field_name": "email"
  },
  "person.do_not_process": {
    "ftp_field_name": "do_not_process"
  }
}

Which would make the resulting tab-separated (tsv) file look like this:

email                        do_not_process
test.true@example.com        true
test.false@example.com       false
test.null@example.com        null
test.unchanged@example.com   ""

There are 2 valid values for the do_not_process field:

Field value	Explanation
true	This user’s data should not be processed and can not be used for sending emails or content personalization.
false	This user's data can be processed.
""	If the field is empty or otherwise invalid, then the existing value in the `do_not_process` field is not changed for that person.

Import customer ID

A Customer ID (cid) is the ID used within your ecommerce system to identify shoppers. This is most useful when your user's accounts are not identified by email. The Customer IDs can be imported along with the shoppers email address to improve your identification rate. Visitors can be identified by cid in your site's query collection fields, purchase complete images, and content server requests.

To import a Customer ID set the field mapping to write some data into the cid field.

For example:

{
  "email": {
    "ftp_field_name": "email"
  },
  "cid": {
    "ftp_field_name": "customer_id"
  }
}

An example CSV file for this field mapping might look something like this:

email,customer_id
test1@example.com,1000001
test2@example.com,1000002
test3@example.com,1000001

Import additional person data

It is also possible to import an extended set of person data into the system. You can import any fields you want into person.extend along with the following top-level person fields:

person.n (full name)
person.fn (first name)
person.ln (last name)

For example, you could import something that you know about the individual to person.extend.favorite_color:

email                             firstname    lastname    favorite_color
test.test@triggeredmessaging.com  Joe          Bloggs      orange

To make this import correctly, you would use a channel with a field mapping like this:

{
  "email": {
    "ftp_field_name": "email"
  },
  "person.fn": {
    "ftp_field_name": "firstname"
  },
  "person.ln": {
    "ftp_field_name": "lastname"
  },
  "person.extend.favorite_color": {
    "ftp_field_name": "favorite_color"
  }
}

As a more sophisticated import example, you can also import JSON structures, for example:

A list of values within a field

email                               my_field
test.test@triggeredmessaging.com    ["cars","bikes"]

A dictionary of fields and values within a field

email                               my_field
test.test@triggeredmessaging.com    {"cars":"two","bikes":"three"}

To make this import correctly, you would need to use a channel with a field mapping like this:

{
  "email": {
    "ftp_field_name": "email"
  },
  "person.extend.my_field": {
    "ftp_field_name": "my_field",
    "field_type": "json"
  }
}

Customer groups for multiple price books

Requires the B2B module.

A customer group is a code which defines which set of prices are seen by each person.

Several prices are imported for the products, for example:

Base price:£26.99
- groupA: £23.99
- groupB: £24.99
- groupC: £25.99

These prices are imported into the product, and a corresponding code is imported to the field person.cg, to tell the system that that person should see the price for their customer group.

For example:

email                  firstname  lastname  favorite_color  customer_group
test.test@example.com  Joe          Bloggs      orange            VIP

To make this import correctly, you would use a channel with a field mapping like this:

{
    "email":{"ftp_field_name":"email"},
    "person.fn":{"ftp_field_name":"firstname"},
    "person.ln":{"ftp_field_name":"lastname"},
    "person.extend.favorite_color":{"ftp_field_name":"favorite_color"}
    "person.cg":{"ftp_field_name":"customer_group"}
}

Learn more about importing prices into the product database in Import multiple price lists.

Assign a SmartBlock to imported people records for use in personalization

To use the Show Assigned SmartBlock rule in Slots, you must upload data SmartBlock IDs formatted like this:

EmailAddress             test-slot-1    test-slot-2
test.test@example.com    xlkjl3         oiuklj3

To make this import correctly, you would need to use a channel with a field mapping like this:

{
  "email": {
    "ftp_field_name": "EmailAddress"
  },
  "person.content.keys.test-slot-1": {
    "ftp_field_name": "test-slot-1"
  },
  "person.content.keys.test-slot-2": {
    "ftp_field_name": "test-slot-2"
  }
}

Import a fixed value for every person

Fixed values can be imported using the val attribute in the field mapping.

Here’s an example of a field mapping which sets every imported person to have ex.imported set to yes:

{
  "email": {
    "ftp_field_name": "EmailAddress"
  },
  "person.extend.imported": {
    "val": "yes"
  }
}

Import location data

It’s also possible to upload a visitor’s location for use by location based Slot rules. You might want to do this to provide more accurate locations for your known customers.

Location upload requires either:

The postal / zip code and the country code.
The country code must be a 2 letter upper case ISO 3166-1 Alpha-2 country code (e.g. GB, FR, US, AU).
The visitor's latitude and longitude.

Example CSV file

EmailAddress,Country,Postcode
test_uk@example.com,GB,SW1A 1AA
test_us@example.com,US,20500

To make this import correctly, you need to set the channel's import field mapping to:

{
  "email": {
    "ftp_field_name": "EmailAddress"
  },
  "location": {
    "location_type": "postcode",
    "country_code_field_name": "Country",
    "postcode_field_name": "Postcode"
  }
}

Example CSV file that would import the location for 2 shoppers using latitude and longitude

EmailAddress,latitude,longitude
test_uk@example.com,-1.4304542541503906,50.962339396267446
test_us@example.com,-0.07894277572631836,51.50027116593512

To make this import correctly, you need to set the channel's import field mapping to:

{
  "email": {
    "ftp_field_name": "EmailAddress"
  },
  "location": {
    "location_type": "latlng",
    "latitude_field_name": "latitude",
    "longitude_field_name": "longitude"
  }
}

By default, the imported location data is used by Slot rules for 1000 days. If you want to use the IP based geolocation, when available, in the Slot rules or change how long the imported location can be used, this can be done under Location Settings.

Learn more in Use Geotargeting.

Import location data from your location sets

Location IDs, for example, a store, region or airport, from within a location set can be associated with a visitor based on an import. The nearest location within the set is picked, up to a configurable max distance, or based on a defined region around the location. This could be useful to pick, for example, the nearest store to each shopper, unless they are more than 20km away from a store.

Locations IDs can be resolved based on:

The postal / zip code and the country code. The country code must be a 2 letter upper case ISO 3166-1 Alpha-2 country code (e.g. GB, FR, US, AU).
The shopper's latitude and longitude.
Supplying the location you want to add from a location set. This allows you to import a fixed location ID for customers, for example, if you know which their preferred store is - even if it not the geographically nearest location.

Example CSV file

EmailAddress,Country,Postcode,local_store_country,local_store_postcode
test_uk@example.com,GB,SW1A 1AA,GB,SE1 3JB

To make this import correctly, you need to set the channel's import field mapping to:

{
  "email": {
    "ftp_field_name": "EmailAddress"
  },
  "location_ids": {
    "location_type": "postcode",
    "country_code_field_name": "local_store_country",
    "postcode_field_name": "local_store_postcode",
    "location_sets": "template:uk-cities|mystores",
    "list_separator": "|",
    "max_distance": 10000
  },
  "location": {
    "location_type": "postcode",
    "country_code_field_name": "Country",
    "postcode_field_name": "Postcode"
  }
}

Example CSV file that would import additional location IDs as well as the visitor's location for using latitude and longitude

EmailAddress,latitude,longitude,local_store_latitude,local_store_longitude
test_uk@example.com,-1.4304542541503906,50.962339396267446,-0.07894277572631836,51.50027116593512

To make this import correctly, you need to set the channel's import field mapping to:

{
  "email": {
    "ftp_field_name": "EmailAddress"
  },
  "location_ids": {
    "location_type": "latlng",
    "latitude_field_name": "local_store_latitude",
    "longitude_field_name": "local_store_longitude",
    "location_sets": "template:uk-cities|mystores",
    "list_separator": "|",
    "max_distance": 10000
  },
  "location": {
    "location_type": "latlng",
    "country_code_field_name": "latitude",
    "postcode_field_name": "longitude"
  }
}

Example CSV file that would import additional locations by providing the location IDs

email,id,first_name,gender,discounted,store
test17815a@example.com,11111,Jim,m,20%,southampton

To make this import correctly, you need to set the channel's import field mapping to:

{
  "email": {
    "ftp_field_name": "EmailAddress"
  },
  "location_ids": {
    "mapped_location_sets": {
      "mystores": "store"
    }
  },
  "location": {
    "location_type": "latlng",
    "country_code_field_name": "latitude",
    "postcode_field_name": "longitude"
  }
}

Using mapped_location_sets takes preference and overwrites any resolved values - latLng or postcode.

Import a wishlist with a person import

The wishlist data source shows products that the current person has added to their wishlist on another system. The wishlist is then imported into Fresh Relevance and is stored in the field person.extend.wishlist.

The import is driven by a person import file which contains a JSON structure containing product IDs along with quantities and date added.

Here's an example of a wishlist structure for one person, containing two products that they have on their wishlist. It needs to be imported into the field person.extend.wishlist.

The product IDs must match with the product IDs in the Fresh Relevance database.

{
  "product_id1": {
    "qty": 1,
    "dt": "2014-01-01T12:13:14Z"
  },
  "product_id2": {
    "qty": 1,
    "dt": "2014-01-01T12:13:14Z"
  }
}

An example field mapping for import might be:

{
  "email": {
    "ftp_field_name": "email"
  },
  "person.extend.wishlist": {
    "ftp_field_name": "wishlist_data"
  }
}

An example CSV import file, for one person, might look something like this:

email        wishlist_data
first.last@example.com        {"prid1": {"qty": 1, "dt": "2014-01-01T12:13:14Z"},"prid2": {"qty": 1, "dt": "2014-01-01T12:13:14Z"}}

Wishlist structure with variants

It’s also possible to import a SKU-level product variant into a wishlist by adding the variant's ID in the vid field:

{
  "product_id1": {
    "vid": "small",
    "qty": 1,
    "dt": "2014-01-01T12:13:14Z"
  },
  "product_id2": {
    "vid": "medium",
    "qty": 2,
    "dt": "2014-01-01T12:15:14Z"
  }
}

To add multiple variants of the same product you can also include an array of different variants to add:

{
  "product_id1": [
    {
      "vid": "small",
      "qty": 1,
      "dt": "2014-01-01T12:13:14Z"
    },
    {
      "vid": "medium",
      "qty": 2,
      "dt": "2014-01-01T12:15:14Z"
    }
  ]
}

Advanced - Encryption

You can encrypt the data being sent to Fresh Relevance using GPG encryption. To do this, you must import our public key into your GPG software.

This is the key certificate, which you should save into a text file with a .cer extension:

Import segments and person data from your messaging provider

Expand the User menu and go to Settings > Imports.
Select Person Import Channels.
Expand the Set up a new channel drop-down menu and select your messaging provider.
Select CREATE IMPORT CHANNEL.
Enter a channel name to identify this import job.
Enter the requested details for your messaging provider.
Optionally, select the Is Service Paused? checkbox to stop the processing of this import job. Clear the checkbox to restart it.
Select SAVE.

Bulk delete person records

Before you start

Files which are imported must have a filename containing person_delete.

Expand the User menu and go to Settings > Imports.
Select Person Import Channels.
Expand the Set up a new channel drop-down menu and select Import records to delete from FTP.
Select CREATE IMPORT CHANNEL.
Enter the details for:
- Channel name
  To identify the specific import job.
- FTP Type
  Only sFTP and FTPes protocols are supported to protect your data and ensure privacy. Regular FTP is not supported.
- FTP Host
- FTP Port
- FTP User Name
- FTP Password
- FTP Access Interval
- FTP Directory
- FTP Allowed Files Pattern
- FTP Field Pattern
- Polling Interval
Optionally, select the Is Service Paused? checkbox to stop the processing of this import job. Clear the checkbox to restart it.
To receive an alert if the import job encounters an error, enter an email address in the Error Alert Email field.
Separate multiple email addresses with a comma. Leave blank to receive no notifications.
Select SAVE.