Go back

Getting started

It's easy to get started using Flatfile. For people using Javascript or jQuery, you have two distinct paths you can take. You can use our NPM package or a CDN to load Flatfile.

In this guide, we will use the bare minimum to get up and running with Flatfile, but in order to get the most out of Flatfile's Portal, continue to the next few pages in order to get data validation implemented.

You'll need a license key to continue. Log in to your account to access the flatfile dashboard. Under the Portal section, you'll see a Setup option that will walk you through how to obtain your license key.

The Basics

Whether you're using the npm package and importing it into your code or working with static html files and the CDN, the very basics of how to work with Flatfile remain the same. The differences between the two implementations can be seen below in separate sections, but in this section, we will talk about each required piece of Flatfile.

If you're working with with static index.html files, you'll need to run some sort of a simple server in order to see Flatfile work locally. One of the simplest servers you can run is with a python server. If you have python installed (which comes included with most operating systems), then you can open a terminal or command line program, navigate to the directory where the index.html file is and run python -m SimpleHTTPServer 8000. Once the server is running, you'll be able to open a browser and go to localhost:8000 and see the served version of the webpage.

The first thing you will do is either import the Flatfile package or use a script tag to reference the CDN. Once that is complete, you'll need to start a new reference to the

FlatfileImporter
passing in your license key and the Flatfile options. The two required keys for the options are the
type
of import and the
fields
you'll want to have in your imports.

One other required aspect of using Flatfile is referencing the user or customer with the 
setCustomer
 method. This helps you identify and match imports to their respective users from within your system. When calling the 
setCustomer
 method, you'll pass in an options which is a reference to the endUser object in our SDK. The only required key is the 
userId
, but we recommend using all of the keys possible to help better identify the user uploading the files.
The final piece to working with Flatfile is to start the import. When doing this, you will use the 
requestDataFromUser
 method to start the import which will create a Promise that you can chain with a 
.then()
 to grab your results and do something with them. You'll see here in this example that we have put this call inside of a function that we are using with a click event tied to an element with an id of 'flatfile-button'.
Example using NPM
If you're using a modern framework like Angular or Vue (for React users, check out our React documentation and for Angular users, check out our Angular documentation) or you have a nice build system like Webpack in place. You can install and use Flatfile as an external dependency via NPM. Also note that you'll need to use your license key. In the code snippet where it says, 
"Replace me with your license key!"
, you'll just want to replace the text inside the quotes with the licesne key you got from your dashboard above.
Below is the full example. Do note that we are referencing an element with the id of 
flatfile-button
 and adding a click event to it in this example. In order for this to work properly, you will need some button or other element that matches this id.
Example using CDN
The latest version of the package is available via CDN. You can just a script tag into your website and start using Flatfile. Add the following code before the ending 
</body>
 tag in your html.
Using a static html file
In the example below, you'll get a basic version of the Flatfile importer. Reminder, you'll need to use your license key. In the code snippet where it says, 
"Replace me with your license key!"
, you'll just want to replace the text inside the quotes with the licesne key you got from your dashboard above.
Developers
Next:Options