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",
  },
});

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

​
Space Types and Patterns

​
User-Specific Spaces

Create dedicated Spaces for individual users:

const createUserSpace = async (userId, userEmail) => {
  return await api.spaces.create({
    name: `${userEmail}'s Import`,
    guestAccess: false,
    users: [
      {
        email: userEmail,
        role: "owner",
      },
    ],
    workbook: userWorkbookConfig,
    metadata: {
      userId,
      type: "user-specific",
    },
  });
};

​
Project-Based Spaces

Organize Spaces around specific projects:

const createProjectSpace = async (projectId, projectName) => {
  return await api.spaces.create({
    name: `${projectName} - Data Import`,
    description: `Import workspace for ${projectName}`,
    workbook: projectWorkbookConfig,
    metadata: {
      projectId,
      type: "project-workspace",
      createdAt: new Date().toISOString(),
    },
  });
};

​
Access Control and Permissions

​
User Roles

Control what users can do within a Space:

const spaceWithRoles = await api.spaces.create({
  name: "Collaborative Import",
  users: [
    {
      email: "admin@company.com",
      role: "admin", // Full control
    },
    {
      email: "editor@company.com",
      role: "editor", // Can edit data
    },
    {
      email: "viewer@company.com",
      role: "viewer", // Read-only access
    },
  ],
});

​
Guest Access

Allow external users to participate:

const guestSpace = await api.spaces.create({
  name: "Customer Data Submission",
  guestAccess: true, // Allow guest users
  allowedDomains: ["@customer.com"], // Restrict by domain
  guestRole: "editor", // What guests can do

  // Guest-specific settings
  guestSettings: {
    requireEmail: true,
    allowDownload: false,
    showProgressBar: true,
  },
});

For advanced guest UI customization, see Customize Guest Sidebar.

​
Space Customization

​
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

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>',
        },
      ],
    })
  );
}

​
Space Monitoring and Analytics

​
Event Tracking

Monitor Space activity:

listener.on("space:*", async (event) => {
  const { spaceId, eventType } = event.context;

  // Track space analytics
  await analytics.track(eventType, {
    spaceId,
    timestamp: new Date(),
    userId: event.context.userId,
    metadata: event.context.metadata,
  });
});

​
Best Practices

​
Space Naming

Use descriptive, consistent naming:

// Good naming patterns
"Customer Import - Q1 2024";
"Acme Corp - Product Catalog";
"User Import - john@example.com";

// Avoid generic names
"Import";
"Data";
"Untitled";