Flatfile | Getting Started

How to start using Flatfile

Flatfile solutions fit into your existing data onboarding flows, and enable new flows. Let's walk through what data you want, and what you want to do with it.

Jump to the deployment project checklist

First: Understand what kind of data you need

Objective: Create your ideal data model(s)

What kind of data do you want to collect?

Who is usually involved in answering this question:

Anyone who understands the type of data your system is ingesting.

What is it:

Primary key/record type: What makes a single record unique?

"Data" is a set of information made up of individual records. The type of data is usually defined by what data makes up a single unique record within that set. This can be a single value (like "email address"), but it can also be made up of multiple values (like "first name", "last name", and "phone number").

Common examples of data (and their associated primary record types):

Contacts: ("email") or ("first name" AND "last name" AND "phone number") ("last name" AND "address")

Inventory: ("UPC") or ("Inventory number" AND "location")

Event logging: ("log ID") or ("Date time" AND "type")

Invoices: ("Invoice #") or ("Vendor" AND "Date" AND "Invoice total")

Related record data: What information is related to each single record?

Information related to the primary key is frequently accepted, if not required. You'll want to define what data you want to collect that is related to the primary key.

If we look at our primary key examples above:

Contacts: "phone number" "secondary phone number" "address" "home address"

Inventory: "units" "unit weight" "storage location" "brand" "label"

Event logging: "description" "source" "request" "count"

Invoices: "vendor" "approver" "net term"

Each data property that you want to import (both primary and related data) will be set up as a field within Flatfile.

What does the ideal version of this data look like?

Ideal data aligns perfectly with your system. It's what data looks like when that record set is complete and in its most useful state. Frequently, it's also what your data looks like if you pull the most complete and useful data out of your system.

What makes the data valid:

Your system likely needs certain data in a particular format in order to process or store it. You'll want to collect any limitations or needs related to each data property (or group of properties).


  • "Address is required if phone number and email are not present"
  • "Email must be in valid email format"
  • "First name must be capitalized"
  • "Phone number must be in (xxx) xxx-xxxx format"
  • "Description is limited to 250 characters"

If you can't find or don't know what your data should look like:

This information can usually be defined or managed by Product teams, Customer Success or Implementations teams, or Data teams who are involved with customer journeys or engagement.

Where does information about your ideal data usually exist?

  • Internal databases (wherever your incoming data is stored in its ideal format)
  • External onboarding guides and data templates

Second: Understand how you want to collect the data

Objective: Build your data flow

Where do you want to collect data?

Flatfile Portal is configured as a button on your website. The Portal importer will launch for the user when the button is pressed.

Flatfile Concierge is a standalone web app for for your team. Your team can use it as an internal tool, or invite collaborators to onboard data with you. The workspace can be launched by going to app.flatfile.com.

Where do you want complete data to go?

Cleaned data from both Flatfile products can be downloaded as a .CSV file. Portal is also configured to allow [webhooks], which push the data as it is created in browser, and [API access], which allows you to pull uploaded data into your system.

Don't know what your user's ideal data flow looks like? Forward a Flatfile team invite to someone on your team who does, and we can help them outline a solution.

Third: Configure Flatfile with your ideal data model

Objective: Technical configuration of Flatfile, using your ideal data model

In Portal (launches on your site):

Your developer will take the ideal data template and translate it into Javascript. It will need to be configured to launch somewhere on your website.

For developers: Getting started with Portal guide

In Concierge (available as a secure online workspace):

Either a developer or someone that understands the ideal data can configure the data template.

Non-technical: No-code template upload of CSV, or button selection in-app

Technical: Json schema upload

Last: Start using Flatfile in your data onboarding flows

Objective: You've done it! Delightful data onboarding at your users' fingertips.