Onboarding - File Specifications
OVERVIEW
This article will overview how to deliver both Onboarding (emails-to-behaviors) and Onboarding Opt-Out (list of emails to opt-out of Lotame onboarding) files.
Supported File Transfer Mechanisms
Lotame will support transfers to a Lotame-hosted S3 bucket for the Onboarding Beta.
There are two methods for connecting to a Lotame-hosted s3:
ARN Authentication
Lotame requires the client to provide an ARN of the AWS IAM role that will be used to access the bucket through an automated upload.
Access Key and Secret Access
Lotame will provide the client with an Access Key and Secret for authentication.
This allows clients to use a desktop AWS S3 client to upload files as described on the Onboarding BETA - Manually Uploading Data Files to Lotame S3 page.
Lotame will provide:
The AWS S3 bucket name to which to upload files.
A directory structure under that bucket that looks like the following:
s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=<client_id>/type=<DATA_or_OPTOUT>/
<client_id> will be a numerical identifier for the Lotame account this data is being loaded into.
<DATA_or_OPTOUT> DATA is for data files. OPTOUT is opting out emails. These are selected by you are upload time depending on the type of upload you are sending.
This directory structure is explained further in each section below.
Data File Specification
Lotame supports two file types for uploading plaintext emails and SHA-256 encoded emails: JSON and CSV. Descriptions of their formats are below.
These files will be uploaded to the DATA directory: s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=<client_id>/type=DATA/<filename>
CSV
Below is the description of the file formatting specs of the CSV file. This file will contain the 1 email in Column 1 with the associated behaviors in the following columns. Each email should only be provided once in a file.
For CSV, the filenames are required to be:
- PlainText Email: <custom_name>_EMAIL.csv
- Examples:
- s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=DATA/newsletter_subscribers_EMAIL.csv
- s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=DATA/website_subscribers_EMAIL.csv
- Examples:
- SHA-256 Encoded Email: <custom_name>_EMAIL_SHA256.csv
- Examples:
- s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=DATA/newsletter_subscribers_EMAIL_SHA256.csv
- s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=DATA/website_subscribers_EMAIL_SHA256.csv
- Examples:
Note: The value <custom_name> is created by you. It should be something that you describes your dataset. So if you have multiple files uploaded, you will be able to know which is what when interacting with them in the Lotame Platform UI.
Note 2: The EMAIL or EMAIL_SHA256 values in the filename must be uppercased.
Column # | Required? | Description |
1 | Yes | The plaintext or SHA-256 encoded email. |
2..as-many-as-needed | Yes | Each column from 2 on should be a segment you want to associate with the email. Pass as many as needed. |
Below is an example CSV file of SHA-256 encoded emails:
9b431636bd164765d63c573c346708846af4f68fe3701a77a3bdd7e7e5166254,Male,AutoBuyer
699af750cdf768a83ca4059ea041da08b86631321f3cedcf5b8ce8f0a872962d,Rock Music,Country
539bbd7479dbf8a353a0e7e25e6570264a912d7b1c10bbe4c645752a98fcee5c,Football,Hockey
Below is an example CSV file of plaintext emails:
user1@example.com,Male,AutoBuyer
user2@example.com,Rock Music,Country
user3@example.com,Football,Hockey
JSON
Below is the description of the file formatting specs of the JSON file. This file will contain the emails (plaintext or SHA-256 encoded) and behaviors. Each row in the file is a JSON object for a single email without line breaks.
The file must be GZIP'd to be space efficient and minimize transfer timings and extra transfer costs of an unzipped file.
For JSON, the filenames are required to be:
- PlainText Email: <custom_filename>_EMAIL.json.gz
- Examples
- s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=DATA/newsletter_subscribers_EMAIL.json.gz
- s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=DATA/website_subscribers_EMAIL.json.gz
- Examples
- SHA-256 Encoded Email: <custom_filename>_EMAIL_SHA256.json.gz
- Examples
- s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=DATA/newsletter_subscribers_EMAIL_SHA256.json.gz
- s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=DATA/website_subscribers_EMAIL_SHA256.json.gz
- Examples
Note: The value <custom_name> is created by you. It should be something that you describes your dataset. So if you have multiple files uploaded, you will be able to know which is what when interacting with them in the Lotame Platform UI.
Note 2: The EMAIL or EMAIL_SHA256 values in the filename must be uppercased.
Key | Data Type | Required? | Description |
userid | String | Yes | The plaintext or SHA-256 encoded email. Note: A userID should only appear once in a given file. |
segments | Array of Strings | Yes | An array of behaviors you want to associate with the emails. |
Below is an example JSON file of SHA-256 encoded emails:
{"userid":"9b431636bd164765d63c573c346708846af4f68fe3701a77a3bdd7e7e5166254","segments": ["Male","AutoBuyer"]}
{"userid":"699af750cdf768a83ca4059ea041da08b86631321f3cedcf5b8ce8f0a872962d","segments": ["Rock Music", "Country"]}
{"userid":"539bbd7479dbf8a353a0e7e25e6570264a912d7b1c10bbe4c645752a98fcee5c","segments":["Football","Hockey"]}
Below is an example JSON file of plaintext emails:
{"userid":"user1@example.com","segments": ["Male","AutoBuyer"]}
{"userid":"user2@example.com","segments": ["Rock Music", "Country"]}
{"userid":"user3@example.com","segments":["Football","Hockey"]}
Opt-Out File Specification
The Opt-Out file(s) allow you to upload a list of emails that you want opted-out of processing. If there is more than one Opt-Out file uploaded, Lotame processing concatenates them and de-deduplicates them. That combined and deduplicated list is then process across all of your active Data files.
- File Type - CSV
- File Contents - single-column list of emails that you want to be opted-out of processing
- File Upload Location: s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=<client_id>/type=OPTOUT/<filename>
- File Names:
- PlainText Email: <custom_filename>_EMAIL.csv
- Examples:
- s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=OPTOUT/newsletter_optout_list_EMAIL.csv
- s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=OPTOUT/website_optout_list_EMAIL.csv
- Examples:
- SHA-256 Encoded Email: <custom_filename>_EMAIL_SHA256.csv
- Examples
- s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=OPTOUT/newsletter_optout_list_EMAIL_SHA256.csv
- s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=OPTOUT/website_optout_list_EMAIL_SHA256.csv
- Examples
- PlainText Email: <custom_filename>_EMAIL.csv
Note: The value <custom_name> is created by you. It should be something that you describes your dataset. So if you have multiple files uploaded, you will be able to know which is what when interacting with them in the Lotame Platform UI.
Example for plaintext emails:
user1@example.com
user2@example.com
user3@example.com
Content aside
Categories
-
- Activation Channel Partners
-
- Inbound to Spherical
- Overview
- Use Case: ID Mapping
- Use Case: Sending Behaviors to Spherical
- Use Case: Sending Sightings Data Only
- Use Case: Lotame Data Exchange
- Supported File Transfer Mechanisms
- Supported ID Types
- How to Create and Share Public SSH Keys
- Passing User Consent
- Onboarding - File Specifications
- Manually Uploading Onboarding Files to Lotame S3
- Outbound from Spherical
- Inbound to Spherical
- Data Collection with Lightning Tag
- Administrative API
- User ID Syncing
- Single Sign-On (SSO)
- Lotame Panorama ID—Prebid, Google ESP & Amazon CxM
- 4 wk agoLast active
- 86Views
- 1 Following