Test Patients

Test patients allow organization administrators to create simulated patient accounts for development, QA testing, and demonstration purposes without affecting real patient data.

Just want to click through the app?

If you're looking for a non-technical, no-API walkthrough of logging in and using HealthEx as a synthetic patient, see User Workflows.

Key Features

Auto-generated credentials: Each test patient gets a unique email address and secure password
Organization-scoped: Test patients are tied to a specific organization
Full CRUD operations: Create, read, update, and delete test patients
Password management: Regenerate passwords or set custom passwords as needed

Email Format

Test patient emails are automatically generated in the format:

test-patient+[random]@[org-domain]

Where:

[random] is a unique alphanumeric string
[org-domain] is the organization's configured domain

Domain Configuration Required

Your organization will need a domain configured by HealthEx. Contact us to get this configured.

API Endpoints

Action	Endpoint	Token Required
Create a test patient	POST `/v1/organizations/:orgId/test-patients`	Admin/Researcher
List test patients	GET `/v1/organizations/:orgId/test-patients`	Admin/Researcher
Get a specific test patient	GET `/v1/organizations/:orgId/test-patients/:patientId`	Admin/Researcher
Update a test patient	PUT `/v1/organizations/:orgId/test-patients/:patientId`	Admin/Researcher
Delete a test patient	DELETE `/v1/organizations/:orgId/test-patients/:patientId`	Admin/Researcher
Add test patient to a project	POST `/v1/projects/:projectId/patients`	Admin/Researcher
Generate authentication token	POST `/v1/auth/token`	Email + password only
Update consent	POST `/v1/projects/:projectId/test-patients/:patientId/consent`	Patient
Upload documents	POST `/v1/patients/:patientId/upload-documents`	Patient
Access MCP tools	POST `/mcp`	Patient

Quick Start

Using Admin/Researcher Token

1. Create a Test Patient

curl -X POST "https://api.healthex.io/v1/organizations/{orgId}/test-patients" \
  -H "Authorization: Bearer {token}"

All fields are optional. By default, the test patient is created with:

firstName: Test
lastName: Patient
email: Auto-generated in format test-patient+[random]@[org-domain]
password: Auto-generated secure password

Response:

{
  "id": "1addc6fa-3c59-4915-b0ba-ae2a31ff1f75",
  "email": "test-patient+dqKVeMid8N41@example.com",
  "firstName": "Test",
  "lastName": "Patient",
  "dateOfBirth": "1990-01-15",
  "organizationId": "658ac9e4-2a8b-4775-a58f-06ef6d65d914",
  "createdAt": "2026-01-31T01:52:05.653Z",
  "isTestPatient": true,
  "password": "zkWZTH$$BmfTAOW4"
}

Important

The password is only returned once at creation time. Store it securely as it cannot be retrieved later.

2. List Test Patients

curl "https://api.healthex.io/v1/organizations/{orgId}/test-patients" \
  -H "Authorization: Bearer {token}"

3. Add Test Patient to Project

To test the production MCP flow with project context, add the test patient to a project (still using your admin token):

curl -X POST "https://api.healthex.io/v1/projects/{projectId}/patients" \
  -H "Authorization: Bearer {researcher_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "patients": [
      {
        "email": "test-patient+dqKVeMid8N41@example.com",
        "firstName": "Test",
        "lastName": "Patient",
        "languagePreference": "en"
      }
    ],
    "suppressNotifications": true
  }'

Response:

{
  "totalProcessed": 1,
  "successCount": 1,
  "errorCount": 0,
  "duplicatesCount": 0,
  "errors": [],
  "duplicates": [],
  "successfulPatients": []
}

4. Update a Test Patient (Regenerate Password)

To regenerate the password:

curl -X PUT "https://api.healthex.io/v1/organizations/{orgId}/test-patients/{patientId}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "regeneratePassword": true
  }'

5. Delete a Test Patient

curl -X DELETE "https://api.healthex.io/v1/organizations/{orgId}/test-patients/{patientId}" \
  -H "Authorization: Bearer {token}"

Using Patient Token

After creating a test patient above, use its email and password to generate an authentication token. Then use that token for patient-specific operations:

1. Generate an Authentication Token

Use the patient's email and password to get an authentication token via the /auth/token endpoint. This is the standard patient authentication flow - the same endpoint works for both test patients and real patients.

Basic token (for test patient MCP bypass):

curl -X POST "https://api.healthex.io/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test-patient+dqKVeMid8N41@example.com",
    "password": "zkWZTH$$BmfTAOW4"
  }'

With Project ID (for production-like MCP flow):

curl -X POST "https://api.healthex.io/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test-patient+dqKVeMid8N41@example.com",
    "password": "zkWZTH$$BmfTAOW4",
    "projectId": "658ac9e4-2a8b-4775-a58f-06ef6d65d914"
  }'

Response:

{
  "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiration": 1738368725,
  "user": {
    "type": "PATIENT",
    "id": "1addc6fa-3c59-4915-b0ba-ae2a31ff1f75",
    "firstName": "Test",
    "lastName": "Patient",
    "state": "ca",
    "createdAt": "2026-01-31T01:52:05.653Z",
    "isTestPatient": true
  }
}

Update consent for the test patient against the project:

curl -X POST "https://api.healthex.io/v1/projects/{projectId}/test-patients/{patientId}/consent" \
  -H "Authorization: Bearer {patient_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "consentStatus": "OPTED_IN"
  }'

Response:

{
  "consentRecordId": "1addc6fa-3c59-4915-b0ba-ae2a31ff1f75"
}

3. Upload Documents

Upload a zip file containing documents:

curl -X POST "https://api.healthex.io/v1/patients/{patientId}/upload-documents" \
  -H "Authorization: Bearer {patient_token}" \
  -F "file=@documents.zip"

Response:

{
  "batchId": "1addc6fa-3c59-4915-b0ba-ae2a31ff1f75"
}

File Size Limit

The maximum file size for uploads is 100 MB. Requests exceeding this limit will be rejected.

4. Access MCP Tools

Test patients can directly access the MCP endpoint without OAuth or consent setup:

curl -X POST "https://api.healthex.io/mcp" \
  -H "Authorization: Bearer {patient_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_health_summary",
      "arguments": {}
    }
  }'

Simplified MCP Access

Test patients bypass OAuth. See MCP Access for Test Patients for the complete guide and all available tools.

Reference: Authentication Requirements

Management Endpoints

All Test Patient management endpoints (create, list, update, delete) require:

External Researcher API client: These endpoints are only accessible via the External Researcher API client type
Bearer token authentication: Token must be generated using External Researcher API credentials
User type: The authenticated user must be an EXTERNAL_RESEARCHER
Permission: ORG_ADMIN permission for the target organization

Token Generation

Test patients authenticate using the standard /auth/token endpoint with email and password. This is the same endpoint used for all patient authentication - test patients are simply regular patients with the isTestPatient flag set to true in the database.

No authentication required (public endpoint)
Rate limited to prevent abuse
The isTestPatient flag in the token payload is read from the database
Optional projectId parameter can be included for MCP access with project context

Key Features​

Email Format​

API Endpoints​

Quick Start​

Using Admin/Researcher Token​

1. Create a Test Patient​

2. List Test Patients​

3. Add Test Patient to Project​

4. Update a Test Patient (Regenerate Password)​

5. Delete a Test Patient​

Using Patient Token​

1. Generate an Authentication Token​

2. Update Consent​

3. Upload Documents​

4. Access MCP Tools​

Reference: Authentication Requirements​

Management Endpoints​

Token Generation​

Key Features

Email Format

API Endpoints

Quick Start

Using Admin/Researcher Token

1. Create a Test Patient

2. List Test Patients

3. Add Test Patient to Project

4. Update a Test Patient (Regenerate Password)

5. Delete a Test Patient

Using Patient Token

1. Generate an Authentication Token

2. Update Consent

3. Upload Documents

4. Access MCP Tools

Reference: Authentication Requirements

Management Endpoints

Token Generation