/* Custom styles for Flatfile docs */

/* Monospace font for code */
@font-face {
  font-family: 'Flatfile Diatype Mono';
  src: url('https://flatfile.com/fonts/FlatfileDiatypeMono-Regular.woff2') format('woff2');
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

/* Apply monospace font to code elements */
code, pre, .code {
  font-family: 'Flatfile Diatype Mono', 'SF Mono', Monaco, Consolas, 'Courier New', monospace !important;
}

em {
  font-style: oblique 12deg;
}

V2 GitHub Upgrade Example

**Welcome to the new Flatfile Developer Docs!** &nbsp; Learn more about the new docs [here](https://flatfile.com/docs/welcome-to-new-docs).

Flatfile Developer Docs

Welcome to Flatfile

Get up and running with Flatfile in minutes using AutoBuild to create a complete data import solution

Getting Started with AutoBuild

Running through the import flow with your Flatfile App

Creating Your First Project

Understanding Flatfile's building blocks and architecture

Overview

Use Environments for testing and authentication

Environments

Apps

Micro-applications for content and data storage

Spaces

Define your data schema to structure exactly how data should look, behave, and connect

Blueprints

Database-like containers with type-strict Blueprints for data import

Workbooks

Individual data tables within Workbooks that organize and structure imported data

Sheets

Blueprint definitions that define the structure and validation rules for your data in Flatfile

Fields

Individual data rows that represent your imported data in Flatfile

Records

Standalone webpages within Flatfile Spaces for guidance and dynamic content

Documents

The anatomy of Events and Listeners - core components of the Flatfile Platform

Events and Listeners

Reusable functionality modules that extend Flatfile's data import capabilities

Plugins

Discrete tasks executed by Agents in response to events

Jobs

Actions

Extend your Flatfile data engine with powerful plugins for extraction, transformation, validation, and integration

Automatically convert data in a Flatfile Sheet to match the data types defined in the corresponding Blueprint

Autocast Plugin

Automatically map columns for headless data import workflows in Flatfile with configurable confidence levels

Automap Plugin

Comprehensive boolean validation plugin for Flatfile that handles various representations of boolean values with multi-language support and flexible configuration options.

Boolean Validator

Extend Flatfile validation capabilities with custom validation logic for complex field and sheet-level constraints

Constraints Plugin

Automatically converts currency values from a source currency to a target currency using Open Exchange Rates API with support for historical exchange rates.

Currency Conversion Plugin

Automatically parse and standardize date values during data import, converting various date formats into a consistent output format.

Date Format Normalizer

A Flatfile plugin that provides functionality to find and remove duplicate records from a sheet based on specified field values or custom logic.

Deduplicate Sheet Records

Export data from all sheets within a Flatfile Workbook into delimited text files and compress them into a single ZIP archive for download.

Delimited File Zip Exporter

Parse text files with custom delimiters and automatically extract structured data for import into Flatfile

Delimiter Extractor Plugin

Validate email addresses in Flatfile data imports with format checking, required field validation, and disposable domain blocking

Email Validation Plugin

A server-side utility for Flatfile that allows users to export data from an entire Flatfile Workbook into a single, downloadable Microsoft Excel (.xlsx) file.

Export Workbook Plugin

Automatically extract data from Microsoft SQL Server backup files (.bak) into Flatfile Workbooks for easy data review and processing.

Foreign Database Extractor for Microsoft SQL Server

Automatically enrich location data using the Google Maps Geocoding API to convert addresses into geographic coordinates and vice-versa.

Geocode Address Data

Automatically processes GPX (GPS Exchange Format) files to extract waypoints, tracks, routes, and calculate geographic statistics like distance and elevation gain.

GPX File Parser and Analyzer

Automatically generate Flatfile Space configurations by converting GraphQL schemas into Workbooks and Sheets, streamlining data import setup for GraphQL APIs.

GraphQL Schema to Flatfile Blueprint Converter

Parse HTML files and extract data from tables within them, converting structured data into Flatfile-compatible format

HTML Table Extractor

A Flatfile plugin that validates and formats International Standard Book Number (ISBN) data during the import process, supporting both ISBN-10 and ISBN-13 standards with automatic formatting and conversion capabilities.

ISBN Validator Plugin

A Flatfile plugin that streamlines the handling of asynchronous Jobs by managing their lifecycle, progress reporting, and completion status.

Job Handler Plugin

Parse JSON and JSON Lines files uploaded to Flatfile and extract data into Sheets within a Workbook

JSON Extractor

Automatically transform JSON Schema into Flatfile Blueprint for streamlined data model setup

JSON Schema Converter

Automatically parse Markdown files and extract tables into Flatfile Sheets

Markdown File Extractor

Connect Flatfile to the Merge.dev unified API platform to sync data from hundreds of third-party integrations including HRIS, ATS, CRM, and Accounting systems.

Merge.dev Connection Plugin

Comprehensive validation for numeric data during the Flatfile import process with support for ranges, formats, and special number types.

Number Validation Plugin

Automatically converts OpenAPI v3.0.3 schemas into Flatfile Blueprints to streamline Space setup using existing API data structures

OpenAPI Schema to Flatfile Blueprint Converter

Extract tabular data from PDF files and convert them to CSV format using the pdftables.com service

PDF Extractor Plugin

Validates and formats phone numbers in Flatfile using country-specific validation with libphonenumber-js library

Phone Number Validation and Formatting Plugin

A Flatfile plugin that performs data analysis and summarization by generating pivot tables from workbook data and uploading them as Markdown documents.

Pivot Table Exporter

Execute custom logic on individual data records within a Flatfile Sheet with support for validation, transformation, enrichment, and cleaning.

Record Hook Plugin

Automatically apply schema changes to existing, live workbooks when a new version of a Flatfile Agent is deployed

Rollout: Automatic Workbook Updates

Automatically analyze sentiment in text fields and add sentiment scores and categories to your Flatfile records

Sentiment Analysis Plugin

Automatically configure new Flatfile Spaces by cloning an existing Space Template, including workbooks, documents, and settings.

Space Configure from Template

Programmatically set up and configure a new Flatfile Space with workbooks, sheets, documents, and metadata from a single configuration object.

Flatfile Space Configuration Plugin

Automatically create Flatfile Blueprints from SQL Data Definition Language (DDL) files to streamline database schema imports.

SQL DDL to Flatfile Blueprint Converter

Automatically applies server-side validation rules to records during the data import process using reusable JavaScript functions defined at the App level.

Stored Constraints Plugin

A comprehensive plugin for validating and transforming string data during the Flatfile import process with configurable validation rules, pattern matching, and automatic data corrections.

String Validator Plugin

Automatically enriches Flatfile data by performing text summarization and key phrase extraction on specified text fields using natural language processing.

Text Summarization and Key Phrase Extraction Plugin

Automatically translate text content in specified fields using Google Translate API and create new fields with translated content

Field Translation using Google Translate API

Automatically hides unmapped columns after the mapping stage to provide a cleaner data review experience

View Mapped Data Plugin

Send workbook data from Flatfile to external webhook endpoints for seamless integration with your systems

Webhook Egress

Forward all Flatfile events to a webhook URL for language-agnostic integration with external systems

Webhook Event Forwarder

Automatically convert What3Words addresses into standard geographic data including country codes, nearest places, and latitude/longitude coordinates using the official What3Words API.

What3Words Converter Plugin

Parse various Excel file formats (.xls, .xlsx, .xlsm, .xlsb, .xltx, .xltm) and extract structured data with support for header detection, merged cells, and hierarchical spreadsheets.

Excel Extractor

A Flatfile plugin for parsing XML files, flattening nested structures and attributes, and converting them into tabular format for easy import into Flatfile Sheets.

XML Extractor

Automates the creation of a Flatfile Blueprint (Workbook and Sheets) from one or more YAML schema definitions, streamlining the setup of a Flatfile Space by converting existing data models into a Flatfile-compatible format.

YAML Schema to Flatfile Blueprint Converter

Automatically decompress .zip files uploaded to a Flatfile Space and extract their contents as individual files

Zip Extractor

Comprehensive guides to help you master Flatfile's features and capabilities

Guides Overview

Listeners are the core of Flatfile's event-driven architecture. They respond to events throughout the data import lifecycle, from space configuration to data validation and job processing. This guide will help you understand how to create and organize listeners effectively.

Setting Up Your First Listener

Complete guide to authenticating with Flatfile using API keys, Personal Access Tokens, and managing roles and permissions

Authentication and Authorization

Using Record Hooks

Accepting Additional Fields

Learn how to use Flatfile's Advanced Filters to efficiently filter and search through your data

Advanced Filters

Learn how to customize the look and feel of Flatfile to match your brand

Theming

Translate and customize your Space with text overrides

Internationalization

Get data out of Flatfile using various transmission methods and file formats

Data Egress

Store descriptive information or data that provides additional context

Metadata

Multi-Part Jobs

Narrow down the scope of Spaces, Workbooks, and Sheets

Namespaces

Secrets

Embed Flatfile data import directly into your application

JavaScript Embedding

React Embedding

Angular Embedding

Vue Embedding

Authentication and credentials for embedded Flatfile

Authentication

Complete reference for all Flatfile events, their payloads, and when they are triggered

Event Reference

Icon Reference

Command line interface for developing, deploying, and managing Flatfile Agents

CLI Reference

Learn how to filter data in Sheets with FFQL.

Flatfile Query Language

AI-optimized documentation formats and tools for better LLM integration

For LLMs

Explore our guides and examples to implement Flatfile.

A selection of example projects to get started with.

Example Projects

Notable additions and updates to the Flatfile platform

Platform

Notable additions and updates to Flatfile core libraries

SDKs

Notable additions and updates to Flatfile plugins

The Flatfile CLI is a command-line tool that simplifies the integration process with Flatfile by providing developers with commands to manage and configure their integration from their local environment.

flatfile

Listener combines event handling capabilities with Flatfile-specific functionality, such as working with Flatfile records and sessions. Simply put, it receives events and it responds to events.

@flatfile/listener

An SDK wrapper that enables you to seamlessly integrate a secure and user-friendly data import experience into your client-side application

@flatfile/javascript

@flatfile/react

@flatfile/angular

@flatfile/vue

A plugin for parsing an XLSX file and extracting it into Flatfile.

@flatfile/plugin-xlsx-extractor

A plugin for parsing a JSON file and extracting it into Flatfile.

@flatfile/plugin-json-extractor

A plugin for parsing an XML file and extracting it into Flatfile.

@flatfile/plugin-xml-extractor

A plugin for decompressing a zip file and uploading the decompressed files into Flatfile.

@flatfile/plugin-zip-extractor

A plugin for parsing a delimited file and extracting it into Flatfile.

@flatfile/plugin-delimiter-extractor

A plugin for parsing a PDF file and extracting it into Flatfile.

@flatfile/plugin-pdf-extractor

A plugin that exports a function named `recordHook` that sets up an event listener for the `commit:created` event. The purpose of this plugin is to provide a concise syntax for running custom logic on individual data records in Flatfile.

@flatfile/plugin-record-hook

A plugin that automatically converts the initial user-inputted data to the correct type needed for that field so it can be processed.

Getting Started

Core Concepts

Plugins

Advanced Guides

Embedding Flatfile

Reference

V2 GitHub Upgrade Example