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

# Send and receive files with Integration Designer endpoints

> Configure Integration Designer endpoints to receive files and XML or SOAP responses, and to send files in POST bodies, with runtime behavior and an example.

You can now handle file uploads and downloads with external systems directly within Integration Designer. This update introduces native support for file transfers in RESTful connectors, reducing the need for custom development and complex workarounds.

> [!WARNING]
>
> **Important: Document replacement behavior**
>
> When saving files to the Document Plugin, if you upload a file with the **same `customId` AND `documentType` combination** as an existing document, the previous document will be automatically **marked as deleted** and replaced by the new file.
>
> This means:
>
> * The previous file's URLs will stop working
> * Only the most recent file with that `customId` + `documentType` combination will be accessible
>
> **Best practices:**
>
> * Always use **unique, dynamic values** for `customId` (for example, `${processInstanceId}`, `${clientId}`, `${uuid}`)
> * Never copy examples with hardcoded values like `customId: "1234"` or `documentType: "BULK"` without changing them
> * If you need to store multiple documents of the same type, ensure each has a unique `customId`
>
> ```json Example: Using dynamic customId theme={"dark"}
> {
>   "customId": "${processInstanceId}_${timestamp}",
>   "documentType": "CONTRACT"
> }
> ```

## Core scenarios

Integration Designer supports two primary file handling scenarios:

**1. Downloading Files**

Can call an external API (`GET` or `POST`) and receives a response containing one or more files. Integration Designer saves these files to a specified location and returns their new paths to the workflow for further processing.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fh1.png)

**2. Uploading Files**

Can send a file that is already stored in the **Document Plugin** or a custom **S3 Bucket** to an external API via a `POST` request. The workflow transmits the file path, enabling file transfer without manual handling.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fh2.png)

> [!NOTE]
>
> Common use cases include contract generation workflows where data is sent to external document services and the generated files are retrieved back into the process.

***

## Receiving XML and SOAP responses

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.0**
>
> Earlier releases assumed every response body was JSON — any other format failed the node even on a valid `2xx`. From 5.9.0, the engine honours the content type the endpoint declares and parses XML responses automatically.

REST endpoints can consume **JSON**, **XML** (including **SOAP** envelopes), and **plain text** responses. You don't pick the response format in a dropdown — the engine resolves it from the endpoint's request **Headers**:

1. The **`Accept`** header wins (what the integration expects back).
2. If `Accept` is absent, the request **`Content-Type`** is used as a fallback.
3. If neither is set, the engine runs in **automatic** mode and infers the format from the upstream's response `Content-Type`.
4. Wildcard `Accept` values (`*/*`, `application/*`, `text/*`) are treated as automatic — they don't commit to a format.

Media types are categorised as follows:

| Declared / received type | Parsed as | Resulting body |
| - | - | - |
| `application/json`, `application/hal+json`, anything ending in `+json` | JSON | Object you map with `${...}` paths |
| `application/xml`, `text/xml`, anything ending in `+xml` (e.g. `application/soap+xml`) | XML | Object you map the same way as JSON |
| `text/*` (plain text, HTML) | Text | The raw string |
| Anything else / unset | Automatic | JSON if parseable, otherwise the raw string |

When an XML or SOAP response is parsed, you map its fields exactly like a JSON response (for example `${response.body.Envelope.Body.result}`). The original XML is preserved alongside the parsed object, so flows that need the raw markup can still access it.

> [!WARNING]
>
> The engine fails the node with a clear error when the response does not match what the endpoint declared:
>
> * **Content type mismatch** — declared `application/json` but the upstream returned `text/plain`: `Expected response content type "application/json" but received "text/plain".`
> * **Parse failure on a declared type** — declared XML but the body is malformed: `Response declared as XML but could not be parsed as XML.`
>
> In automatic mode (or when XML was only *inferred* from the upstream's `Content-Type`), a parse failure does **not** fail the node — the raw string is returned instead, so a mislabelled upstream doesn't break the flow.

XML parsing is XXE-safe: external entity resolution and DTD processing are disabled, so XXE and entity-expansion payloads cannot read local files or exhaust memory.

XML bodies larger than 5 MiB are returned as raw strings without parsing.

> [!NOTE]
>
> To **send** a SOAP or XML request body, set the endpoint **Content type** to **Raw** and add the matching `Content-Type` header — see [Defining REST integration endpoints](https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/data-sources-and-endpoints.md#defining-rest-integration-endpoints).

***

## Receiving files (endpoint response configuration)

To configure an endpoint to handle incoming files from an external system, navigate to its **Response** tab. This functionality is available for both `GET` and `POST` methods.

### Enabling and configuring file downloads

**1. Activate File Processing**

Switch the **Save Files** toggle to the "on" position to activate file processing for the response.

> [!WARNING]
>
> If this toggle is **off**, the system doesn't save files. The response body reaches the workflow as a raw string, whether it holds Base64 data or the binary file itself, and the node succeeds. The node fails only when the endpoint's request headers declare an `Accept` type (or, without one, a `Content-Type`) of JSON, XML, or text and the response is a different type. The error reads `Expected response content type "…" but received "…".`

**2. Configure Content-Type**

Select the expected format of the successful API response from the **Content-Type** dropdown:

* `JSON` (Default): For responses containing Base64 encoded file data
* `Single Binary`: For responses where the body is the file itself

### Handling JSON content-type

This option is used when the API returns a JSON object containing one or more Base64 encoded files.

**File Destination Configuration:**

> [tab] Document Plugin
>
> Saves files to the platform's managed storage, linking them to a specific process instance. The Document Plugin acts as a wrapper over the file system and provides special integration capabilities with document templates.
>
> **processInstance** `string` *required*
>
> The ID of the process instance. This field defaults to `${processInstanceId}` to be mapped dynamically at runtime.
>
> > [!TIP]
> >
> > When using Document Plugin for file operations, you typically send only the document reference (ID) rather than the entire file content. The Integration Designer handles the special integration with document templates automatically.
>
> **Files Mapping Table:**
>
> | Column | Description | Example |
> | - | - | - |
> | **Base 64 File Key** | The JSON path to the Base64 encoded string | `files.user.photo` |
> | **File Name Key** | *Optional.* The JSON path to the filename string | `files.photoName` |
> | **Default File Name** | A fallback name to use if the File Name Key is not found | `imagineProfil` |
> | **Default Folder** | The business-context folder, such as a client ID (`CNP`) | `folder_client` |
> | **Default Doc Type** | The document type for classification in the Document Plugin | `Carte Identitate` |

> [tab] S3 Protocol
>
> Saves files to a custom S3 bucket, ideal for files not tied to a specific process instance or when Document Plugin is not available.
>
> This configuration requires the same **Files** table but omits the `Process Instance` and `Default Document Type` fields since S3 storage operates independently of the FlowX document management system.
>
> > [!TIP]
> >
> > Use S3 Protocol when you want to manipulate files at the workflow level for scenarios like AI processing, report generation, or CMS integrations with unassociated documents.

> [!NOTE]
>
> The `Translate or Convert Enumeration Values` toggle can be used in conjunction with the `Save Files` feature.

### Handling Single Binary content-type

This option is used when the entire API response body is the file itself. The Single Binary content-type is ideal for endpoints that return raw file data directly in the response body.

**1. Configure Content-Type**

In the **Response** tab of your endpoint configuration:

1. Enable the **Save Files** toggle
2. Select **Single Binary** from the **Content-Type** dropdown

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fh3.png)

> [!WARNING]
>
> With the **Save Files** toggle off, a binary response isn't saved as a file: the body reaches the workflow as a raw string. Turn **Save Files** on to store the file.

**2. Choose File Destination**

Select your preferred file storage destination:

> [tab] S3 Protocol
>
> For files stored in custom S3 buckets, ideal for files not tied to specific process instances.

> [tab] Document Plugin
>
> For files managed by FlowX's document system, linked to process instances with additional metadata.

**3. Configure File Name Identification**

Choose how the system should identify the filename from the response.

**File Name Identification Methods:**

> [tab] Auto Identify (Recommended)
>
> The system automatically parses the `Content-Disposition` HTTP header to extract the `filename` attribute. This is the standard approach for most file download endpoints.
>
> > [!TIP]
> >
> > **When to use:** When the external API follows standard HTTP conventions and includes file information in the `Content-Disposition` header.
>
> **Example of standard Content-Disposition header:**
>
> ```
> Content-Disposition: attachment; filename="document.pdf"
> ```
>
> The system will automatically extract `document.pdf` as the filename.

> [tab] Manual Configuration
>
> Configure custom header parsing when the external system doesn't follow standard conventions or uses custom headers for file information.
>
> **1. Disable Auto Identify**
>
> Turn off the **Auto Identify File** toggle to enable manual configuration options.
>
> **2. Configure Header Fields**
>
> **File Name Header Key** `string` *required*
>
> The name of the HTTP header that contains the filename information.
>
> **Examples:**
>
> * `X-Dctm-Object-Name`
> * `X-File-Name`
> * `Custom-Filename-Header`
>
> **File Name Header Attribute** `string` *required*
>
> The specific attribute or value within the header to extract as the filename.
>
> **Examples:**
>
> * For simple headers: leave empty or use the full header value
> * For complex headers: specify the attribute name
>
> **3. Apply Custom Regex (Optional)**
>
> Enable the **Apply Custom Regex** toggle when you need to extract the filename using pattern matching.
>
> > [!NOTE]
> >
> > **When to use regex:** When the filename is embedded within a larger header value and needs to be extracted using pattern matching.
> >
> > **Example scenarios:**
> >
> > * Header value: `filename=document.pdf; size=1024`
> > * Regex pattern: `filename=([^;]+)`
> > * Extracted result: `document.pdf`
>
> **Common regex patterns:**
>
> ```regex theme={"dark"}
> # Extract filename from "filename=document.pdf"
> filename=(.+)
>
> # Extract filename with extension from complex header
> ([a-zA-Z0-9_-]+\.[a-zA-Z]{2,4})
>
> # Extract quoted filename: filename="my document.pdf"
> filename="([^"]+)"
> ```
>
> > [!TIP]
> >
> > Use manual configuration when working with legacy systems, custom APIs, or when the external server provides file information through non-standard headers.

**File Destination Configuration:**

> [tab] Document Plugin
>
> For files managed within FlowX's document system with full process integration:
>
> **Default File Name** `string` *required*
>
> Fallback filename if header extraction fails
>
> **Default Folder** `string` *required*
>
> Business context folder (e.g., client ID, case number)
>
> **Default Document Type** `string` *required*
>
> Document classification for the Document Plugin
>
> > [!NOTE]
> >
> > Files stored via Document Plugin are automatically linked to process instances and can be used with document templates and other FlowX document features.

> [tab] S3 Protocol
>
> For files stored in custom S3 buckets with flexible storage options:
>
> **Default File Name** `string` *required*
>
> Fallback filename if header extraction fails
>
> **Default Folder** `string`
>
> Optional folder structure within the S3 bucket
>
> > [!TIP]
> >
> > S3 Protocol storage is ideal for files that need to be processed by external systems, used in AI workflows, or when Document Plugin is not available.

**Configuration Examples:**

```json Auto Identify Example theme={"dark"}
{
  "contentType": "Single Binary",
  "saveFiles": true,
  "autoIdentifyFile": true,
  "fileDestination": "S3 Protocol",
  "defaultFileName": "downloaded_file",
  "defaultFolder": "client_${clientId}"
}
```

```json Manual Configuration Example theme={"dark"}
{
  "contentType": "Single Binary", 
  "saveFiles": true,
  "autoIdentifyFile": false,
  "fileNameHeaderKey": "X-Document-Name",
  "fileNameHeaderAttribute": "filename",
  "applyCustomRegex": true,
  "customRegex": "filename=\"([^\"]+)\"",
  "fileDestination": "Document Plugin",
  "defaultFileName": "fallback_document",
  "defaultFolder": "documents",
  "defaultDocumentType": "Contract",
}
```

***

## Sending files (endpoint POST body configuration)

To configure an endpoint to send a file, navigate to the **Body** tab and select the appropriate **Content Type**.

### Content Type: Multipart/Form-data

Use this to send files and text fields in a single request. This format is flexible and can handle mixed content types within the same POST request.

**1. Configure File Source**

Select where the file originates:

* `Document Plugin`
* `S3 Protocol`

**2. Define Form Parts**

Add rows to the resource table, defining each part of the form:

* **Key Type**: Choose `File` or `Text`
* **Value**:
  * For files: Provide the `filePath` (Minio path for S3 or Document Plugin reference)
  * For text: Provide the string value or variable reference

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fh4.png)

> [!NOTE]
>
> Multipart requests can be sent even without files - you can include only text fields by setting all Key Types to `Text`. The difference between content types is primarily in how data is packaged for transmission to the target server.

### Content Type: Single binary

Use this to send the raw file as the entire request body. This method sends only the file content without any additional form data or metadata.

**fileSource** `string` *required*

Select `Document Plugin` or `S3 Protocol`

**filePath** `string` *required*

Specify the path of the file to be sent (Minio path for the file location)

> [!TIP]
>
> When using Single Binary, only the Minio path is required since the entire request body will be the file content itself, without any additional packaging or metadata.

### Content Type: JSON

Use this option for standard JSON payloads. To send a file as the whole request body or as a form part, use `Single Binary` or `Multipart/Form-Data`.

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.6**
>
> A JSON body can carry a file from the Document Plugin as a base64 string. In 5.9.5 and earlier, a JSON body cannot carry a file: use `Multipart/Form-Data` or `Single Binary`.

To embed a file, set a string value in the JSON body to `@@base64File(<path>)`, where `<path>` is the file's path in the Document Plugin. When the node runs, the marker is replaced with the file content encoded as base64:

```json theme={"dark"}
{
  "documentName": "contract.pdf",
  "content": "@@base64File(${filePath})"
}
```

* The path can come from a workflow variable, such as `${filePath}` from an earlier node. Variables are resolved before the marker is read.
* Only string values are replaced. A marker used as a JSON key is left as it is.
* The file content is added only to the request that is sent. The saved request body and the generated curl command keep the marker.
* Downloading the file from the Document Plugin is cancelled after 5 minutes by default. On self-hosted deployments, change the limit with `FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT` (see the [Integration Designer setup guide](https://docs.flowx.ai/5.9/setup-guides/integration-designer-setup.md#service-communication)).

***

## Runtime behavior & testing

### Workflow node configuration

All configured file settings (for example, `File Path`, `Folder`, `Process Instance ID`) are exposed as parameters on the corresponding workflow nodes, allowing them to be set dynamically using process variables at runtime.

### Response payload & logging

> [!TIP]
>
> When a node successfully downloads and saves a file, its output will contain the **`filePath`** to the stored file, **not** the raw Base64 string or binary content.

> [!NOTE]
>
> For security and performance, runtime logs will also only contain the `filePath`, not the raw file content.

### Error handling

If a node is configured to receive a `Single Binary` file but the external system returns a `JSON` error (for example, file not found), the JSON error will be correctly passed through to the workflow for handling.

If **Save Files** is on with the `JSON` content type (Base64 files) and the external system returns a success status (2xx) with a response that isn't JSON or XML, the node fails with `Unsupported content type "text/html". Make sure system is configured correctly.` (the message names the content type actually received). The external system's response causes this error, not the endpoint configuration.

**Error status (non-2xx), starting with FlowX.AI 5.9.6:** the node keeps the response body as text, with its status code, for both `JSON` (Base64 files) and `Single Binary`. Nothing is saved as a file, and the error response isn't stored in the endpoint response cache. The status code then drives the node: with **Allow Retry** on, a `408`, `429`, `500`, `502`, `503`, or `504` is retried, and once retries are done the node completes with the error status, so a failure path on the node can handle it. For example, an HTML `504 Gateway Timeout` page from a gateway or proxy is now retried instead of failing the workflow.

**Error status on 5.9.5 and earlier:** with `JSON` (Base64 files), an HTML error page fails the node, for example `Content type 'text/html' not supported for bodyType=com.fasterxml.jackson.databind.JsonNode`. Changing the request `Accept` header doesn't help, because the upstream gateway decides the response format. To avoid the gateway's error page, set the node's **Timeout** on its **Settings** tab (default `10000` ms) lower than the gateway's timeout. The node then stops waiting before the gateway responds and returns a `408` status, which is retried when **Allow Retry** is on. Switching the response to `Single Binary` doesn't avoid the problem on these versions: Single Binary doesn't check the status code, so an HTML error page is saved as a file.

### Testing guidelines

> [!TIP]
>
> The **Test Modal** is context-aware. It will only display input fields for file parameters (`Process Instance ID`, `Folder`, etc.) if `Save Files` is enabled on the endpoint.

> [!WARNING]
>
> If you test an endpoint that returns a binary file without configuring it as `Single Binary`, the test will fail with the error: "*Endpoint returns a binary file. Please configure the Content-Type to handle binary responses.*"

> [!NOTE]
>
> The **Response Example** tab is now separate from the **Response** configuration tab and includes both `Body` and `Headers` sections for better clarity.

## Example: sending files to an external system after uploading a file to the Document Plugin

> [!NOTE]
>
> In this example, we'll send a file to an external system using the  Integration Designer.

**1. Upload a file to the Document Plugin**

Configure a process where you will upload a file to the Document Plugin.

* Configure a User Task node where you will upload the file to the Document Plugin.
* Configure an Upload File Action node to upload the file to the Document Plugin.
* Configure a Save Data Action node to save the file to the Document Plugin.

**2. Configure the Integration Designer**

Configure the Integration Designer to send the file to an external system:

* Configure a REST API Call node to send the file to an external system.


## Related topics

- [Integration Designer](https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/integration-designer.md)
- [Data sources and endpoints in Integration Designer](https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/data-sources-and-endpoints.md)
- [Multiple file upload](https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload.md)
- [FlowX.AI 5.1.0 Release Notes](https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/v5.1.0-october-2025.md)
- [File Storage](https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/file-storage.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.