# sFTP

### Overview

With the SFTP connector, Birdie can import data from files placed on your SFTP server. Once a day Birdie connects to the configured server, reads any new files from the agreed directory, and ingests the records into Birdie.

This is a good fit when you can't (or don't want to) expose a database or API directly to Birdie, but already have a process that drops files onto an SFTP server.

### Requirements

* An SFTP server that Birdie can reach over the public internet.
* A dedicated **user and directory** for Birdie's reads.
* **Key-pair authentication** (recommended) or password authentication.
* Agreement on **file format and schema** for each record kind that will be sent ([see Schema requirements](#schema-requirements)).

{% hint style="info" %}
**Why key-pair authentication is recommended**

Birdie owns and rotates the key pair internally. Only the public key leaves Birdie. The client never handles secrets that need rotation, and Birdie can revoke a key without changing anything on the client side beyond removing one line from `authorized_keys`.
{% endhint %}

#### Step 1 — Create a dedicated user and directory

On your SFTP server, create a user that Birdie will use, and a directory where the files Birdie should read will be placed:

```
/home/birdie/import/
```

The user only needs **read access** to this directory. Write access is not required for ingestion.

#### Step 2 — Install Birdie's public key

Birdie shares the public half of an internal key pair with you over a secure channel. Install it on the dedicated user's `~/.ssh/authorized_keys` file:

```bash
mkdir -p /home/birdie/.ssh
echo "<birdie-public-key>" >> /home/birdie/.ssh/authorized_keys
chmod 700 /home/birdie/.ssh
chmod 600 /home/birdie/.ssh/authorized_keys
chown -R birdie:birdie /home/birdie/.ssh
```

The private half stays inside Birdie's infrastructure and is never shared.

If you can't use key-pair authentication for any reason, Birdie also supports password authentication — share the password with Birdie over a secure channel instead of the public-key step.

#### Step 3 — (Optional) Share your server's host key

To prevent man-in-the-middle attacks, Birdie can validate your server's host key on every connection. Capture the server's public host key and share it with Birdie:

```bash
ssh-keyscan -t rsa <your-sftp-host> 2>/dev/null
```

If a host key is not provided, Birdie will still connect but won't validate the server identity beyond the SSH protocol defaults.

#### Step 4 — Agree on file format and schema <a href="#schema-requirements" id="schema-requirements"></a>

Birdie's SFTP connector reads structured files (CSV is the most common; Parquet is also supported for some flows). Before the integration is enabled, you and Birdie will agree on:

* **Record kind** — what type of feedback or entity each file represents (e.g., `support_ticket`, `csat`, `review`).
* **File format** — typically `csv`; alternative formats can be discussed.
* **Separator** (CSV only) — defaults to `,`; configurable per integration.
* **Schema** — the columns each file must contain. Birdie provides the schema reference for each record kind separately, following the same model as the [data ingestion schema documentation](https://ask.birdie.ai/integrations-and-data-ingestion/data-schema-definitions-for-birdie-ingestion).
* **Path convention** — files can live directly under the configured directory, or under subfolders by kind / source. Birdie's team will agree the layout with you during setup.

#### Step 5 — Share connection details with Birdie

Once the user, directory, and public key are in place, securely provide Birdie with the following information:

```json
{
  "connection_details": {
    "address": "sftp.example.com",
    "port": "22",
    "username": "birdie",
    "server_public_key": "ssh-rsa AAAA..."
  },
  "data_source": {
    "path": "import/",
    "format": "csv",
    "separator": ",",
    "kind": "support_ticket"
  }
}
```

| Section              | Field               | Required | Description                                                                                        |
| -------------------- | ------------------- | -------- | -------------------------------------------------------------------------------------------------- |
| `connection_details` | `address`           | Yes      | Hostname or IP address of your SFTP server.                                                        |
| `connection_details` | `port`              | Yes      | Port for the SFTP connection. Typically `22`.                                                      |
| `connection_details` | `username`          | Yes      | The dedicated user created in Step 1.                                                              |
| `connection_details` | `server_public_key` | No       | The server's RSA public host key captured in Step 3. Required when host-key validation is enabled. |
| `connection_details` | `password`          | No       | Only required when using password authentication instead of key-pair.                              |
| `data_source`        | `path`              | Yes      | Directory on the SFTP server where files will be placed (configured in Step 1).                    |
| `data_source`        | `format`            | Yes      | File format. Typically `csv`; `parquet` is also supported for some flows.                          |
| `data_source`        | `separator`         | No       | CSV column separator. Defaults to `,`.                                                             |
| `data_source`        | `kind`              | Yes      | Record kind agreed with Birdie in Step 4 (e.g., `support_ticket`, `csat`, `review`).               |

[Share credentials securely](https://ask.birdie.ai/integrations-and-data-ingestion/securely-sharing-credentials-for-data-integration) with the Birdie team. Never send credentials via email or unencrypted channels.

### How the Import Works

1. Once a day, Birdie's SFTP connector connects to your server using the configured credentials.
2. It lists files in the configured path that fall within the import window (based on file metadata).
3. For each file, Birdie parses records according to the agreed format and schema, and ingests them into Birdie.
4. Files are not deleted or modified on your server — Birdie only reads.

If a file is added after the daily run, it will be picked up on the next run.

### References

* [Data Schema Definitions for Birdie Ingestion](https://ask.birdie.ai/integrations-and-data-ingestion/data-schema-definitions-for-birdie-ingestion)
* [Securely sharing credentials for Data Integration](https://ask.birdie.ai/integrations-and-data-ingestion/securely-sharing-credentials-for-data-integration)
* [OpenSSH server configuration](https://man.openbsd.org/sshd_config)
* [SSH `authorized_keys` format](https://man.openbsd.org/sshd#AUTHORIZED_KEYS_FILE_FORMAT)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ask.birdie.ai/integrations-and-data-ingestion/how-to-integrate-with/sftp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.