Assessment Records

Create and manage patient assessment responses.

Assessment Records store patient responses to assessments configured in Welkin Designer. Each record is linked to a patient and corresponds to a specific assessment schema (see Assessment Formation).

Base path: /{tenantName}/{instanceName}/patients/{patientId}/assessment-records

---

Endpoints

POST Create an Assessment Record

POST /{tenantName}/{instanceName}/patients/{patientId}/assessment-records

Creates a new assessment response record for a patient.

Request Body

Field	Type	Required	Description
assessmentName	string	Yes	Name of the assessment as defined in Designer
answers	object	Yes	Key-value pairs of question name → response value
completedAt	string	No	ISO 8601 timestamp of completion

Example Request

POST /acme-health/live/patients/a1b2c3d4/assessment-records
Authorization: Bearer <token>
Content-Type: application/json

{
  "assessmentName": "phq9",
  "answers": {
    "q1": 2,
    "q2": 1,
    "q3": 3
  },
  "completedAt": "2026-03-19T10:30:00Z"
}

Example Response 201 Created

{
  "id": "assess-rec-uuid",
  "patientId": "a1b2c3d4",
  "assessmentName": "phq9",
  "score": 6,
  "completedAt": "2026-03-19T10:30:00Z",
  "createdAt": "2026-03-19T10:30:05Z"
}

---

PUT Update an Assessment Record

PUT /{tenantName}/{instanceName}/patients/{patientId}/assessment-records/{recordId}

Replaces the full set of answers for an assessment record.

---

PUT Update Answers

PUT /{tenantName}/{instanceName}/patients/{patientId}/assessment-records/{recordId}/answers

Updates specific answers within an assessment record without replacing the entire record.

---

GET Get All Assessment Records

GET /{tenantName}/{instanceName}/patients/{patientId}/assessment-records

Returns all assessment records for a patient across all assessment types.

Query Parameters

Parameter	Type	Description
assessmentName	string	Filter by specific assessment name
page	integer	Page number (default: 0)
size	integer	Results per page (default: 20)

---

GET Get an Assessment Record

GET /{tenantName}/{instanceName}/patients/{patientId}/assessment-records/{recordId}

Returns a single assessment record by ID.

---

DELETE Delete an Assessment Record

DELETE /{tenantName}/{instanceName}/patients/{patientId}/assessment-records/{recordId}

Permanently deletes an assessment record.

Response 204 No Content

---

POST Generate Results File

POST /{tenantName}/{instanceName}/patients/{patientId}/assessment-records/{recordId}/generate-results

Generates a PDF or structured results file for a completed assessment record.

Response

Returns a file download URL or binary file content depending on configuration.