> 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 . --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://resources.abstractivehealth.com/api-documentation/sftp-ingestion.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.