SFTP Getting Started

This guide walks you through your first SFTP upload end-to-end — from getting credentials to confirming that the network ingested your data.

What you’ll need

An organization API key

SFTP uses the same organization API key as the REST API. Create one in the SOLO dashboard under Settings → API keys (see Authentication). The key string itself is the SFTP password.

Treat the API key like any other credential. Store it in a secrets manager and never commit it to source control. The key — not the username — is what grants access: anyone holding it can upload, and call the API, as your organization.

An email-form username

The SFTP username is an email address, such as your work email. It selects the environment through an optional plus-tag; it isn’t used to authenticate you or to decide which organization your uploads belong to — the API key does both.

The network id

The network you’re furnishing into. Each SFTP feed’s detail page in the dashboard shows it. Your organization must be a furnisher or governor of that network.

An SFTP client

Anything that speaks SFTP works — the sftp command from OpenSSH, FileZilla, Cyberduck, or a library such as Python’s Paramiko.

Step 1 — Pick an environment

We recommend doing your first upload against sandbox. Sandbox is a separate environment from production: nothing you upload there reaches production data, so it’s the right place to learn the format and verify your pipeline. You select an environment with a plus-tag on the local part of the email:

Environment	Username format	Example
Sandbox	`email+sandbox@domain.com`	`alice+sandbox@yourbank.com`
Production	`email@domain.com` (no tag)	`alice@yourbank.com`

Usernames are case-insensitive — Alice@YourBank.com and alice@yourbank.com are the same.

Step 2 — Connect

The SFTP host is the same for every environment:

sftp.solo.one:22

sftp alice+sandbox@yourbank.com@sftp.solo.one
# When prompted, paste your organization API key as the password.

import paramiko

transport = paramiko.Transport(("sftp.solo.one", 22))
transport.connect(
    username="alice+sandbox@yourbank.com",
    password="<your organization API key>",
)
sftp = paramiko.SFTPClient.from_transport(transport)
# ... upload here ...
sftp.close()
transport.close()

Host solo-sftp-sandbox
    HostName sftp.solo.one
    User alice+sandbox@yourbank.com
    Port 22

On a successful connection you’ll land at the root of your organization’s upload area.

Your SFTP session is upload-only: you can put files and create directories, but ls, get, overwriting, and deleting are not permitted. Don’t be surprised when a directory listing is denied — that’s policy, not a fault. Verification happens in the dashboard (Step 5), not over SFTP.

If the server rejects you immediately, the most common causes are (1) the API key has been revoked or isn’t an organization key, (2) your organization isn’t provisioned in SOLO yet, or (3) the plus-tag is misspelled — use +sandbox for sandbox, or no tag for production. Re-check the username and key, then reach out to your account manager if it persists.

Step 3 — Write a JSONL file

Every upload is a JSONL file: UTF-8 text with one JSON object per line. Each record carries a _type naming the kind of record it is — that’s how the network decides which mappings receive it. Find the record type in the dashboard: open Feeds, pick the feed you’re delivering, and read its sample record. The sample’s _type is the value to use, and its other fields are the ones the feed’s mapping reads. For this walkthrough, write one consumer record for a feed whose record type is consumers:

first_upload.jsonl

{"_type":"consumers","ssn":"123456789","dob":"1990-01-15","first_name":"Jane","last_name":"Doe"}

A few things to know about the format (full reference):

One compact object per line — not a JSON array, and not pretty-printed across lines.
Blank lines are skipped. Every other line is processed independently, so a single bad line won’t fail the rest of the file.
Identifiers are strings. Write SSNs and tax identifiers as "012345678", never as numbers — a number drops the leading zero.
Filenames — use a new filename for every upload (a date or batch number works well).

Step 4 — Upload

Put the file in network_{network_id}/jsonl_furnish_data/, where {network_id} is the network the records go to:

sftp> mkdir network_9f1c0c2e-7a44-4f1e-9d2a-08b6f3a1c5d7
sftp> cd network_9f1c0c2e-7a44-4f1e-9d2a-08b6f3a1c5d7
sftp> mkdir jsonl_furnish_data
sftp> cd jsonl_furnish_data
sftp> put first_upload.jsonl
sftp> bye

network_dir = "network_9f1c0c2e-7a44-4f1e-9d2a-08b6f3a1c5d7"
for directory in (network_dir, f"{network_dir}/jsonl_furnish_data"):
    try:
        sftp.mkdir(directory)
    except OSError:
        pass  # already exists
sftp.put("first_upload.jsonl", f"/{network_dir}/jsonl_furnish_data/first_upload.jsonl", confirm=False)

Sessions can’t overwrite or delete existing files, so re-using a name from a previous drop will be rejected. Pass confirm=False in Paramiko — its post-upload check lists the file, which upload-only sessions don’t allow.

Step 5 — Verify ingestion

Ingestion starts automatically once the upload completes and runs in the background. Each file has 30 minutes to finish; split very large exports into several files. Check the result in the SOLO dashboard (or production): the Uploads page lists every file your organization has sent, with the records read and the succeeded, filtered, failed, and unmatched counts. The feed’s detail page shows its recent deliveries and names any record types no mapping claimed.

Re-sending is safe for identities: records resolve to the existing consumer or business on their natural keys (SSN and date of birth for consumers; federal EIN and jurisdiction of formation for businesses), so a re-upload attaches to the same profiles instead of creating duplicates. Verification events in a re-sent record are added again, so re-send only the records that didn’t ingest.

Common first-upload issues

"Permission denied" on ls, get, or overwrite

Working as intended — SFTP access is upload-only. You can put new files and create directories; everything else is denied. Use the dashboard to inspect what you’ve uploaded, and use a new filename rather than overwriting an old one.

"Host key verification failed"

The first time you connect from a new machine your SSH client doesn’t know the server’s host key yet. Either accept the fingerprint at the prompt, or pre-populate your known_hosts:

ssh-keyscan sftp.solo.one >> ~/.ssh/known_hosts

File uploaded but no upload appears in the dashboard

The file landed outside a jsonl_furnish_data/ folder, so it was never ingested. Re-upload it into network_{network_id}/jsonl_furnish_data/.

Records are counted as unmatched

No active mapping in the target network claims their _type. Compare the value with the feed’s sample record, confirm the feed’s mapping is active rather than a draft, and confirm the folder names the network you expected.

The upload fails with an access error

Your organization doesn’t hold the furnisher or governor role in the network named by the folder. Check the network id in the path, or ask the network’s governor to add your organization as a furnisher.

Only part of a large file was ingested

The file ran out of its 30-minute processing budget or stopped partway. Records processed before that point stay ingested. Check the upload’s results, then upload the remaining records as a new file.

Where to go next

SFTP Overview

The full mental model — directories, environments, how routing works.

JSONL Files

The file format, record types, and results reference.

Furnishing Policies

How mappings turn records into network data.

API Reference

Prefer to furnish over HTTPS? Records can be sent as REST calls.

Furnishing API

Query API

GraphQL API

What you’ll need

Step 1 — Pick an environment

Step 2 — Connect

Step 3 — Write a JSONL file

Step 4 — Upload

Step 5 — Verify ingestion

Common first-upload issues

Where to go next

SFTP Overview

JSONL Files

Furnishing Policies

API Reference

​What you’ll need

​Step 1 — Pick an environment

​Step 2 — Connect

​Step 3 — Write a JSONL file

​Step 4 — Upload

​Step 5 — Verify ingestion

​Common first-upload issues

​Where to go next

SFTP Overview

JSONL Files

Furnishing Policies

API Reference

What you’ll need

Step 1 — Pick an environment

Step 2 — Connect

Step 3 — Write a JSONL file

Step 4 — Upload

Step 5 — Verify ingestion

Common first-upload issues

Where to go next