Skip to main content
GET
/
assessment
/
api
/
fetch_interviews
/
v2
/
curl --request GET \
  --url 'https://api.eka.care/assessment/api/fetch_interviews/v2/?status=COMPLETED&unique_identifier=173765761279834' \
  --header 'Authorization: Bearer <token>'
{
  "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
        }
      ]
    }
  ]
}

​
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 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:

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. 
{
  "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:

curl ".../v2/?unique_identifier=UID-XYZ"

​
Response:

Notice how both groups have the same unique_identifier, but different practitioners and patients. 
{
  "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:

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. 
{
  "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:

curl ".../v2/?patient_uuid=456-patient&wfids=101,205"

​
Response:

Only assessments whose workflow matches one of the provided wfids are returned. 
{
  "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 }
      ]
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
practitioner_uuid
string

The UUID of the practitioner(doctor oid) to filter assessments by.

Example:

"161467756044223"

​
patient_uuid
string

The UUID of the patient(patient_uuid) to filter assessments by.

Example:

"02b66c91-ce53-45b7-8794-14f4a640f9c2"

​
unique_identifier
string

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.

Example:

"173765761279832"

​
transaction_id
string

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.

Example:

"txn_aBcDeFgHiJkLmNoP"

​
username_alias
enum<string>

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

Available options:
practitioner_uuid,
patient_uuid,
unique_identifier,
transaction_id
Example:

"unique_identifier"

​
wfids
string

Comma-separated list of workflow IDs to filter by.

Example:

"101,102"

​
status
enum<string>
default:COMPLETED

The status of the assessments to fetch.

Available options:
NEW,
IN_REVIEW,
COMPLETED,
PARTIAL

Response

A successful response containing the grouped assessments.

​
conversations
object[]

A list of assessment groups.