Meet the Workbook

The DevXP engineering team hosts office hours every Thursday at 11 a.m. Pacific Time where we answer your questions live and help you get up and running with Flatfile. Join us!

A Workbook replaces the spreadsheet template(s) that you may currently share with others when requesting data. Unlike a spreadsheet, a Workbook enables your users to import, validate, and correct data before sending it back to you.

Prerequisites: You’ll need a Flatfile account and your secret key to complete this tutorial. Sign up and use the secret key from your development environment for this tutorial.

Building your first Workbook

Create a workbook

We’ll begin by creating a new workbook using Flatfile’s API. Paste this cURL request in your terminal to create a simple workbook or run this command directly from our docs.

Use your secret key from the development environment. Secret key format is “sk_abcd…” and is found in your Flatfile Dashboard here.

Shell / cURL
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",
  "sheets": [
      "name": "Contact",
      "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",
      "type": "string",
      "description": "Submit data to webhook.site",
      "primary": true

Using schemas

Flatfile’s Blueprint is a robust data definition language (DDL) that emphasizes validation and data preparation. Flatfile’s API expects the Blueprint format creating or updating a schema definition.

Add data to your workbook

Now that you have a Workbook, you’re now ready to start importing data with Flatfile!

  1. Head to your Spaces Dashboard and click on the Workbook you just created (My First Workbook). You may need to refresh the page.
  2. Upload a test file in the Files section, and then click the “Import” action for the file. Follow the steps to map the example data into the “Contact” sheet in the workbook.
  3. After mapping is complete, you can click on the “Contact” icon in the left sidebar and see the imported data.
  4. Additionally, you can make changes to the Workbook in the Contact sheet’s user interface by modifying existing records or adding new rows entirely.

Recap & Next Steps

In the next step, we will dive deeper into responding to record Events with transformations and validations.