# Assessment Records

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](/developer-and-integration-guide/api-reference/assessment-formation.md)).

**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

```http
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`

```json
{
  "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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.welkinhealth.com/developer-and-integration-guide/api-reference/assessment-records.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.