SFTP Audience Integration Guide

The Rokt Ads SFTP integration enables advertisers and technology partners to securely send audience segments to Rokt in batches formatted as one or more .csv files, keeping data user data in sync for use in campaign targeting and suppression. Keeping audiences synced with Rokt Ads leads to fewer ads served to the wrong users, which reduces wasted spend and improves overall campaign performance.

Prerequisites

Before you begin, ensure you have:

• Access to an SFTP client (e.g., FileZilla, WinSCP, or command-line sftp)
• A Keybase account for secure credential exchange

1. Create CSV files

To ensure your audience data can be successfully sent to Rokt, format it as a CSV file according to the following guidelines:

File format requirements

• Files must adhere to RFC 4180 CSV format standards.
• Supported file formats:
  • Plain CSV (.csv)
  • ZIP archive containing one or more CSV files (.zip)
  • Gzip-compressed CSV (.csv.gz)
  • PGP-encrypted files with .gpg extension (e.g., .csv.gpg or .csv.gz.gpg). Contact your Rokt Account Manager for Rokt's public key.
• File size: 5 MB – 2 GB (optimal). Split larger datasets into multiple files for parallel processing.
• Maximum 50 columns per file.
• Maximum row size: 80 KB.
• All column names must be unique.
• Do not use subfolders when uploading.

File naming

Use the following naming convention for your files:

File Name Pattern	Example
<name>-audience.csv	premium_users-audience.csv

caution

Avoid dashes (-) and dots (.) in the <name> portion of your file name. The dash before audience is required.

Data requirements

Each row must include at least one valid user.

note

Rows missing valid identity values will fail processing. Ensure at least one identity column contains a value for every row.

Root-level fields

Column Name	Example Value	Notes
environment	production	Environment identifier (e.g., development, production).

User identities

Column Name	Example Value	Notes
user_identities.email	j.smith@example.com	User's email address (plaintext).
user_identities.other	fab1e2e699b3b927cbf875046a64f222	Hashed email or other identifier. Use SHA-256. Lowercase and trim trailing spaces before hashing.

User attributes

Include as many of the following attributes as available to improve matching:

Column Name	Example Value	Notes
user_attributes.FirstName	John	Customer's first name.
user_attributes.FirstNameSha256	fab1e2e699b3b927cbf875046a64f222	SHA-256 hash of first name. Lowercase and trim spaces before hashing.
user_attributes.LastName	Doe	Customer's last name.
user_attributes.LastNameSha256	fab1e2e699b3b927cbf875046a64f222	SHA-256 hash of last name. Lowercase and trim spaces before hashing.
user_attributes.Mobile	3125551515	Phone number. Accepts 1112345678 or +1 (222) 345-6789 formats.
user_attributes.MobileSha256	fab1e2e699b3b927cbf875046a64f222	SHA-256 hash. Format as 5551234567 (digits only, no country code).
user_attributes.Age	33	Customer's age.
user_attributes.Dob	19900717	Date of birth in YYYYMMDD format.
user_attributes.Gender	M	Customer's gender: M, Male, F, or Female.
user_attributes.City	Brooklyn	Customer's city.
user_attributes.State	NY	Customer's state (two-letter code for US).
user_attributes.Zip	11201	Customer's zip/postal code.
user_attributes.Title	Mr	Customer's title: Mr, Mrs, Ms, etc.

Device identities

Column Name	Example Value	Notes
device_info.android_advertising_id	38400000-8cf0-11bd-b23e-10b96e40000d	Google Advertising ID (GAID) for Android.
device_info.android_uuid	550e8400-e29b-41d4-a716-446655440000	Android device UUID.
device_info.ios_advertising_id	38400000-8cf0-11bd-b23e-10b96e40000d	iOS Advertising ID (IDFA).
device_info.ios_idfv	550e8400-e29b-41d4-a716-446655440000	iOS Identifier for Vendor (IDFV).

Audience attributes

For audience data, include the following columns:

Column Name	Example Value	Required	Notes
external_audience_id	premium_users	Yes	Name of the audience.
action	add	Yes	Accepted values: add or remove. Use add to include the user in the audience, or remove to exclude them.
change_timestamp_ms	1713895200000	No	Unix timestamp of the audience membership change (in milliseconds).

Example CSV files

Download a sample file to use as a template:

RoktSample-audience.csv

2. Get SFTP credentials

Rokt uses Keybase for secure credential exchange.

SFTP server details:

• Host: sftp://sftp.us2.mparticle.com
• Port: 4422

SFTP clients (e.g. FileZilla, WinSCP)

When using a graphical SFTP client, use Host sftp.us2.mparticle.com, Protocol SFTP, and Port 4422 (or paste sftp://sftp.us2.mparticle.com if your client accepts a full URL). Enter the username and password from your Account Manager when prompted.

To obtain your credentials:

1. Create or log into your Keybase account at keybase.io.
2. Share your Keybase username with your Rokt Account Manager.
3. Your Account Manager will send your SFTP credentials via encrypted Keybase chat.

tip

Keep your credentials secure. Do not share them via email or other unencrypted channels.

3. Upload CSV files

1. Connect to the SFTP server:

sftp -P 4422 your_username@sftp.us2.mparticle.com

2. Navigate to or create the drop folder structure:

cd drop
mkdir US2-123456789123456789  # Use the folder name provided by your Account Manager
cd US2-123456789123456789

3. Upload your CSV files:

put premium_users-audience.csv

caution

Verify there are no trailing spaces in folder names. The folder name is case-sensitive.

What happens next

Files are added to the processing queue immediately after upload. Contact your Rokt Account Manager if you need to verify successful processing or encounter any issues.