Setup Guide

Karana Data Courier connects HubSpot to any SFTP server for scheduled, bi-directional data exchange — exports of CRM records to your server, and imports of files from your server into HubSpot. This guide walks you from installation to your first completed sync.

Before You Start

Make sure you have the following ready:

HubSpot access — Super Admin or App Marketplace install permissions in your portal
SFTP server details — hostname or IP address, port (typically 22), username, and a password or SSH private key
Network access — your SFTP server must be reachable from the public internet on its SFTP port. Confirm with your IT team if the server sits behind a firewall
Payment method — a credit card for subscription setup via the in-app billing portal

Don't have an SFTP server? Any standards-compliant SFTP server works — self-hosted (OpenSSH) or hosted services. You connect it with your own credentials; Karana Data Courier never provisions or manages servers on your behalf.

Step 1 — Install from the HubSpot Marketplace

Go to the HubSpot App Marketplace and search for Karana Data Courier
Click Install app and select the portal to install into
Review and accept the requested permissions — Karana Data Courier requests read-only access to your CRM objects plus HubSpot's native import and export APIs. It never writes to records directly; all imports go through HubSpot's own import engine, so you get HubSpot's native validation and import history
Click Connect app to complete the installation

Once installed, Karana Data Courier appears under Settings → Integrations → Connected Apps.

Step 2 — Activate Your Subscription

Open the Karana Data Courier settings page and go to the Billing tab
Click Get Sign Up Link and complete the sign-up form with your contact details, payment information, and chosen plan
Once your subscription is active, return to the app — the service is enabled automatically

The app shows a "Subscription Required" message until this step is complete. Import and export jobs will not run without an active subscription.

Step 3 — Connect Your SFTP Server

Go to the SFTP tab and click Set Credentials
Enter your server details:
- Host — hostname or IP address
- Port — typically 22
- Username — your SFTP account username
- Authentication — a password, an SSH private key, or a key plus password
- Base Directory — optional; the root directory Karana Data Courier starts from (e.g. /hubspot)
Click Save, then Test Connection to verify

Your credentials are encrypted at rest with AES-256-GCM and are used only to connect to your server for the jobs you configure.

Connection test failing? Verify the credentials with a standalone SFTP client first, then confirm with your IT team that the server accepts inbound connections from the public internet on your SFTP port.

Step 4 — Create an Export

Go to the Exports tab and click New Configuration
Name it descriptively (e.g. Deals to SAP — Hourly)
Select the HubSpot object (Contacts, Companies, Deals, Tickets, custom objects, and more)
Select the properties to include, in the order you want them in the file
Optionally add filters (e.g. "has email", "city equals Sydney") or enable incremental mode to export only records modified since the last successful run
Choose the file format (CSV or XLSX), delimiter, and header options
Enter the SFTP destination path (created automatically if it doesn't exist)
Set a file name pattern using placeholders like {object}, {date}, {datetime}, or {date:YYYYMMDD} — the resolved name previews before you save
Pick a schedule (every 15 minutes up to monthly, or manual-only) and click Save

Use Run Now on any configuration to trigger an immediate execution.

Step 5 — Create an Import

Go to the Imports tab and click New Configuration
Select the target HubSpot object and the operation: Upsert, Create Only, or Update Only
Enter the SFTP source path and a file pattern to match incoming files (e.g. contacts_*.csv)
Click Browse to pick a sample file, then map each column to a HubSpot property — or mark it Skip
Set a deduplication column mapped to a unique HubSpot property (strongly recommended for upserts and updates)
Set the archive path where processed files are moved after import, so the same file is never processed twice
Pick a schedule and click Save

Step 6 — Monitor Your Jobs

Dashboard — job volume, success rates, and period-over-period trends
Job History — every run with status, records processed, records failed, duration, and detailed error messages; filter by type, status, or date
Details / Retry — inspect any failure and retry recoverable jobs with one click
HubSpot Import link — jump from a completed import straight to HubSpot's native import results screen
Download — retrieve any completed export file directly from job history
SFTP tab — browse, upload, download, copy, move, rename, and delete files on your server without leaving HubSpot

Troubleshooting

Issue	What to check
Connection test fails	Verify credentials; confirm the server accepts connections from the public internet on your SFTP port
Import finds no files	Confirm the file exists in the configured path and matches the file pattern
Import fails with "minimum two rows"	The file is empty or missing a header row — fix the file and click Retry
Export not running on schedule	Check the configuration is Active, not Paused
Records not deduplicating	The dedup column must map to a property marked unique in HubSpot
"Subscription Required"	Complete billing setup on the Billing tab
"Additional permissions required"	Some object types (e.g. Tickets, Products) need extra read scopes — the app prompts you to re-authorize with one click when needed

Limits

Karana Data Courier uses HubSpot's native import and export APIs, which carry HubSpot's own daily limits (e.g. 50 imports and 30 exports per rolling 24-hour period on paid portals). Schedule accordingly for high-frequency use cases.

Support

Questions or issues? Email datacourier@unlimitedtechsolutions.com — include your HubSpot portal ID and, for job failures, the job's timestamp from Job History.