> For the complete documentation index, see [llms.txt](https://resources.abstractivehealth.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://resources.abstractivehealth.com/api-documentation/sftp-ingestion.md). # 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](/api-documentation/reference-docs.md) 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:** ```bash ssh-keygen -t rsa -b 4096 -f ~/.ssh/abstractive_sftp ``` **Windows PowerShell / Command Prompt:** ```powershell 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 with the subject line **"SFTP Access Request"**. To get the contents of your public key: **Mac Terminal:** ```bash cat ~/.ssh/abstractive_sftp.pub ``` **Windows PowerShell / Command Prompt:** ```powershell 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... your@email.com ``` 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: ```bash 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: ```bash put /path/to/your/patients.csv ``` To delete a file: ```bash 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-documentation/reference-docs.md) 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 | `patient@example.com` | | `team_api_code` | Associates the patient search with a specific team in your organization | String | `default` | {% hint style="warning" %} 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. {% endhint %} ### 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. ```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,john@example.com,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 ```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,john@example.com,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,jane@example.com,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 .