Healthcheck Healthservice Connector

This connector retrieves health services, loads questionnaire definitions, and submits questionnaire answers for an authenticated patient. It uses the shared Healthcheck HTTP client together with an authenticated HCLoginClient.

Features

1. List available health services
2. Load questionnaire definitions for a selected health service
3. Submit questionnaire answers
4. Reuse the authenticated login client and shared HttpClient

Installation

npm install @healthcloudai/hc-healthservice-connector \
@healthcloudai/hc-login-connector \
@healthcloudai/hc-http

Import

import { HCHealthserviceClient } from "@healthcloudai/hc-healthservice-connector";
import { HCLoginClient } from "@healthcloudai/hc-login-connector";
import { FetchClient } from "@healthcloudai/hc-http";

Usage

Configuration

const httpClient = new FetchClient();
const authClient = new HCLoginClient(httpClient);

authClient.configure("demo-tenant", "dev");
await authClient.login("[email protected]", "ExamplePassword123!");

const healthserviceClient = new HCHealthserviceClient(
  httpClient,
  authClient
);

Reuse the same authenticated HCLoginClient instance when creating HCHealthserviceClient so both connectors share the same auth state.

API Key

Use setApiKey(...) to attach an API key header to requests from HCHealthserviceClient.

const apiKey = process.env.HEALTHCLOUD_API_KEY;

if (!apiKey) {
  throw new Error("HEALTHCLOUD_API_KEY is required.");
}

healthserviceClient.setApiKey("x-api-key", apiKey);

• Header name should be x-api-key.

Methods

The Healthservice connector follows a simple questionnaire flow:

1. Retrieve available health services.
2. Load the questionnaire for the selected health service.
3. Submit the completed questionnaire payload.

Get Health Services

Public signature: healthserviceClient.getHealthservices()

Returns the health services available for the authenticated patient.

const services = await healthserviceClient.getHealthservices();

Full API request

This method performs an authenticated request internally and does not send a request body.

API response

Status:

200

{
  "Data": [
    {
      "ID": "health-service-id-example",
      "Name": "Oral Herpes (Cold Sores)",
      "ScreeningSNOMEDCode": null,
      "Description": "Example health service description.",
      "ImageURL": "data:image/png;base64,image-data-example",
      "IntroImageURL": null,
      "Category": "Urgent Care",
      "CQLID": null,
      "CQL": null,
      "Documents": [
        "example-document.pdf"
      ],
      "Reasons": [
        {
          "ID": "reason-id-example",
          "Name": "Oral Herpes (Cold Sores)"
        }
      ],
      "Outcomes": [],
      "AlternativeKBSummary": "Example knowledge-base summary text.",
      "ScreeningGenerationAdditionalInstructions": null,
      "CQLGenerationAdditionalInstructions": null,
      "AgentID": null,
      "AdditionalAgentInstructions": null,
      "SelectedAccountIDs": [
        "account-id-example-1",
        "account-id-example-2"
      ],
      "TenantID": null
    }
  ],
  "ErrorMessage": null,
  "IsOK": true
}

Get Questionnaire for Health Service

Public signature: healthserviceClient.getQuestionnaire(healthServiceId)

Retrieves the questionnaire definition for a selected health service. Use the returned questionnaire structure to render questions and prepare the answer payload for submission.

const questionnaire = await healthserviceClient.getQuestionnaire(
  "health-service-id-example"
);

Full API request

This method performs an authenticated request internally and does not send a request body. The client places healthServiceId in the request path.

API response

Status:

200

{
  "Data": {
    "ID": "health-service-id-example",
    "HealthServiceID": "health-service-id-example",
    "AgentID": null,
    "Title": "Oral Herpes (Cold Sores)",
    "Note": null,
    "HPI": null,
    "Questions": [
      {
        "Question": "Are you currently diagnosed with Oral Herpes?",
        "ID": "Q1",
        "Type": "Boolean",
        "Default": "",
        "Description": null,
        "Next": "Q2",
        "Outcome": null,
        "PossibleAnswers": [],
        "ActualAnswers": null,
        "ImageURLs": null
      },
      {
        "Question": "Have you experienced painful blisters or sores around your mouth?",
        "ID": "Q2",
        "Type": "SingleSelect",
        "Default": "",
        "Description": null,
        "Next": "",
        "Outcome": null,
        "PossibleAnswers": [
          {
            "Text": "Yes",
            "Next": "Q2a",
            "Outcome": null
          },
          {
            "Text": "No",
            "Next": "Q2b",
            "Outcome": null
          }
        ],
        "ActualAnswers": null,
        "ImageURLs": null
      }
    ],
    "Outcome": [
      {
        "Message": "Based on the information you provided, we suggest you schedule a Telehealth appointment with a provider.",
        "Action": "patient/book-appointment",
        "Value": 0,
        "IsDefault": false,
        "ID": null,
        "EncounterID": null
      }
    ],
    "Reasons": [
      {
        "ID": "reason-id-example",
        "Name": "Oral Herpes (Cold Sores)"
      }
    ]
  },
  "ErrorMessage": "",
  "IsOK": true
}

Submit Questionnaire

Public signature: healthserviceClient.submitQuestionnaire(payload)

Submits questionnaire answers for the selected health service. Build the payload from the questionnaire structure returned by getQuestionnaire(). The connector wraps the provided payload in the expected request body before sending it.

await healthserviceClient.submitQuestionnaire({
  Title: "Oral Herpes (Cold Sores)",
  HealthServiceID: "health-service-id-example",
  Questions: [
    {
      Question: "What is your age?",
      ActualAnswers: [
        {
          FHIRID: "",
          Text: "51",
          Outcome: ""
        }
      ]
    },
    {
      Question: "Have you experienced painful blisters or sores around your mouth?",
      ActualAnswers: [
        {
          FHIRID: "",
          Text: "No",
          Outcome: null
        }
      ]
    }
  ],
  Reasons: [
    {
      ID: "reason-id-example",
      Name: "Oral Herpes (Cold Sores)"
    }
  ],
  HPI: ""
});

Full API request

{
  "Data": {
    "Title": "Oral Herpes (Cold Sores)",
    "HealthServiceID": "health-service-id-example",
    "Questions": [
      {
        "Question": "What is your age?",
        "ActualAnswers": [
          {
            "FHIRID": "",
            "Text": "51",
            "Outcome": ""
          }
        ]
      },
      {
        "Question": "Have you experienced painful blisters or sores around your mouth?",
        "ActualAnswers": [
          {
            "FHIRID": "",
            "Text": "No",
            "Outcome": null
          }
        ]
      }
    ],
    "Reasons": [
      {
        "ID": "reason-id-example",
        "Name": "Oral Herpes (Cold Sores)"
      }
    ],
    "HPI": ""
  }
}

API response

Status:

200

{
  "Data": {
    "Message": "",
    "Action": null,
    "Value": 0,
    "IsDefault": false,
    "ID": "record-id-example",
    "EncounterID": "encounter-id-example"
  },
  "ErrorMessage": null,
  "IsOK": true
}

How It Works

• HCLoginClient handles tenant configuration, login, and authenticated headers.
• HCHealthserviceClient uses the authenticated login client for the base API URL and request headers.
• Typical usage is: fetch available health services, fetch the questionnaire for the selected service, render the questionnaire, then submit the completed answer payload.
• submitQuestionnaire() wraps the provided payload inside the request Data object before sending it.
• getHealthservices() and getQuestionnaire() perform authenticated requests without a request body.

Notes

• HCLoginClient must be configured and logged in before calling Healthservice connector methods.
• Reuse the same authenticated HCLoginClient instance when constructing HCHealthserviceClient.
• getHealthservices() returns the list of available health services for the authenticated patient.
• getQuestionnaire() returns the questionnaire structure that should drive UI rendering.
• submitQuestionnaire() expects a payload prepared from the questionnaire structure returned by getQuestionnaire().
• getHealthservices() and getQuestionnaire() do not require the caller to build a request body.