Skip to content

Managing Subjects

Create and manage subjects (patients) using the iFlow CLI.

Overview

Subjects represent patients in the iFlow platform. Each subject can have:

  • Samples - Biological samples for analysis
  • Clinical metadata - Name, sex, date of birth, diagnosis, etc.
  • Custom properties - Any additional key-value data (first_name, surname, gender, etc.)

Prerequisites

  1. Installed CLI - See Installation
  2. Authenticated - Run iflow login
  3. Project selected - Run iflow config select-project

Listing Subjects

iflow subjects list
iflow subjects list --limit 50

Creating Subjects

--display-id (-n) is required. All other fields are passed via --property/-P key=value:

# Basic subject
iflow subjects create --display-id "Patient Smith"

# With clinical metadata
iflow subjects create \
  --display-id "SUB-2026-001" \
  -P sex=female \
  -P date_of_birth=1985-03-15 \
  -P external_id=ACC-12345 \
  -P first_name=Jane \
  -P surname=Doe \
  -P diagnosis="Hereditary cancer"

# With tags
iflow subjects create -n "SUB-2026-002" -P sex=male -t hereditary -t urgent

Property Types

Properties are split into two categories:

Model columns (stored as dedicated database fields):

Key Description
sex Patient sex (male, female, other, unknown)
date_of_birth Date of birth (YYYY-MM-DD)
external_id External system reference / accession number
diagnosis Clinical diagnosis
clinical_notes Free-text clinical notes

Custom properties (stored in JSONB):

Any other key goes into the flexible properties store. Common examples:

Key Description
first_name Patient first name
surname Patient surname
gender Gender identity
hpo_terms HPO phenotype terms
phenotype_description Free-text phenotype

Create Options

Option Description
-n, --display-id Subject display ID (required)
-P, --property Property key=value (repeatable)
-t, --tag Tag (repeatable)
-p, --project Project ID (uses default)
--curl Output curl command

Getting Subject Details

iflow subjects get SUBJECT_ID

Output:

Subject: SUB-2026-001
  ID: abc123-def456-...
  Display ID: SUB-2026-001
  External ID: ACC-12345
  Sex: female
  Date of Birth: 1985-03-15
  Diagnosis: Hereditary cancer
  Created: 2026-02-13T10:00:00Z
  Properties:
    first_name: Jane
    surname: Doe

Updating Subjects

Update a subject's display ID, model fields, or custom properties:

# Change display ID
iflow subjects update SUBJECT_ID -n "NEW-ID"

# Update clinical metadata
iflow subjects update SUBJECT_ID -P sex=female -P diagnosis="Type 2 Diabetes"

# Update multiple fields at once
iflow subjects update SUBJECT_ID \
  -n "SUB-2026-001-v2" \
  -P external_id=ACC-99999 \
  -P clinical_notes="Updated after follow-up"

Update Options

Option Description
-n, --display-id New subject display ID
-P, --property Property key=value (repeatable)
-p, --project Project ID (uses default)
--curl Output curl command

Deleting Subjects

iflow subjects delete SUBJECT_ID

You'll be prompted to confirm. Deleting a subject cascades to its samples.

API Access

For programmatic access (LIS integration), use the REST API:

curl -X POST https://miner.flow.labpgx.com/api/v1/subjects \
  -H "Authorization: Bearer TOKEN" \
  -H "X-Project-ID: PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "display_id": "SUB-2026-001",
    "sex": "female",
    "date_of_birth": "1985-03-15",
    "external_id": "ACC-12345",
    "properties": {
      "first_name": "Jane",
      "surname": "Doe",
      "gender": "female"
    }
  }'

curl https://miner.flow.labpgx.com/api/v1/subjects \
  -H "Authorization: Bearer TOKEN" \
  -H "X-Project-ID: PROJECT_ID"

Property Promotion

When sending model-column keys (like sex) inside properties, they are automatically promoted to the correct field. This means LIS systems can send all metadata in properties without worrying about the distinction.

Next Steps