📂SFTP Patient Ingestion

Abstractive Health supports automated patient search ingestion via SFTP. This is a low-code bulk ingestion option for teams that can generate a CSV but do not want to build against the JSON API directly. Drop a CSV file containing patient demographics onto your dedicated SFTP folder and our pipeline will automatically trigger patient searches on your behalf.

Before you begin: choose an SFTP client

To use this workflow, your organization will need an SFTP client that supports SSH key authentication. Common options include:

• Mac Terminal — built-in ssh-keygen and sftp commands

• Windows PowerShell / Command Prompt — built-in ssh-keygen and sftp commands (Windows 10 and later)

• WinSCP

• FileZilla

• Cyberduck

• PuTTY / PSFTP

Abstractive does not require a specific SFTP client. Your IT or technical team may use whichever tool is approved by your organization, as long as it supports SFTP with SSH key-based authentication.

Abstractive supports the SFTP endpoint, user provisioning, SSH public key setup, CSV format, and ingestion workflow. Customer IT teams are responsible for installing and configuring any third-party SFTP client used on their machines.

---

How it works

1. You upload a CSV file to your SFTP folder

2. Our pipeline detects the file and parses each row as a patient search request

3. Each patient is queued through the same Search Patient pipeline

4. Results are available via the API or your connected dashboard

---

Step 1: Generate an SSH key pair

You need an SSH key pair to authenticate with the SFTP server.

Mac Terminal:

ssh-keygen -t rsa -b 4096 -f ~/.ssh/abstractive_sftp

Windows PowerShell / Command Prompt:

ssh-keygen -t rsa -b 4096 -f $env:USERPROFILE\.ssh\abstractive_sftp

This creates two files — a private key (keep this secret, never share it) and a public key (send this to us).

---

Step 2: Send us your public key

Email your public key to [e-mail] with the subject line "SFTP Access Request".

To get the contents of your public key:

Mac Terminal:

cat ~/.ssh/abstractive_sftp.pub

Windows PowerShell / Command Prompt:

Get-Content $env:USERPROFILE\.ssh\abstractive_sftp.pub

Copy the full output and paste it into the email. It should look something like:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQ... [e-mail]

We will provision your SFTP user and send you back your username and the server endpoint.

---

Step 3: Connect to the SFTP server

Once you have your credentials from us, connect using:

sftp -i ~/.ssh/abstractive_sftp your-username@your-server-endpoint

Your home directory is automatically scoped to your organization's folder — you cannot access other customers' data.

To upload a file:

put /path/to/your/patients.csv

To delete a file:

rm patients.csv

---

Step 4: Format your CSV

Each row in the CSV represents one patient search request. The column names map directly to the Search Patient API payload.

Required columns

Column	Description	Format	Example
given_name	Patient's first name. Include middle name here if available.	String	John Michael
family_name	Patient's last name	String	Smith
administrative_gender_code	Patient gender	M or F	M
birth_time	Date of birth	YYYYMMDD	19810315

Optional columns (strongly recommended — improves match quality)

Column	Description	Format	Example
street_address_line	Street address	String	1100 Test Street
city	City	String	Helena
state	State abbreviation	2-letter code	AL
postal_code	ZIP code	String	35080
country	Country code	US	US
phone_number	Patient phone number	XXX-XXX-XXXX	205-111-1111
email	Patient email address	String	[e-mail]
team_api_code	Associates the patient search with a specific team in your organization	String	default

Address fields are optional but materially improve matching quality across the Carequality® network. When addresses are provided, all five address fields (street_address_line, city, state, postal_code, country) must be included together.

Multiple addresses per patient

If a patient has lived at multiple addresses, you can include them as additional rows with the same demographics — just vary the address columns. The pipeline groups rows by given_name + family_name + birth_time + administrative_gender_code and treats all matched rows as a single patient with multiple addresses.

given_name,family_name,administrative_gender_code,birth_time,street_address_line,city,state,postal_code,country,phone_number,email,team_api_code
John Michael,Smith,M,19810315,1100 Test Street,Helena,AL,35080,US,205-111-1111,[e-mail],cardiology
John Michael,Smith,M,19810315,200 Oak Avenue,New York,NY,10001,US,,,cardiology

Both rows above resolve to the same patient search with two addresses. Including prior addresses materially improves matching across the Carequality® network.

Example CSV

given_name,family_name,administrative_gender_code,birth_time,street_address_line,city,state,postal_code,country,phone_number,email,team_api_code
John Michael,Smith,M,19810315,1100 Test Street,Helena,AL,35080,US,205-111-1111,[e-mail],cardiology
John Michael,Smith,M,19810315,200 Oak Avenue,New York,NY,10001,US,,,cardiology
Jane,Doe,F,19750822,55 Oak Avenue,New York,NY,10001,US,212-555-9876,[e-mail],default
Robert,Johnson,M,19631204,,,,,,,,,

• Rows 1–2: John Smith with two addresses, both associated with the cardiology team

• Row 3: Jane Doe with one address, associated with the default team

• Row 4: Minimal valid row — only required fields, no address or team

---

Notes

• Drop files into the root of your home directory. Do not create subfolders.

• File names must end in .csv.

• Each CSV can contain multiple patients. We recommend batches of no more than 500 rows per file.

• Duplicate patients (same demographics within 1 hour) will be rate-limited by the pipeline.

• If you have questions or issues, contact [e-mail].