Use the Tool in This Section – Easily Import Historical Data into Segment with a CSV
Segment CSV Importer allows you to import all of your historical data in the form of a CSV file to Segment in a matter of seconds. All you need to do is upload your CSV file to Segment CSV Importer and it will send your data to Segment which in turn sends it to all your integrations, such as Mixpanel or Amplitude.
in a CSV file
Copy Write Key
Paste into importer
Upload CSV & click
You can use this template, and the guide lower on this page, to structure your import CSV. Once your data is filled in on the Google Sheet, export to CSV and use that file to import below.
How to Use This Segment CSV Importer
What You Can Use This User Data Import Tool for
What if you want to use data collected prior to your Segment implementation?
And what if you want to use offline user data, e.g. CRM actions, in-person events, or sales history?
This Segment CSV import tool is the answer to your historical and offline user data woes. It allows you to upload bulk user data into Segment in a simple, quick, and effective way.
The tool uses a connector to Segment API that we built, as well as the taxonomy template in CSV. The work draws from our experience as a technology partner of Segment, and a MarTech agency with an extensive track record of setting up data integrations.
Before You Start Uploading Your Bulk Data Into Segment
Upon loading, our Segment CSV Importer asks you to enter your segment write key and upload your CSV file.
EXERCISE CAUTION. USE A TEST ACCOUNT TO SEND DATA BEFORE YOU TRY IT ON YOUR LIVE ACCOUNT.
The import is permanent, and in most cases, the bulk of data you upload can’t be removed. Use extreme caution. As with any Segment integration, setup a separate sandbox account in Segment. It’s also a good idea to use a sandbox project in the data destination, like Amplitude or Mixpanel.
Now that you’ve considered the above, you’re ready to import your bulk data.
1. CSV Import File Specifications & Template
We’ve made a taxonomy template in CSV for you. Save time by using it to just fill in your data instead of starting from scratch, or to reformat an existing CSV file by following the template. The result will look something like this:
Below are a few main concepts to remember:
- The CSV file should cover some mandatory fields that allow Segment to detect the action you want to perform with your data.
- We combined two Segment import actions – Identify – “who is the customer?”, and Track – “what are they doing?”. For every row in your CSV, we send an Identity Segment action with Traits fields, and then we send a Track event using Event and Properties data from the row. By doing so, we avoid requiring you to split your data into separate lists with Identity data and Track data. You can import one file for both.
- Every row in your CSV should represent an event that the user performed, timestamp of the event, traits that describe the user, and the user properties associated with the event in your taxonomy.
- If you only need to update user traits and don’t want to track an explicit user action, you can do that, too. Use something like user updated or user traits imported for the event to make it clear that the user didn’t take action, and that it was only an update to their user profile.
In short, your CSV should have the following fields:
- Identity – user ID
- Timestamp – our importer can take a variety of formats
Uploading batches of your historical or offline user data, so that Segment can send it downstream, is contingent upon consistent taxonomy without mistakes.
If you haven’t established your stack taxonomy yet, or if you’re just seeking guidance to make your taxonomy more consistent, check out our event spec template for Segment. It is a file we’ve used to train our clients and team members, and it will show you an example of how you can structure the taxonomy used across your stack.
2. Finding the Write Key
The write key allows our app to connect with your workspace. A workspace is a group of sources, linked together so you can control them together via the CDI. You can think of the write key as a unique identifier that tells Segment two essential things:
- What is the source that generated the data
- Where the data should be piped to. Which integrations – business tools and apps interlinked via Segment such as Mixpanel or Amplitude, and workspaces should receive it.
The key is called a write key because it tells Segment which workspace the data should be written into (imported). To exemplify – when importing data into a user analytics tool such as Mixpanel or Amplitude, you use the write key for the workspace that contains the integration of the user analytics tool.
Now that you know what the write key is for, follow these steps to find yours:
- Navigate to segment.com
- Log in with your account
- Select your desired workspace. It will take you to your sources.
- Click on the relevant source
- Click Settings
- On the left, click API keys
- Copy the Write Key, per image below:
Now you’ll have the key you that you can paste into our Segment CSV Importer.
3. Uploading the File
Now that you’ve prepped your CSV file, and that you have your write key that you’ve pasted it in:
- Click on the Choose File button to upload your data in .csv
- After you choose your file, you’ll see a basic format of your file, and the first two records from your CSV file
- Click “Import” at the bottom left of the page
- If everything is OK, you’ll see a message saying “Data sent”
That’s all. Marketing technology can be that simple.
Back-end Specs of This Segment CSV Import Tool
If you’re a dev and want to know how our tool works on the back-end, or if you’re just curious about what the tool does behind the scenes, this list is for you.
- More than 10k rows of bulk data can be handled by the tool at once. We’ve worked on stability as a core quality.
- All of the front-end, the web interface, happens on our site. Namely on this very page.
- The CSV template consolidates Track and Identify requests into one. You only have to do one import, not two.
- The CSV file is sent to the server via an API connector on our end
- Headers of the CSV file are consolidated:
- Renames Identity to UserID
- Structure Traits and Properties as an associative array
- The time format that can be entered and correctly parsed is flexible. This is due to the feature we’ve developed for transforming the date into a timestamp in the ISO 8601 extended format. Thanks to that, the date you put in can be anything meaningful. We use the strtotime PHP function to execute the transformation. As a result, the time stamp can be almost anything:
- Correct date formats include 30/08/2019, 2019/8/30, 2019-8-30, 30.8.19, 30-August 2019, 30AUG19, etc.
- American vs European
- The PHP function disambiguates dates in the m/d/y or d-m-y formats by looking at the separator between the various components. If the separator is a slash (/), the American m/d/y is assumed. If the separator is a dash (-) or a dot (.), the European d-m-y format is assumed. If, however, the year is given in a two digit format and the separator is a dash (-), the date string is parsed as y-m-d. To avoid potential ambiguity between the European and American formats, it’s best to use ISO 8601 (YYYY-MM-DD) dates, or to use dates with the month name spelled out.
- If you enter timestamps in the ISO 8601 extended format yourself, there should be two-digit months and two-digit months. 2019-04-4T00:00:02.000Z would be wrong because of a missing zero in the day number, 2019-04-04T00:00:02.000Z would be correct.
- The tool combines row data in a pack until the pack size reaches 32Kb. Then the pack of data is sent. This is repeated until the end of the CSV file.
We hope you love the tool and get value out of it as much as we and our clients do. If you’d like to talk to us about anything related to your marketing analytics, run an audit of your MarTech stack, or get help with implementing Segment first, talk to us.
Bonus #1: User Data Import Example – Mixpanel CSV Upload
One of the most popular use cases for user data import into Segment is the import of historical or offline data into a user analytics tool. One of the most popular user analytics tools is Mixpanel. We’ll use that as an example to elaborate on, and you can also continue reading at the bottom of this page for other high-value use cases for user data import into other tools.
The standard way to import user data into Mixpanel would be to follow instructions for importing old events, and use the /import endpoint in the API. That doesn’t sound simple, and it isn’t. Moreover, all the work you’d put into the data import would only make a difference in Mixpanel – not any other linked tools in your Segment workspace.
Using our CSV import tool above is a better alternative – quicker and with a broader application.
To import data into Mixpanel, follow the steps (1.) through (3.) as described above.
Mixpanel User Data Import Use Cases
There are a plethora of applications for uploading historical or offline data into Mixpanel via Segment. To inspire your work about full-picture user analysis opportunities, we’ll mention a handful.
- Send any offline data about the user as people properties:
- Lead score data from your sales tool
- Touchpoint or attribution data from your TV ad campaign
- Historical data:
- From the user analytics tool you were using before Mixpanel
- Touchpoint or attribution data collected by your online lead nurture campaigns before you consolidated your MarTech stack into the CDI
- Online data from databases that aren’t synced yet:
- Create funnel reports and analysis by uploading user profile data currently stored in S3, MySQL, or Hive
Bonus #2: 5 Scenarios for Valuable User Data Imports
Managing, integrating and transferring user data to several tools and warehouses holds immense value. That is further amplified if the data can maintain its integrity without repeated coding or remodeling. As a result, your reporting and analysis will become more accurate and actionable. You may also gain the ability to analyze the full customer journey. Below are some of our favorite use cases for the CSV user data import tool.
#1 Sales Data
Import Salesforce data about deal stages or closed optees into Amplitude (or Mixpanel) for an end-to-end ROI analysis. You’ll use email as the user identifier to bring offline and online data together.
#2 POS and Loyalty Data
Point of sales systems store data about using loyalty cards. There’s often a crappy log file that stores information about who the user is and what actions they took from a loyalty perspective. If you can transform that data into a CSV import file consistent with your taxonomy and upload it via Segment, you’ll gain the ability to run an ad hoc analysis for business intelligence.
#3 Context for Automated Marketing Messaging
Effectiveness of email and SMS automation can be increased when the messaging tool has more context to work with. Before the import tool, you’d have to upload to each tool separately, which quickly gets labor-intensive. Now, you can upload once to Segment and pipe the data into multiple platforms, including the one for email automation. This works great with tools such as Active Campaign, Autopilot, or Customer.io.
#4 Custom User Attributes
Tools such as Intercom can help you maintain or improve customer relationships with real-time business messaging. Importing user attributes that you previously only used in other tools can help you truly drive loyalty and growth at the different stages of your customer lifecycle.
#5 Cohort Analyses
Cohort analysis in user analytics tools can lead to some of the biggest improvements in your marketing. In Amplitude, importing additional user data to define behavioral cohorts will enable you to use some of the most valuable reports in the tool – Event Segmentation, Funnel Analysis, or Retention Analysis.