Flatfile Spaces are micro-applications, each having their own database, filestore, and auth. Use Spaces to integrate Flatfile into your data exchange workflow, whether that happens directly in your application or as part of an offline process.

You can think of a Space as a home for any one of your Customers’ data, or as place for a discrete data migration session; you can create a new Space any time you need an isolated place to migrate new data.

Terminology note: Spaces are sometimes referred to as “Projects” in Flatfile conversations - this is because we often consider them to be a single import or series of imports from a single end-customer, or, a “Project”.

​
Anatomy

A Space is comprised of Workbooks, Files, Users, Documents, Themes and Metadata:

  • Documents - Custom pages mounted on the Space, displayed in sidebar
  • Files - Uploaded directly to a Space for processing
  • Users - Admins and configurable Guest Users (temporary or named)
  • Metadata - Raw data that you can use for configuration and customizations. Learn more about utilizing metadata effectively.
    • Themes - Space-level customization nested in Metadata for branding and appearance
  • Workbooks - Blueprint-defined databases containing structured data
  • Sheets - Blueprint-defined individual data tables

​
Creating Spaces

​
Basic Space Creation

Create a simple Space with Workbook configuration:

import { FlatfileApi } from "@flatfile/api";

const api = new FlatfileApi({
  token: process.env.FLATFILE_TOKEN,
});

const space = await api.spaces.create({
  name: "Customer Data Import",
  workbook: {
    name: "Customer Onboarding",
    sheets: [customerSchema],
  },
});

console.log(`Space created: ${space.id}`);

​
Advanced Space Configuration

Configure Space with custom settings:

const space = await api.spaces.create({
  name: "Product Catalog Import",
  description: "Import and validate product catalog data",

  // Access control
  guestAccess: true,
  allowedDomains: ["@yourcompany.com"],

  // Blueprint definition
  workbook: {
    name: "Product Catalog",
    sheets: [productsSchema, categoriesSchema],
    actions: [
      {
        operation: "validate-skus",
        label: "Validate SKUs",
        description: "Check SKU uniqueness and format",
      },
    ],
  },

  // UI customization
  theme: {
    primaryColor: "#635BFF",
    logo: "https://yoursite.com/logo.png",
  },

  // Metadata for tracking
  metadata: {
    project: "Q1-2024-catalog-update",
    department: "marketing",
    priority: "high",
  },
});

​
Space Customization

For advanced UI customization, see Customize Guest Sidebar.

​
Branding and Theming

For complete theming capabilities, see our comprehensive Theme Your Space guide.

Basic theming example:

const brandedSpace = await api.spaces.create({
  name: "Partner Data Import",
  theme: {
    primaryColor: "#635BFF",
    secondaryColor: "#8B85FF",
    logo: "https://yoursite.com/logo.png",
    favicon: "https://yoursite.com/favicon.ico",

    // Custom CSS
    customStyles: `
      .header { background: linear-gradient(135deg, #635BFF, #8B85FF); }
      .upload-area { border: 2px dashed #635BFF; }
    `,
  },

  // Custom messaging
  messages: {
    welcome: "Welcome to our partner data import portal",
    uploadInstructions: "Please upload your product catalog in CSV format",
    completionMessage: "Thank you! Your data has been successfully imported.",
  },
});

​
Configuration via the Space Configure Plugin

For complete configuration options and advanced usage patterns, see the Space Configure Plugin documentation.

Use the Space Configure Plugin to programmatically set up Spaces with a declarative configuration. The plugin automatically listens for the space:configure event that’s triggered when a new Space is created:

import { configureSpace } from '@flatfile/plugin-space-configure';

export default function (listener) {
  listener.use(
    configureSpace({
      workbooks: [
        {
          name: 'Customer Data',
          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' },
              ],
            },
          ],
        },
      ],
      space: {
        metadata: {
          theme: {
            root: { primaryColor: '#635BFF' },
          },
        },
      },
      documents: [
        {
          title: 'Welcome Guide',
          body: '<h1>Welcome!</h1><p>Follow the steps to import your data.</p>',
        },
      ],
    })
  );
}