If you don’t already have one, sign up for a Flatfile account here.

To go through this tutorial you’ll need a Flatfile account. We’ll be using the credentials from your free account to assemble your first data import experience.

In your account use the quickcopy button to copy your secrets key. You’re about to use this credential to create a Workbook in your account.

Create a Workbook

The adjacent curl command creates a Workbook.

Copy this command, replace “PASTE_SECRET_KEY_HERE” with the credential you just fetched from your account, and run it in your terminal.

Congratulations! You’ve just created your first Workbook.

If you are uncertain how to use cURL, you can run the same command from our site here.

curl --request POST \
  --url https://platform.flatfile.com/api/v1/workbooks \
  --header 'Authorization: Bearer PASTE_SECRET_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "My First Workbook",
  "labels": ["simple-demo"],
  "sheets": [
      "name": "Contacts",
      "slug": "contacts",
      "fields": [
          "key": "firstName",
          "type": "string",
          "label": "First Name"
          "key": "lastName",
          "type": "string",
          "label": "Last Name"
          "key": "email",
          "type": "string",
          "label": "Email"
  "actions": [
      "operation": "submitAction",
      "mode": "foreground",
      "label": "Submit",
      "description": "Submit data to webhook.site",
      "primary": true

Meet your Workbook

So what did that just do?

In your Flatfile account you should now be able to see your Workbook.

As you can see, this Workbook has a sheet and fields. A Workbook is like a template, it’s definition includes a profile of the data it expects to hold. We call that profile a Blueprint.

Blueprint is Flatfile’s robust data definition language (DDL) that emphasizes validation and data preparation. Flatfile APIs leverage Blueprint for their create, update, and read operations.

Next steps

Now that you have a Workbook, which acts both as a schema and destination for your data, you’re ready to Setup a listener.