---
canonical_url: "https://docs.composio.dev/toolkits/flatfile"
markdown_url: "https://docs.composio.dev/toolkits/flatfile.md"
product: "platform"
version: null
last_updated: null
---

# Flatfile

Flatfile is a data exchange platform for collecting, validating, transforming, and managing structured data across collaborative workflows.

- **Category:** developer tools
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 12
- **Triggers:** 0
- **Slug:** `FLATFILE`
- **Version:** 00000000_00

## Tools

### Delete Records

**Slug:** `FLATFILE_DELETE_RECORDS`

Permanently delete one to 100 explicitly identified records from one Flatfile sheet. This action never performs an unfiltered delete. Flatfile hooks are disabled, so these deletions do not trigger hook-driven workflows.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sheet_id` | string | Yes | ID of the sheet containing the records. |
| `record_ids` | array | Yes | One to 100 exact record IDs to permanently delete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Job

**Slug:** `FLATFILE_GET_JOB`

Get detailed status, outcome, result, and diagnostic information for one Flatfile asynchronous job.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `job_id` | string | Yes | ID of the Flatfile job to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Sheet

**Slug:** `FLATFILE_GET_SHEET`

Get one sheet's field configuration and record counts before reading or writing records.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sheet_id` | string | Yes | ID of the Flatfile sheet to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Space

**Slug:** `FLATFILE_GET_SPACE`

Get safe metadata for one Flatfile space without exposing transient access credentials or token-bearing guest links.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `space_id` | string | Yes | ID of the Flatfile space to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Insert Records

**Slug:** `FLATFILE_INSERT_RECORDS`

Insert one or more rows into a Flatfile sheet using simple field-key to value objects. Returns Flatfile's success receipt and commit ID, not created record IDs. Use List Records separately when later work requires IDs; only attribute matches that are unambiguous for caller-controlled unique values. Hooks are disabled for this mutation.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `records` | array | Yes | Rows to insert, keyed by sheet field key. Each value may be a string, number, boolean, ISO date or date-time string, or string array. |
| `sheet_id` | string | Yes | ID of the destination sheet. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Environments

**Slug:** `FLATFILE_LIST_ENVIRONMENTS`

List Flatfile environments visible to the connected environment secret key and return the IDs needed to find spaces.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cursor` | string | No | Continuation cursor from a previous response; omit for the first page. |
| `page_size` | integer | No | Maximum environments to return in this page. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Files

**Slug:** `FLATFILE_LIST_FILES`

Discover import or export files and their processing status, optionally within a Flatfile space.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mode` | string ("import" | "export") | No | Storage mode of files to discover. |
| `cursor` | string | No | Continuation cursor from a previous response; omit for the first page. |
| `space_id` | string | No | Only return files in this space. |
| `page_size` | integer | No | Maximum files to return in this page. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Jobs

**Slug:** `FLATFILE_LIST_JOBS`

Find asynchronous Flatfile jobs by environment, space, workbook, file, or parent job and inspect progress at a glance.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cursor` | string | No | Continuation cursor from a previous response; omit for the first page. |
| `source` | string | No | ID of the file, workbook, sheet, or app that originated the job; prefer the corresponding typed ID filter when available. |
| `file_id` | string | No | Only return jobs for this file. |
| `space_id` | string | No | Only return jobs in this space. |
| `page_size` | integer | No | Maximum jobs to return in this page. |
| `workbook_id` | string | No | Only return jobs for this workbook. |
| `parent_job_id` | string | No | Only return child jobs of this parent job. |
| `environment_id` | string | No | Only return jobs in this environment. |
| `sort_direction` | string ("asc" | "desc") | No | Sort jobs in ascending or descending order. |
| `exclude_child_jobs` | boolean | No | Return only top-level jobs unless a parent job is specified. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Records

**Slug:** `FLATFILE_LIST_RECORDS`

Read one page of records from a Flatfile sheet, optionally filtering by validity, field, record ID, search value, or FFQL expression.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | No | Flatfile FFQL expression for advanced filtering. |
| `cursor` | string | No | Continuation cursor returned by an earlier call. Omit for the first page. |
| `fields` | array | No | Field keys to include; omit to return all fields. |
| `filter` | string ("valid" | "error" | "all" | "none") | No | Validity filter: valid, error, all, or none. |
| `sheet_id` | string | Yes | ID of the sheet whose records should be read. |
| `page_size` | integer | No | Maximum records to return in this page. Use moderate page sizes. |
| `record_ids` | array | No | Up to 100 record IDs to include for unfiltered reads or exclude when another filter is active. |
| `filter_field` | string | No | Field key used with the validity filter. |
| `search_field` | string | No | Field key to restrict the search. |
| `search_value` | string | No | Value to search for in records. |
| `include_links` | boolean | No | Whether cell values should include linked records. |
| `include_messages` | boolean | No | Whether cells should include validation messages. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Spaces

**Slug:** `FLATFILE_LIST_SPACES`

Find Flatfile spaces by environment, text, namespace, archive state, or template status.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cursor` | string | No | Continuation cursor from a previous response. Omit for the first page. |
| `search` | string | No | Search space names and supported text fields. |
| `archived` | boolean | No | Whether archived spaces should be included. |
| `namespace` | string | No | Only return spaces with this namespace. |
| `page_size` | integer | No | Maximum spaces to return in this page. |
| `environment_id` | string | No | Only return spaces in this environment. |
| `is_app_template` | boolean | No | Filter by whether the space is an app template. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Workbooks

**Slug:** `FLATFILE_LIST_WORKBOOKS`

List workbooks, optionally within a space, with their nested sheets so an agent can continue to sheet and record tasks.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Filter by workbook name; prefix with '-' for provider-supported negation. |
| `label` | string | No | Filter by workbook label; prefix with '-' for negation. |
| `space_id` | string | No | Only return workbooks belonging to this space. |
| `namespace` | string | No | Filter by workbook namespace; prefix with '-' for negation. |
| `include_sheets` | boolean | No | Include nested sheet IDs and schemas in each workbook. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Records

**Slug:** `FLATFILE_UPDATE_RECORDS`

Update one or more existing Flatfile records by ID using simple field-key to value objects. Flatfile hooks are disabled, so these updates do not trigger hook-driven workflows.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `records` | array | Yes | One or more record updates, each with a required record ID and values. |
| `sheet_id` | string | Yes | ID of the sheet containing the records. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |