Skip to main content
Version: v3.0

Flatfile Developer Documentation

Learn how to use Flatfile to import, exchange, and migrate unstructured data.



What is Flatfile?

Flatfile is a platform for exchanging data between businesses.

To your end users, Flatfile is an easy-to-use data importer that accepts their messy, unstructured data and allows them to submit it quickly and easily.

To your customer success team, Flatfile is an automated data processor that cleans and validates incoming customer data, replacing hours of back-and-forth communication.

And to your developers, Flatfile is a powerful data engine that can be configured to accept, transform, and validate data so that it arrives in your systems in exactly the right shape.

Intro Artsy SampleIntro Artsy Sample

How it works​

  1. Configure a data engine in code using our SDK and deploy it to Flatfile.
  2. Embed an import UI component into your app to collect data from your users.
  3. Send the cleaned, processed data to your systems using a webhook or our API.
Intro Artsy SampleIntro Artsy Sample

Quickstart command​

Get your keys, pull in a sample project, and deploy to Flatfile, all from your terminal in just a few minutes.

Set up the CLI

Assumptions​

We are here to help you get started implementing Flatfile into your current application, but first, we want to let you know up front the assumptions we are making in this documentation (and also provide some resources if you need a refresher).

  • You should be familiar with a package manager OR CDN provider. We reference using either NPX, NPM or a CDN link within the docs themselves, so knowing about working with one of these helps. If you prefer working with Yarn over NPM, we've got you covered there too. We just reference the NPM commands throughout the documentation.
  • You should have a basic understanding of JSON and how to work with JSON objects.. At the end of an import, Flatfile will return a JSON object. It doesn't matter if your backend is Ruby, C#, Python, Node.js, PHP or anything else you could be using. We will give you clean data as JSON and a way to send it to your server. Your server will take it from there.

Key terminology​

A note about terminology used in this documentation. There are a few terms we'll use that have alternate meanings, and you may be more familiar with the other definitions. We feel it's important for us to clarify the terminology below.

  • field - This often gets used interchangeably with a column of similar data. For example, if you're accepting a full name, email address and phone number in your data, each of those would be their own field.
  • record - You might refer to this as a row or line. This is referring to an individual record/row/line of the data. So this would encompass one person's name, email address and phone number.
  • value - This one you might refer to as a cell. It's the intersection of a specific record and specific field. If, for example, you want the email for one specific record, this is the value or cell we're referring to.