> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowmaticai.in/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Upload CSV Data for Use in Flowmatic Workflows

> Learn how to upload a CSV file to Flowmatic, get an uploadId, and reference it as a DATA_SOURCE node in your automation workflows.

Before you can build a workflow that processes rows of customer data, product records, or any other tabular information, you need to upload that data to Flowmatic. The upload endpoint accepts a CSV file and returns an `uploadId` — a stable reference you embed in a `DATA_SOURCE` node so the workflow engine knows exactly which dataset to load at runtime.

## Why upload data first?

Flowmatic workflows are defined as graphs where each node transforms or acts on data. The `DATA_SOURCE` node is the bridge between your raw CSV file and the rest of the graph. Rather than embedding data inline in the workflow definition, you upload the file once and reference its `uploadId` as many times as you like across any number of workflows. This keeps your workflow definitions lightweight and lets you swap datasets by re-uploading a new file without touching the graph itself.

## CSV format requirements

Flowmatic expects your CSV to follow a few straightforward conventions:

* **The first row must be a header row.** Each column header becomes a field name you can reference in template expressions later (for example, `{{item.email}}` or `{{item.rating}}`).
* **Values may be plain text or numbers.** The engine preserves the raw string value of each cell; numeric comparisons in FILTER nodes handle coercion automatically.
* **UTF-8 encoding is required.** Files exported from Excel, Google Sheets, or any standard spreadsheet application are typically UTF-8 by default.
* **There is no enforced row limit**, but very large files may increase run duration. For best performance, pre-filter your CSV to the relevant subset before uploading.

Here is an example CSV you can use to follow along with the guides on this site:

```csv theme={null}
name,email,rating
Alice Johnson,alice@example.com,5
Bob Smith,bob@example.com,3
Carol White,carol@example.com,5
```

The three columns — `name`, `email`, and `rating` — will be accessible in downstream nodes as `item.name`, `item.email`, and `item.rating` respectively once the workflow iterates over rows.

## Uploading a file

The upload endpoint accepts a `multipart/form-data` request with a single field named `file`. You must include a valid bearer token in the `Authorization` header.

```bash theme={null}
curl -X POST https://api.flowmatic.io/api/uploads \
  -H "Authorization: Bearer <accessToken>" \
  -F "file=@customers.csv"
```

Replace `<accessToken>` with the token you received from `POST /api/auth/login`, and `customers.csv` with the path to your local file. The `-F` flag tells curl to send the request as multipart form data and attach the file contents.

### Response

On success, the API returns HTTP `200` with a JSON body containing a single field:

```json theme={null}
{ "uploadId": "upload_abc123xyz" }
```

The `uploadId` is a unique, immutable identifier for the file you just uploaded. Store it somewhere convenient — you will need it when defining your workflow graph in the next step.

<Note>
  Upload IDs do not expire during normal use. If you upload the same file again, a new `uploadId` is issued for the new upload. Old IDs remain valid and continue to point to their original data.
</Note>

## Using `uploadId` in a DATA\_SOURCE node

Once you have an `uploadId`, you reference it inside the `data` object of any `DATA_SOURCE` node in your workflow graph. The node has the following shape:

```json theme={null}
{
  "id": "ds",
  "type": "DATA_SOURCE",
  "data": {
    "uploadId": "upload_abc123xyz"
  }
}
```

At runtime, the engine fetches the uploaded CSV, parses it row by row, and emits the full array of row objects as `ds.rows` (where `ds` is the node's `id`). Downstream nodes — such as an `AI` node or a `FILTER` node — receive this array and can process it accordingly.

### Template variable

After a `DATA_SOURCE` node runs, you reference its output in downstream node configurations using the template syntax `{{nodeId.rows}}`. For example, if your node `id` is `"ds"`, use:

```
{{ds.rows}}
```

This expression resolves to the full array of parsed CSV rows and is the value you pass to an `AI` node's prompt or a `FILTER` node's `source` field.

## Full upload-to-node example

The workflow snippet below shows how a freshly uploaded `uploadId` slots into a minimal two-node graph fragment:

```json theme={null}
{
  "nodes": [
    {
      "id": "ds",
      "type": "DATA_SOURCE",
      "data": {
        "uploadId": "upload_abc123xyz"
      }
    }
  ]
}
```

From here you can connect this node to an `AI` node, a `FILTER` node, or any other node that accepts a rows array. See the [AI Workflow](/guides/build-ai-workflow) and [Filter Workflow](/guides/build-filter-workflow) guides for complete end-to-end examples that build on this upload step.

<Tip>
  Keep a note of your `uploadId` values alongside a short description of the dataset they represent. Flowmatic does not currently expose a file-listing endpoint, so tracking IDs externally (in a notes file or environment variable) saves time when building new workflows.
</Tip>