Test Patients

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

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

Authentication

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

API Endpoints

Method	Endpoint	Description
POST	/v1/auth/token	Generate authentication token (using email + password)
POST	/v1/organizations/:orgId/test-patients	Create a test patient
GET	/v1/organizations/:orgId/test-patients	List all test patients
GET	/v1/organizations/:orgId/test-patients/:patientId	Get a specific test patient
PUT	/v1/organizations/:orgId/test-patients/:patientId	Update a test patient
DELETE	/v1/organizations/:orgId/test-patients/:patientId	Delete a test patient
POST	/v1/projects/:projectId/patients	Add test patient to a project (OrgAdmin or researcher token)
POST	/v1/projects/:projectId/test-patients/:patientId/consent	Update consent for a test patient (OrgAdmin or researcher token)
POST	/v1/patients/:patientId/upload-documents	Upload documents (zip file) for a test patient
POST	/mcp	MCP endpoint for AI tool access (see MCP Access)

Quick Start

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. Generate a 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
  }
}

3. List Test Patients

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

4. Add Test Patient to Project

To test the production MCP flow with project context, add the test patient to a project using a researcher or org 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": []
}

5. Update Consent (as the Test Patient)

Update consent for the test patient against the project using the patient token (from step 2):

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"
}

6. Update a Test Patient (Optional - Admin)

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
  }'

7. Upload Documents (as the Test Patient)

Use the patient token (from step 2) to 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"
}

Patient Authentication Required

This endpoint requires authentication as the patient (using the token from /auth/token), not as an org admin. The patientId in the URL must match the authenticated patient.

File Size Limit

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

8. Delete a Test Patient

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

9. Access MCP Tools (as the Test Patient)

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.