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:

name,email,rating
Alice Johnson,[e-mail],5
Bob Smith,[e-mail],3
Carol White,[e-mail],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.

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:

{ "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.

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.

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:

{
  "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:

{
  "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 and Filter Workflow guides for complete end-to-end examples that build on this upload step.

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.