> ## Documentation Index
> Fetch the complete documentation index at: https://developer.eka.care/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch Grouped Assessments

> Fetch assessments from both Self-Assessment and Smartcheck modules.


# Fetch and Group Assessments

This API fetches and groups assessments. One can filter using any combination of these properties:
`practitioner_uuid`, `patient_uuid`, `unique_identifier`, `transaction_id` with `status` (default: COMPLETED).

One can also create a New Assessment using [🔗 INIT API](/api-reference/health-ai/assessment/assessment-flow/initialization/initialize-assessment) with any one of these properties.

## Examples

### Example 1: Filtering by Practitioner AND Patient

This request finds all assessment groups for a specific practitioner AND a specific patient. The unique\_identifier can be different for each group.

### Request:

```bash theme={null}
curl ".../v2/?practitioner_uuid=123-doc&patient_uuid=456-patient"
```

### Response:

Notice how both groups in the response match the requested practitioner\_uuid and patient\_uuid.

```json theme={null}
{
  "conversations": [
    {
      "practitioner_uuid": "123-doc",
      "patient_uuid": "456-patient",
      "unique_identifier": "UID-A",
      "transaction_id": "TXN-1",
      "conversations": [
        { "conversationid": "sa_111", "created_at": "...", "wflow_wfid": 101 }
      ]
    },
    {
      "practitioner_uuid": "123-doc",
      "patient_uuid": "456-patient",
      "unique_identifier": "UID-B",
      "transaction_id": "TXN-2",
      "conversations": [
        { "conversationid": "sa_222", "created_at": "...", "wflow_wfid": 101 },
        { "conversationid": "sn_333", "created_at": "...", "wflow_wfid": 205 }
      ]
    }
  ]
}
```

### Example 2: Filtering by a Single Identifier

This request finds all assessment groups that share the same unique\_identifier, regardless of the practitioner or patient.

### Request:

```bash theme={null}
curl ".../v2/?unique_identifier=UID-XYZ"
```

### Response:

Notice how both groups have the same unique\_identifier, but different practitioners and patients.

```json theme={null}
{
  "conversations": [
    {
      "practitioner_uuid": "doc-alpha",
      "patient_uuid": "patient-one",
      "unique_identifier": "UID-XYZ",
      "transaction_id": "TXN-100",
      "conversations": [
        { "conversationid": "sa_777", "created_at": "...", "wflow_wfid": 101 }
      ]
    },
    {
      "practitioner_uuid": "doc-beta",
      "patient_uuid": "patient-two",
      "unique_identifier": "UID-XYZ",
      "transaction_id": "TXN-200",
      "conversations": [
        { "conversationid": "sn_888", "created_at": "...", "wflow_wfid": 101 }
      ]
    }
  ]
}
```

### Example 3: Filtering by UHID via username\_alias

During INIT, patient identifiers are stored as **OIDs** (eka's internal identifier). However, some clients pass their own primary key (e.g., UHID, MRN) during INIT instead of the OID. Use `username_alias` to handle this — set it to the name of the filter field that contains the UHID, and the API will resolve it to the corresponding OID before filtering.

**Supported values:** `practitioner_uuid`, `patient_uuid`, `unique_identifier`, `transaction_id`

> The field named in `username_alias` must also be provided as a query parameter with the UHID value.

### Request:

```bash theme={null}
curl --location 'https://api.eka.care/assessment/api/fetch_interviews/v2/?status=COMPLETED&unique_identifier=abc&username_alias=unique_identifier' \
--header 'Authorization: Bearer <token>'
```

Here `unique_identifier=abc` is the UHID, and `username_alias=unique_identifier` tells the API to resolve it to an OID before filtering.

### Response:

Assessments matching the resolved OID are returned, grouped as usual.

```json theme={null}
{
  "conversations": [
    {
      "practitioner_uuid": "123-doc",
      "patient_uuid": "456-patient",
      "unique_identifier": "<resolved-oid>",
      "transaction_id": "TXN-1",
      "conversations": [
        { "conversationid": "sa_111", "created_at": "...", "wflow_wfid": 101 }
      ]
    }
  ]
}
```

***

### Example 4: Filtering by Workflow IDs

Use `wfids` to fetch only assessments belonging to specific workflows. This is useful when you want results scoped to a particular assessment type (e.g., only diabetes screenings or only general health checks).

### Request:

```bash theme={null}
curl ".../v2/?patient_uuid=456-patient&wfids=101,205"
```

### Response:

Only assessments whose workflow matches one of the provided `wfids` are returned.

```json theme={null}
{
  "conversations": [
    {
      "practitioner_uuid": "123-doc",
      "patient_uuid": "456-patient",
      "unique_identifier": "UID-A",
      "transaction_id": "TXN-1",
      "conversations": [
        { "conversationid": "sa_111", "created_at": "2024-03-01T10:00:00Z", "wflow_wfid": 101 },
        { "conversationid": "sn_999", "created_at": "2024-03-05T14:30:00Z", "wflow_wfid": 205 }
      ]
    }
  ]
}
```

***


## OpenAPI

````yaml get /assessment/api/fetch_interviews/v2/
openapi: 3.0.3
info:
  title: Fetch Assessments V2 API
  version: 2.0.0
servers:
  - description: Production
    url: https://api.eka.care
  - description: Staging
    url: https://api.dev.eka.care
security: []
paths:
  /assessment/api/fetch_interviews/v2/:
    get:
      summary: Fetch Grouped Assessments
      description: |
        Fetch assessments from both Self-Assessment and Smartcheck modules.
      parameters:
        - name: practitioner_uuid
          in: query
          description: The UUID of the practitioner(doctor oid) to filter assessments by.
          required: false
          schema:
            type: string
            example: '161467756044223'
        - name: patient_uuid
          in: query
          description: The UUID of the patient(patient_uuid) to filter assessments by.
          required: false
          schema:
            type: string
            example: 02b66c91-ce53-45b7-8794-14f4a640f9c2
        - name: unique_identifier
          in: query
          description: >
            A unique identifier associated with the assessment. This is
            typically the patient OID (eka's internal identifier) used during
            INIT. If you are passing a UHID or any other external identifier
            instead, set `username_alias=unique_identifier` so the API resolves
            it to the OID before filtering.
          required: false
          schema:
            type: string
            example: '173765761279832'
        - name: transaction_id
          in: query
          description: >
            The transaction ID for a specific assessment session. If this value
            is a UHID or external identifier rather than an OID, set
            `username_alias=transaction_id`.
          required: false
          schema:
            type: string
            example: txn_aBcDeFgHiJkLmNoP
        - name: username_alias
          in: query
          description: >
            Use this when the value of one of the filter fields
            (`practitioner_uuid`, `patient_uuid`, `unique_identifier`, or
            `transaction_id`) is a UHID or external client identifier instead of
            an OID. Set `username_alias` to the name of that field — the API
            will resolve the UHID to the corresponding OID via the patient
            directory before filtering.

            **Example:**
            `?unique_identifier=MRN12345&username_alias=unique_identifier`
          required: false
          schema:
            type: string
            enum:
              - practitioner_uuid
              - patient_uuid
              - unique_identifier
              - transaction_id
            example: unique_identifier
        - name: wfids
          in: query
          description: Comma-separated list of workflow IDs to filter by.
          required: false
          schema:
            type: string
            example: 101,102
        - name: status
          in: query
          description: The status of the assessments to fetch.
          required: false
          schema:
            type: string
            enum:
              - NEW
              - IN_REVIEW
              - COMPLETED
              - PARTIAL
            default: COMPLETED
      responses:
        '200':
          description: A successful response containing the grouped assessments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  conversations:
                    type: array
                    description: A list of assessment groups.
                    items:
                      type: object
                      properties:
                        practitioner_uuid:
                          type: string
                          description: The practitioner UUID for this group.
                        patient_uuid:
                          type: string
                          description: The patient UUID for this group.
                        unique_identifier:
                          type: string
                          description: >
                            The OID stored against this assessment group. When
                            `username_alias` is used, this will be the resolved
                            OID — not the UHID that was passed in.
                        transaction_id:
                          type: string
                          description: The transaction ID for this group.
                        conversations:
                          type: array
                          description: A list of individual assessments within this group.
                          items:
                            type: object
                            properties:
                              conversationid:
                                type: string
                                description: >-
                                  The unique ID for the assessment, prefixed
                                  with 'sa_' or 'sn_'.
                                example: sa_123456789
                              created_at:
                                type: string
                                format: date-time
                                description: The creation timestamp of the assessment.
                                example: '2023-07-15T10:30:00Z'
                              wflow_wfid:
                                type: integer
                                nullable: true
                                description: >-
                                  The workflow ID (wfid) associated with this
                                  assessment.
                                example: 101
              examples:
                default:
                  summary: Filter by OID
                  value:
                    conversations:
                      - practitioner_uuid: '161467756044223'
                        patient_uuid: 02b66c91-ce53-45b7-8794-14f4a640f9g4
                        unique_identifier: '173765761279834'
                        transaction_id: txn_aBcDeFgHiJkLmNoP
                        conversations:
                          - conversationid: sa_123456789
                            created_at: '2023-07-15T10:30:00Z'
                            wflow_wfid: 101
                          - conversationid: sn_987654321
                            created_at: '2023-07-15T10:35:00Z'
                            wflow_wfid: 101
                username_alias:
                  summary: Filter by UHID (username_alias=unique_identifier)
                  value:
                    conversations:
                      - practitioner_uuid: '161467756044223'
                        patient_uuid: 02b66c91-ce53-45b7-8794-14f4a640f9g4
                        unique_identifier: '173765761279834'
                        transaction_id: txn_aBcDeFgHiJkLmNoP
                        conversations:
                          - conversationid: sa_123456789
                            created_at: '2023-07-15T10:30:00Z'
                            wflow_wfid: 101
        '400':
          description: >-
            Validation error, such as a missing required ID in the token or an
            invalid status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: patient_uuid is required.
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: An unexpected error occurred, sit tight, we are fixing..
      security:
        - apiKeyAuth: []
      x-codeSamples:
        - lang: cURL
          label: Filter by OID (default)
          source: |
            curl --request GET \
              --url 'https://api.eka.care/assessment/api/fetch_interviews/v2/?status=COMPLETED&unique_identifier=173765761279834' \
              --header 'Authorization: Bearer <token>'
        - lang: cURL
          label: Filter by UHID (username_alias)
          source: |
            curl --request GET \
              --url 'https://api.eka.care/assessment/api/fetch_interviews/v2/?status=COMPLETED&unique_identifier=MRN12345&username_alias=unique_identifier' \
              --header 'Authorization: Bearer <token>'
components:
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````