SFTP import tool

SFTP CSV ingestion allows customers to transfer comma-separated files over SSH File Transfer Protocol to sync their customer data. Currently, the tool supports these operations:

• Event: create
• Profiles: create, update

This feature is ideal for customers who want to bulk import CSV data using an SFTP client of their choice. At this time, we allow the creation of profiles and events in Klaviyo and may, in the future, expose other data types via SFTP import. SFTP import supports a variety of fields on events and profiles as well as any custom field you wish to define.

To use this feature, you’ll first generate a public/private SSH key pair. Then, you’ll use your SFTP client to initiate an import. In this article, you’ll learn how to initiate an import and the requirements for your import, including formatting.

Before you begin

This feature is only available to Klaviyo users with an Owner, Admin, or Manager role. Learn more about Klaviyo user roles.

SSH key generation

Before getting started, generate a public/private key pair on your local machine using ssh-keygen or a tool of your choice. Klaviyo uses Amazon Web Service’s Transfer Family service to provision its SFTP server and handle authentication. Transfer Family will accept the SSH key formats listed in its documentation. 

Once you have generated your keys:

1. In Klaviyo, click your account name in the lower left corner and select Integrations.
2. On the Integrations page, click Manage Sources in the upper right, then select Import via SFTP.
3. Click Add a new SSH Key.
4. Paste your public key into the SSH Key box.
   
5. Click Add key.

Initiate your SFTP import

You can use FileZilla, Cyberduck or an SFTP client of your choice to connect to Klaviyo’s SFTP server at sftp.klaviyo.com following key creation. To establish a connection:

• Your public key must be added in the previous step for Klaviyo to properly authenticate.
• You must connect with a machine that has the private key at the location your client specifies.
• You must specify your username assigned by Klaviyo. Passwords can be left blank, as key validation is used instead of a password. To find your username, navigate to klaviyo.com/sftp/setup, where you’ll find it under Your SFTP Username.

Your connection should be set up as follows:

• Server
  sftp.klaviyo.com
• Username
  Your_SFTP_Username (abc123_def456 in the example above)
• Port
  22
• Password
  empty
• SSH Private Key
  The private key associated with the public key generated in previous steps 

In Cyberduck, your connection would look like this:

Once connected to Klaviyo’s server, you should see two remote directories titled profiles and events.

At this point, you can transfer CSVs via your SFTP client into either directory to initiate an ingest job. CSVs placed into the events folder will generate Klaviyo events and CSVs placed in the profiles folder will generate Klaviyo profiles.

Valid CSVs require specific headers and cell values must be formatted correctly for ingest to work properly. Similar to Klaviyo’s Create Profile and Create Event API endpoints, certain fields are required for data creation to occur. Valid CSV formats are explained below.

We recommend you test with a small CSV (ex. several rows) to test data generation before moving to larger CSVs in order to verify ingest works as you expect.

Please note the following about the ingest process:

• Ingested event rows will either create events or result in a “no-operation” (no-op). Given a CSV row with the same headers and values ingested twice, the second ingestion will be a no-op (essentially, the same event with the same identifying properties cannot be created twice). Events are unique on either a unique_id property or the combination of profile, time, and metric name. Uploading the same event CSV twice will result in events only being created once, given the same identifying properties.
• Ingested profile rows will create or update profiles or result in a no-op. Profiles are unique on email, phone number, or external_id. A CSV ingest of profiles can create or update profiles. The same CSV ingested twice will only create or update profiles once.
• At this time, Klaviyo assumes all files in either the events or profiles directory must be ingested and will attempt to ingest duplicate files. We recommend you name files with a timestamp to avoid duplicate file uploads.

General CSV formatting and size limitations

Klaviyo expects the first row of all CSV files passed to be a header row and subsequent rows as values to ingest. It is important to note the following:

• Commas are the only accepted delimiters and all files are expected to have a .csv extension.
• Given row values with commas or other special characters, we expect double quotes to wrap cell values or we will interpret commas as delimiters.

Cell values must be formatted according to the following data types:

• Dates
  Dates must be ISO8601 compliant.
• Phone Numbers
  Read our help article on acceptable phone number formatting.

📘

Klaviyo observes the following file limitations:

• Klaviyo will not ingest files with any row (including headers) exceeding 1MB.

Event CSV Formatting

The following are required headers for Event CSVs:

• Metric name
  Name of the Klaviyo metric you want to associate the event with. An account can have up to 200 metrics and a metric may be created when an event is created.
• Time
  When the event occurred, in an ISO8601 compliant format.

One or more of the following identifying headers are also required:

• Profile.Email
  The associated customer’s email.
• Profile.PhoneNumber
  The associated customer’s phone number. Note if Profile.PhoneNumber is the only identifying column, you must have SMS enabled in your account. 
• Profile.ExternalID
  The associated customer’s ID from another system of record.

You can also include optional special fields such as:

• Value
  The numeric value to associate with the event.
• Unique ID
  A unique identifier for the event. If this is not included, a combination of profile, time, and metric name will be used to create an identifier for deduplication.
• Other profile properties can be specified via Profile.PropertyName. For nested JSON fields, the dot notation can be used like so: Profile.Location.Zip, Profile.Location.Country.

Custom event properties can be added on via any header addition, such as MyProperty. Additionally, custom profile properties can be defined via prefacing props with “Profile,” for example, Profile.MyProperty.

View and download an example event CSV.

Profile CSV Formatting

One or more of the following identifying headers are required:

• Email
  The profile’s email address.

• PhoneNumber
  The profile’s phone number. Note if PhoneNumber is the only identifying column, you must have SMS enabled in your account.

• ExternalID
  A unique identifier used to associate Klaviyo profiles with profiles in an external system, such as a point-of-sale system. Format varies based on the external system.

You can also include optional special fields such as:

• List ID
  The List identifier you want a profile to be single-opted-in to for an email list. If you want all uploaded profiles to be subscribed to the same list, this value will be the same for all rows. If you do not want any profiles to have email marketing consent, do not populate or include this column. Please note that you must provide a valid email if you populate a List ID column in the same row. We will not process rows with an invalid List ID.
• SMS Consent
  A boolean indicating whether or not a profile has consented to SMS marketing. You can consent users into SMS marketing via SFTP by providing PhoneNumber, List ID, and SMS Consent fields. View and download an example CSV with SMS Consent.
• First Name
  Individual’s first name.
• Last Name
  Individual’s last name.
• Organization
  Name of the organization for whom the individual works.
• Title
  Individual’s job title.
• Image
  URL pointing to the location of a profile image; must be in URL format or row will be skipped.
• Location.Address1
  First line of street address.
• Location.Address2
  Second line of street address.
• Location.City
  City name.
• Location.Country
  Country name.
• Location.Latitude
  Latitude coordinate; please use up to four decimal precision.
• Location.Longitude
  Longitude coordinate; please use up to four decimal precision.
• Location.Zip
  Zip code.
• Location.Timezone
  Time zone; we recommend using time zones from the IANA TZ Database.

Custom profile properties can be added on via any header addition (ex. MyProperty)

View and download an example profile CSV.

Checking SFTP Ingest Job Status

Any in progress, failed, or completed jobs will show up in the table Recent Imports. You will receive email notifications and in-app messages for all failed and successful jobs. Klaviyo maintains logs of all jobs and is available to assist in debugging the reasons behind skipped rows.

Finally, please be aware that ingest jobs will complete prior to metrics and profiles being available in your account. 100K rows should be processed within 10 minutes. If metrics and profiles do not begin to populate in your account within this timespan, please contact Klaviyo support.

Troubleshooting

Access denied

If you encounter an Access denied error, it may be due to one of the following reasons:

• The transfer mode is not explicitly set to ASCII.

  Check if a different transfer mode is being set by default and update accordingly.

• The key is not an OpenSSH formatted public key.

  AWS Transfer Family will only accept the SSH key formats listed in its documentation. If you are using an SSH2 key, you'll need to convert it.

• The file type is not .csv