Patients API

The Patients API provides full CRUD operations for patient records with FHIR R4 compliance, AES-256 field-level encryption for all Protected Health Information (PHI), archive/unarchive workflows, and direct import from eClinicalWorks.

PHI Encryption

All patient demographic fields (first name, last name, date of birth, SSN, phone, email, address) are encrypted at rest using AES-256. Decrypted values are only returned to authenticated users with the appropriate role permissions.

List Patients

Retrieve a paginated list of active patients. Supports filtering by name, MRN, and status.

GET /api/v1/patients/

Query Parameters

Parameter	Type	Required	Description
`page`	`integer`	No	Page number (default: 1)
`page_size`	`integer`	No	Results per page (default: 20, max: 100)
`search`	`string`	No	Search by first name, last name, or MRN
`active`	`boolean`	No	Filter by active status: `true`, `false`
`ordering`	`string`	No	Sort field: `last_name`, `created_at`, `-created_at`

Example Request

curl https://app.vantrexia.com/api/v1/patients/?active=true&search=doe&page_size=10 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "first_name": "Jane",
      "last_name": "Doe",
      "date_of_birth": "1958-03-15",
      "gender": "female",
      "mrn": "MRN-00001",
      "active": true,
      "phone": "+1-555-0101",
      "email": "jane.doe@email.com",
      "address": {
        "line1": "123 Main St",
        "line2": "Apt 4B",
        "city": "Springfield",
        "state": "IL",
        "zip": "62704"
      },
      "external_id": "ECW-98765",
      "created_at": "2026-01-10T14:30:00Z",
      "updated_at": "2026-02-01T09:15:00Z"
    }
  ]
}

Create Patient

Create a new patient record. All PHI fields are automatically encrypted before storage. A unique MRN is auto-generated if not provided.

POST /api/v1/patients/

Request Body

Parameter	Type	Required	Description
`first_name`	`string`	Yes	Patient's first name (encrypted at rest)
`last_name`	`string`	Yes	Patient's last name (encrypted at rest)
`date_of_birth`	`string`	Yes	ISO 8601 date format: `YYYY-MM-DD`
`gender`	`string`	Yes	One of: `male`, `female`, `other`, `unknown`
`mrn`	`string`	No	Medical Record Number (auto-generated if omitted)
`phone`	`string`	No	Phone number (encrypted at rest)
`email`	`string`	No	Email address (encrypted at rest)
`address`	`object`	No	Address object with `line1`, `line2`, `city`, `state`, `zip`
`external_id`	`string`	No	External EMR identifier (e.g., eClinicalWorks ID)

Example Request

curl -X POST https://app.vantrexia.com/api/v1/patients/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Robert",
    "last_name": "Williams",
    "date_of_birth": "1965-08-22",
    "gender": "male",
    "phone": "+1-555-0199",
    "email": "r.williams@email.com",
    "address": {
      "line1": "456 Oak Avenue",
      "city": "Chicago",
      "state": "IL",
      "zip": "60614"
    }
  }'

Response `201 Created`

{
  "id": "4d5e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a",
  "first_name": "Robert",
  "last_name": "Williams",
  "date_of_birth": "1965-08-22",
  "gender": "male",
  "mrn": "MRN-00088",
  "active": true,
  "phone": "+1-555-0199",
  "email": "r.williams@email.com",
  "address": {
    "line1": "456 Oak Avenue",
    "line2": null,
    "city": "Chicago",
    "state": "IL",
    "zip": "60614"
  },
  "external_id": null,
  "created_at": "2026-02-06T14:30:00Z",
  "updated_at": "2026-02-06T14:30:00Z"
}

Get Patient

Retrieve a single patient record by ID. Returns all demographic fields including encrypted PHI (decrypted for authorized users).

GET /api/v1/patients/{uuid}/

Path Parameters

Parameter	Type	Required	Description
`uuid`	`uuid`	Yes	Patient UUID

Example Request

curl https://app.vantrexia.com/api/v1/patients/d290f1ee-6c54-4b01-90e6-d701748f0851/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": "1958-03-15",
  "gender": "female",
  "mrn": "MRN-00001",
  "active": true,
  "phone": "+1-555-0101",
  "email": "jane.doe@email.com",
  "address": {
    "line1": "123 Main St",
    "line2": "Apt 4B",
    "city": "Springfield",
    "state": "IL",
    "zip": "62704"
  },
  "external_id": "ECW-98765",
  "created_at": "2026-01-10T14:30:00Z",
  "updated_at": "2026-02-01T09:15:00Z"
}

Update Patient

Update an existing patient record. Supports full replacement (PUT). All changes are audit-logged.

PUT /api/v1/patients/{uuid}/

Example Request

curl -X PUT https://app.vantrexia.com/api/v1/patients/d290f1ee-6c54-4b01-90e6-d701748f0851/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Doe",
    "date_of_birth": "1958-03-15",
    "gender": "female",
    "phone": "+1-555-0102",
    "email": "jane.doe.new@email.com",
    "address": {
      "line1": "789 Elm Street",
      "city": "Springfield",
      "state": "IL",
      "zip": "62704"
    }
  }'

Response `200 OK`

Returns the full updated patient object (same structure as GET response).

Delete Patient

Soft-delete a patient record. The record is marked as deleted but retained for compliance. Soft-deleted patients no longer appear in list queries.

DELETE /api/v1/patients/{uuid}/

Example Request

curl -X DELETE https://app.vantrexia.com/api/v1/patients/d290f1ee-6c54-4b01-90e6-d701748f0851/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `204 No Content`

Soft Delete

Patient records are never permanently deleted due to HIPAA data retention requirements. The record is flagged as deleted and excluded from normal queries. Administrators can view deleted records via admin tools.

Archive Patient

Archive a patient with a required reason. Archived patients remain accessible but are separated from the active patient list.

POST /api/v1/patients/{uuid}/archive/

Request Body

Parameter	Type	Required	Description
`reason`	`string`	Yes	Reason for archiving (e.g., "Discharged from RPM program")

Example Request

curl -X POST https://app.vantrexia.com/api/v1/patients/d290f1ee-6c54-4b01-90e6-d701748f0851/archive/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Patient discharged from RPM program - goals met"
  }'

Response `200 OK`

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "status": "archived",
  "archived_at": "2026-02-06T15:00:00Z",
  "archived_by": "clinician@practice.com",
  "archive_reason": "Patient discharged from RPM program - goals met"
}

Unarchive Patient

Restore an archived patient to active status.

POST /api/v1/patients/{uuid}/unarchive/

Example Request

curl -X POST https://app.vantrexia.com/api/v1/patients/d290f1ee-6c54-4b01-90e6-d701748f0851/unarchive/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "status": "active",
  "unarchived_at": "2026-02-06T15:30:00Z",
  "unarchived_by": "clinician@practice.com"
}

List Archived Patients

Retrieve a paginated list of archived patients with their archive reasons and timestamps.

GET /api/v1/patients/archived/

Example Request

curl https://app.vantrexia.com/api/v1/patients/archived/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

{
  "count": 12,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
      "first_name": "Mary",
      "last_name": "Thompson",
      "mrn": "MRN-00045",
      "status": "archived",
      "archived_at": "2026-01-28T10:00:00Z",
      "archived_by": "admin@practice.com",
      "archive_reason": "Patient transferred to another practice"
    }
  ]
}

Import from eClinicalWorks

Import selected patients from eClinicalWorks into Vantrexia. The system performs duplicate detection based on external ID and handles conflict resolution automatically.

POST /api/v1/patients/import_selected_from_ecw/

Request Body

Parameter	Type	Required	Description
`ecw_patient_ids`	`array`	Yes	Array of eClinicalWorks patient IDs to import

Example Request

curl -X POST https://app.vantrexia.com/api/v1/patients/import_selected_from_ecw/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "ecw_patient_ids": ["ECW-12345", "ECW-67890", "ECW-11111"]
  }'

Response `200 OK`

{
  "imported": 2,
  "skipped": 1,
  "errors": 0,
  "details": [
    { "ecw_id": "ECW-12345", "status": "imported", "patient_id": "5e6f7a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b" },
    { "ecw_id": "ECW-67890", "status": "imported", "patient_id": "6f7a8b9c-0d1e-2f3a-4b5c-6d7e8f9a0b1c" },
    { "ecw_id": "ECW-11111", "status": "skipped", "reason": "Patient already exists (ID: 7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d)" }
  ]
}

FHIR R4 Patient Resource Model

Internally, patient records are stored and can be exported in FHIR R4 Patient resource format. The following shows the FHIR representation of a Vantrexia patient record:

{
  "resourceType": "Patient",
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "meta": {
    "versionId": "3",
    "lastUpdated": "2026-02-01T09:15:00Z",
    "profile": ["http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"]
  },
  "identifier": [
    {
      "system": "https://vantrexia.com/mrn",
      "value": "MRN-00001"
    },
    {
      "system": "https://eclinicalworks.com/patient-id",
      "value": "ECW-98765"
    }
  ],
  "active": true,
  "name": [
    {
      "use": "official",
      "family": "Doe",
      "given": ["Jane"]
    }
  ],
  "gender": "female",
  "birthDate": "1958-03-15",
  "telecom": [
    { "system": "phone", "value": "+1-555-0101", "use": "home" },
    { "system": "email", "value": "jane.doe@email.com" }
  ],
  "address": [
    {
      "use": "home",
      "line": ["123 Main St", "Apt 4B"],
      "city": "Springfield",
      "state": "IL",
      "postalCode": "62704",
      "country": "US"
    }
  ]
}

Previous Authentication API Next Observations API

List Patients

Query Parameters

Example Request

Response 200 OK

Create Patient

Request Body

Example Request

Response 201 Created

Get Patient

Path Parameters

Example Request

Response 200 OK

Update Patient

Example Request

Response 200 OK

Delete Patient

Example Request

Response 204 No Content

Archive Patient

Request Body

Example Request

Response 200 OK

Unarchive Patient

Example Request

Response 200 OK

List Archived Patients

Example Request

Response 200 OK

Import from eClinicalWorks

Request Body

Example Request

Response 200 OK

FHIR R4 Patient Resource Model

Response `200 OK`

Response `201 Created`

Response `200 OK`

Response `200 OK`

Response `204 No Content`

Response `200 OK`

Response `200 OK`

Response `200 OK`

Response `200 OK`