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

# FTP Read Connector

> You can perform file search, reading, and content retrieval in different formats using FTP connection definitions. You can search files from your servers or different environments according to specific criteria, read their contents with various output formats, and create API Proxies that perform these operations and return results.

<img src="https://mintcdn.com/apinizer/-OUVpYz7x56LFQ3F/images/yonetici/konnektor/ftp-read.png?fit=max&auto=format&n=-OUVpYz7x56LFQ3F&q=85&s=ac663330850940a0754f57c855abe9d5" alt="FTP Read Connector Configuration" width="800" className="mr-auto" data-path="images/yonetici/konnektor/ftp-read.png" />

<CardGroup cols={3}>
  <Card title="File Access" icon="file">
    You can access file contents on your FTP servers or different environments.
  </Card>

  <Card title="File Search" icon="magnifying-glass">
    You can search files according to specific criteria and patterns.
  </Card>

  <Card title="Format Conversion" icon="arrows-rotate">
    You can download file contents in different formats (JSON, ZIP, MTOM).
  </Card>
</CardGroup>

## Usage

<Info>
  The FTP file read connector you create allows you to perform file reading operations from FTP server. This connector provides flexible search criteria such as searching by file name patterns, wildcard matching, and exact match, along with the ability to produce output in various formats, allowing you to develop solutions suitable for your needs.
</Info>

The connector accepts HTTP POST request with JSON body. If request body is sent empty, default values are used.

## HTTP Request

```bash theme={null}
curl --location --request POST "https://<APINIZER_ACCESS_URL>/<RELATIVE_PATH>" \
  -H "Content-Type: application/json" \
  --data-raw '{"searchType": "WILDCARD", "searchPattern": "*.json", "returnType": "ALL_MATCHES", "outputFormat": "JSON_BASE64"}'
```

## Request Body Parameters

<AccordionGroup>
  <Accordion title="File Search Settings">
    <CardGroup cols={2}>
      <Card title="searchType" icon="magnifying-glass">
        **Type:** string

        **Default Value:** STARTS\_WITH

        **Description:** Specifies how file names will be searched. Available options:

        * **STARTS\_WITH**: Checks if file name starts with the given pattern
        * **EXACT\_MATCH**: Checks for exact match with the given file name
        * **CONTAINS**: Checks if file name contains the given pattern
        * **ENDS\_WITH**: Checks if file name ends with the given pattern
        * **WILDCARD**: Uses wildcard pattern matching (\* matches any sequence, ? matches single character)
      </Card>

      <Card title="searchPattern" icon="filter">
        **Type:** string

        **Default Value:** (empty - returns all files)

        **Description:** File name or pattern to search for. Usage depends on searchType:

        * For WILDCARD: `*.json`, `file?.txt`, `invoice_*.pdf`
        * For ENDS\_WITH: `.json`, `.pdf`, `.xml`
        * For STARTS\_WITH: `invoice_`, `report`, `data`
        * For CONTAINS: `2025`, `test`, `_backup`
        * For EXACT\_MATCH: `report.pdf`, `config.json`
      </Card>

      <Card title="caseInsensitive" icon="font">
        **Type:** boolean

        **Default Value:** true

        **Description:** Determines whether file name search is case-sensitive. When set to true, "File.txt" and "file.txt" are treated as the same.
      </Card>

      <Card title="returnType" icon="list">
        **Type:** string

        **Default Value:** ALL\_MATCHES

        **Description:** Specifies the amount of results to return:

        * **FIRST\_MATCH**: Downloads only the first matching file and stops searching. Useful when you need just one file quickly.
        * **ALL\_MATCHES**: Downloads all matching files. Use this when you need to process multiple files.
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="File Size Limitation">
    <Card title="maxFileSizeKB" icon="gauge">
      **Type:** integer

      **Default Value:** (no limit)

      **Description:** Maximum file size in kilobytes (KB) to download. Files larger than this size are skipped and not included in the response.

      **Example:** Setting it to `10240` means only files up to 10 MB (10240 KB) will be downloaded.

      **Use Case:** Prevent downloading very large files that could cause memory or performance issues.
    </Card>
  </Accordion>

  <Accordion title="Output Format Settings">
    <Card title="outputFormat" icon="file-code">
      **Type:** string

      **Default Value:** JSON\_BASE64

      **Description:** Specifies the format in which file contents will be returned:

      * **JSON\_BASE64**: File contents are returned in JSON format with Base64 encoding. Best for API integrations and when you need structured response.
      * **MTOM**: Files are returned in MTOM (Message Transmission Optimization Mechanism) format as multipart SOAP message. Useful for SOAP-based integrations.
      * **ZIP**: All matching files are packaged into a single ZIP archive. Best for downloading multiple files or large files efficiently.

      <Warning>
        When using **MTOM** or **ZIP** format, if no files are found, the response returns HTTP 404 status code with error message. Only JSON\_BASE64 format returns HTTP 200 with empty files array.
      </Warning>
    </Card>
  </Accordion>
</AccordionGroup>

## Response Format

Response format varies based on the `outputFormat` parameter:

### JSON\_BASE64 Format (Default)

**Successful Response:**

```json theme={null}
{
  "count": 2,
  "files": [
    {
      "name": "invoice_2025_001.pdf",
      "data": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL...",
      "size": 245760
    },
    {
      "name": "invoice_2025_002.pdf",
      "data": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL...",
      "size": 198432
    }
  ]
}
```

**Empty Response (No Files Found):**

```json theme={null}
{
  "count": 0,
  "message": "No files found",
  "files": []
}
```

<Info>
  In JSON\_BASE64 format, the `data` field contains the Base64 encoded file content. You need to decode this data to access the actual file content.
</Info>

### ZIP Format

When `outputFormat` is set to `ZIP`, all matching files are packaged into a single ZIP archive and returned as binary data.

**Headers:**

* `Content-Type`: application/zip
* `Content-Disposition`: attachment; filename="ftp\_files.zip"

**Response:** Binary ZIP file data

<Warning>
  If no files are found, returns HTTP 404 status code with error message: "No files found"
</Warning>

### MTOM Format

When `outputFormat` is set to `MTOM`, files are returned as multipart SOAP message in MTOM format.

**Headers:**

* `Content-Type`: multipart/related; boundary=...; type="application/xop+xml"

**Response:** Multipart MTOM message with file attachments

<Warning>
  If no files are found, returns HTTP 404 status code with error message: "No files found"
</Warning>

## Example Scenarios

### Example 1: JSON Format - First Match

**Usage Scenario**: Find the first file starting with "invoice\_2025\_" and return in JSON format. Accept files up to 10 MB in size.

**Request:**

```json theme={null}
{
  "caseInsensitive": true,
  "searchType": "STARTS_WITH",
  "searchPattern": "invoice_2025_",
  "returnType": "FIRST_MATCH",
  "maxFileSizeKB": 10240,
  "outputFormat": "JSON_BASE64"
}
```

**Response:**

```json theme={null}
{
  "count": 1,
  "files": [
    {
      "name": "invoice_2025_001.pdf",
      "data": "JVBERi0xLjQKJeLjz9MK...",
      "size": 245760
    }
  ]
}
```

### Example 2: ZIP - All Matches

**Usage Scenario**: Find all PDF files and download as ZIP archive.

**Request:**

```json theme={null}
{
  "caseInsensitive": false,
  "searchType": "ENDS_WITH",
  "searchPattern": ".pdf",
  "returnType": "ALL_MATCHES",
  "outputFormat": "ZIP"
}
```

**Response:** Binary ZIP file containing all matching PDF files.

### Example 3: MTOM Format

**Usage Scenario**: Find the file named "payload.xml" with exact match and return in MTOM format for SOAP integration.

**Request:**

```json theme={null}
{
  "searchType": "EXACT_MATCH",
  "searchPattern": "payload.xml",
  "returnType": "FIRST_MATCH",
  "outputFormat": "MTOM"
}
```

**Response:** Multipart MTOM message with the file attached.

### Example 4: Wildcard Pattern - All JSON Files

**Usage Scenario**: Find all JSON files in the directory using wildcard pattern.

**Request:**

```json theme={null}
{
  "searchType": "WILDCARD",
  "searchPattern": "*.json",
  "returnType": "ALL_MATCHES",
  "outputFormat": "JSON_BASE64"
}
```

This will match files like `config.json`, `data.json`, `report.json`

### Example 5: Complex Wildcard Pattern

**Usage Scenario**: Find files matching specific pattern with single character wildcard.

**Request:**

```json theme={null}
{
  "searchType": "WILDCARD",
  "searchPattern": "report_2025_0?.pdf",
  "caseInsensitive": true
}
```

This will match files like:

* ✅ `report_2025_01.pdf`
* ✅ `report_2025_09.pdf`
* ❌ `report_2025_10.pdf` (two digits after 0)
* ❌ `report_2024_01.pdf` (different year)

### Example 6: Files Containing Specific Text

**Usage Scenario**: Find all files containing "backup" in their name.

**Request:**

```json theme={null}
{
  "searchType": "CONTAINS",
  "searchPattern": "backup",
  "caseInsensitive": true,
  "maxFileSizeKB": 50000
}
```

This will match files like `daily_backup.zip`, `backup_2025.tar.gz`, `db_backup_full.sql`

### Example 7: Case Sensitive Search

**Usage Scenario**: Find files with exact case matching.

**Request:**

```json theme={null}
{
  "searchType": "STARTS_WITH",
  "searchPattern": "Report",
  "caseInsensitive": false
}
```

This will match:

* ✅ `Report_2025.pdf`
* ❌ `report_2025.pdf` (lowercase 'r')
* ❌ `REPORT_2025.pdf` (all uppercase)

## Error Handling

### JSON\_BASE64 Format

Always returns HTTP 200 status code. When no files are found:

```json theme={null}
{
  "count": 0,
  "message": "No files found",
  "files": []
}
```

### ZIP and MTOM Formats

Return HTTP 404 status code when no files are found:

**Status Code:** 404 Not Found

**Response Body:** "No files found"

## Best Practices

<CardGroup cols={2}>
  <Card title="Use maxFileSizeKB" icon="shield">
    Always set a reasonable `maxFileSizeKB` limit to prevent downloading very large files that could cause memory issues.
  </Card>

  <Card title="Choose Right Format" icon="file-code">
    * Use **JSON\_BASE64** for API integrations and when you need structured response
    * Use **ZIP** when downloading multiple or large files
    * Use **MTOM** only for SOAP-based integrations
  </Card>

  <Card title="Use FIRST_MATCH" icon="gauge-high">
    When you only need one file, use `returnType: "FIRST_MATCH"` to improve performance by stopping search after first match.
  </Card>

  <Card title="Wildcard Patterns" icon="wand-magic-sparkles">
    * `*` matches zero or more characters
    * `?` matches exactly one character
    * Combine them for complex patterns: `file_*.???` matches `file_data.txt`, `file_test.pdf`
  </Card>
</CardGroup>