Patients

Base URL: https://api.welkinhealth.com/{tenantName}/{instanceName}/patients

Patients are the core resource in Welkin. A patient represents an individual receiving care. All clinical data — assessments, encounters, programs, messages — is associated with a patient record.

---

Create Patient

POST /patients

Creates a new patient record.

Request Body

Field	Type	Required	Description
firstName	string	Yes	Patient's first name
lastName	string	Yes	Patient's last name
birthDate	string (YYYY-MM-DD)	No	Date of birth
gender	string	No	MALE, FEMALE, OTHER, UNKNOWN
email	string	No	Primary email address
phone	string	No	Primary phone number
mrn	string	No	Medical record number (must be unique)

Example Request

POST /acme/live/patients
Authorization: Bearer {token}
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Doe",
  "birthDate": "1985-06-15",
  "gender": "FEMALE",
  "email": "[e-mail]",
  "phone": "[phone]",
  "mrn": "MRN-00123"
}

Example Response

{
  "id": "pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2",
  "firstName": "Jane",
  "lastName": "Doe",
  "birthDate": "1985-06-15",
  "gender": "FEMALE",
  "email": "[e-mail]",
  "phone": "[phone]",
  "mrn": "MRN-00123",
  "status": "ACTIVE",
  "createdAt": "2026-03-19T14:32:00Z",
  "updatedAt": "2026-03-19T14:32:00Z"
}

---

Get All Patients

GET /patients

Returns a paginated list of patients.

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 0)
size	integer	Page size (default: 20, max: 100)
firstName	string	Filter by first name (partial match)
lastName	string	Filter by last name (partial match)
mrn	string	Filter by medical record number
status	string	Filter by status: ACTIVE, INACTIVE

Example Request

GET /acme/live/patients?status=ACTIVE&page=0&size=20
Authorization: Bearer {token}

Example Response

{
  "data": [
    {
      "id": "pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2",
      "firstName": "Jane",
      "lastName": "Doe",
      "birthDate": "1985-06-15",
      "gender": "FEMALE",
      "email": "[e-mail]",
      "phone": "[phone]",
      "mrn": "MRN-00123",
      "status": "ACTIVE",
      "createdAt": "2026-03-19T14:32:00Z",
      "updatedAt": "2026-03-19T14:32:00Z"
    },
    {
      "id": "pt_2a4b6c8d-e0f1-4a2b-c3d4-e5f6a7b8c9d0",
      "firstName": "John",
      "lastName": "Smith",
      "birthDate": "1972-11-03",
      "gender": "MALE",
      "email": "[e-mail]",
      "phone": "[phone]",
      "mrn": "MRN-00124",
      "status": "ACTIVE",
      "createdAt": "2026-03-18T09:15:00Z",
      "updatedAt": "2026-03-18T09:15:00Z"
    }
  ],
  "metaInfo": {
    "page": 0,
    "pageSize": 20,
    "totalElements": 2,
    "totalPages": 1
  }
}

---

Get Patient by ID

GET /patients/{patientId}

Returns a single patient record by ID.

Path Parameters

Parameter	Type	Description
patientId	string	The unique patient ID

Example Request

GET /acme/live/patients/pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2
Authorization: Bearer {token}

Example Response

{
  "id": "pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2",
  "firstName": "Jane",
  "lastName": "Doe",
  "birthDate": "1985-06-15",
  "gender": "FEMALE",
  "email": "[e-mail]",
  "phone": "[phone]",
  "mrn": "MRN-00123",
  "status": "ACTIVE",
  "createdAt": "2026-03-19T14:32:00Z",
  "updatedAt": "2026-03-19T14:32:00Z"
}

---

Update Patient

PATCH /patients/{patientId}

Updates one or more fields on a patient record. Only include fields you want to change.

Path Parameters

Parameter	Type	Description
patientId	string	The unique patient ID

Request Body

All fields are optional — include only what you want to change.

Example Request

PATCH /acme/live/patients/pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2
Authorization: Bearer {token}
Content-Type: application/json

{
  "phone": "[phone]",
  "status": "INACTIVE"
}

Example Response

{
  "id": "pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2",
  "firstName": "Jane",
  "lastName": "Doe",
  "birthDate": "1985-06-15",
  "gender": "FEMALE",
  "email": "[e-mail]",
  "phone": "[phone]",
  "mrn": "MRN-00123",
  "status": "INACTIVE",
  "createdAt": "2026-03-19T14:32:00Z",
  "updatedAt": "2026-03-19T15:10:00Z"
}

---

Delete Patient

DELETE /patients/{patientId}

Permanently deletes a patient and all associated records. This action cannot be undone.

Path Parameters

Parameter	Type	Description
patientId	string	The unique patient ID

Example Request

DELETE /acme/live/patients/pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2
Authorization: Bearer {token}

Example Response

HTTP 204 No Content