SFTP Integration in Clarisights

Clarisights operates a managed SFTP endpoint that you can push files to. Drop CSV files (plain, gzip, or zip compressed) into your designated folder, and Clarisights ingests them on the cadence agreed with your CSM. If you already run your own SFTP server, Clarisights can also pull files from it instead (see Pulling from your own SFTP server).

At a glance

Connector type	File transfer (you push files to a Clarisights-hosted SFTP server)
Authentication	Username + password (default), or SSH key (PPK / OpenSSH)
Permissions needed	Not applicable (credentials are scoped to your folder)
File formats	CSV, CSV.GZ, CSV in a ZIP archive (one file per archive)
Refresh cadence	Set per pipeline (agreed with your CSM)
Limited rollout	No

Authentication options

Two authentication methods are supported. Choose the one that fits your security requirements when you request access.

• Username + password (default): Clarisights generates a username and password for your folder and shares them with you securely.

• SSH key (alternative): if your security policy requires key-based authentication, generate a key pair on your side and share the public key with Clarisights. Keep the private key on the machine that uploads files. Both PPK (PuTTY) and OpenSSH formats are accepted.

Setting up the connection

Step 1: Request SFTP credentials

Contact your Customer Success Manager (CSM) and request an SFTP endpoint. Tell us which authentication method you want to use:

• Username + password (we generate the password), or

• SSH key (you generate the key pair and send us the public key)

Step 2: Receive your connection details

Clarisights provisions your endpoint and shares the connection details (host, port, username, folder path, and password if applicable). For key-based auth, we register your public key against your username.

⚠ Common error: Permission denied → caused by an incorrect username, password, or private key → double-check the credentials we shared, and confirm you're using the matching auth method.

Step 3: Connect with your SFTP client

Use any standard SFTP client (FileZilla, WinSCP, Cyberduck, OpenSSH sftp, or your scripting language of choice) to connect to the host and port we provided. Upload files into the designated folder for each pipeline.

⚠ Common error: Connection refused → caused by the wrong host or port, or a firewall blocking the connection → verify the host and port from the details we shared, and ensure outbound traffic on that port is allowed from your network.

⚠ Common error: File not found / No such file or directory → caused by uploading to the wrong folder → confirm the upload path with your CSM and make sure files land inside the designated folder, not the SFTP root.

Step 4: Files are ingested on the configured cadence

Once files are in the folder, the pipeline picks them up at the next scheduled run. The cadence (for example, hourly or daily) is agreed with your CSM when the pipeline is set up.

Connection details exchange

You provide	Clarisights provides
Preferred authentication method (password or SSH key)	SFTP host
If using SSH key: your public key (PPK or OpenSSH)	Port
Expected file format and naming pattern	Username
Refresh cadence requirement	Password (if using password auth)
	Designated upload folder path

What we read

• File formats supported: CSV, gzip-compressed CSV (.csv.gz), and CSV inside a ZIP archive (.zip, one file per archive). Parquet, Excel, and JSON files are not read from SFTP.

• One file per configured path: Each pipeline reads the file at the path agreed with your CSM on every run. The path can contain wildcards (for example exports/orders_*.csv) and date placeholders such as <year>, <month>, and <day_of_month>. If several files match, the first one in alphabetical order is read, so include the date in the file name or overwrite a single file rather than letting files pile up.

• CSV header convention: The first row of every CSV file must be the column header. Column names in this header become the field names ingested into Clarisights.

Connector specifics

• Consistent file names: When you re-upload an updated file, keep the same file name as agreed in your pipeline configuration. Renaming a file mid-stream can cause it to be treated as a new dataset.

• File names with spaces: If you reference a file by URL elsewhere in Clarisights, replace spaces with %20 (for example, Campaign%20Data.csv).

• Keep the schema stable: Every file a pipeline reads must have the same column headers. Renaming, adding, or removing columns needs a change on the Clarisights side, so tell your CSM before you change the export.

• One folder per dataset: If you have multiple datasets with different schemas, use a separate folder for each. Your CSM will set up one pipeline per folder.

Pulling from your own SFTP server

If your files already land on an SFTP server you operate, Clarisights can connect to it and download the file at an agreed path on each run, instead of you pushing files to us. Share the host, port, username, password, and file path with your CSM through the secure channel they provide. Only username and password login is supported for this option; SSH key login to your server is not.

Limitations & known constraints

• File size: Very large single files can slow down ingestion. If you regularly produce files over a few GB, talk to your CSM about splitting them by date or by partition.

• Retention on the SFTP server: The SFTP server is an ingestion drop zone, not long-term storage. Older files may be cleared periodically. Always keep an authoritative copy on your side.

• One SFTP endpoint per company: Each company gets a single SFTP endpoint. Multiple datasets are organized into separate folders under that endpoint.

Operating notes

• Refresh cadence: Ingestion runs on the schedule agreed with your CSM (commonly hourly or daily). To change the cadence, contact your CSM.

• Credential rotation: To rotate a password or replace an SSH public key, contact your CSM. We'll issue new credentials and confirm when the old ones are revoked.

• Adding a new dataset: To add a new file feed, contact your CSM with the dataset name, expected schema, file format, and cadence. We'll provision a new folder and pipeline against your existing endpoint.

Need help?

When contacting support from the in-app messenger, please include:

• The folder or pipeline name you're uploading to

• The exact error message from your SFTP client (or a screenshot)

• The step where the issue occurred (connect, upload, or ingestion)

• When the issue started and the file name(s) involved