Healthcheck Settings Connector

This connector gives authenticated patients access to account information and document flows used in your application. It includes dashboard information, profile image management, identification document processing, insurance information, and account deactivation.

HCSettingsClient reuses the configured and authenticated HCLoginClient for the API base URL and authorization context.

Features

1. Retrieve dashboard information for the authenticated patient.
2. Request upload information for patient profile and document images.
3. Submit uploaded identification and insurance images for capture.
4. Submit and retrieve insurance information.
5. Update the patient profile image.
6. Deactivate the authenticated patient account.

Installation

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

Import

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

Usage

Configuration

const httpClient = new FetchClient();

const loginClient = new HCLoginClient(httpClient);

loginClient.configure("demo-tenant", "dev");

await loginClient.login(
  "[email protected]",
  "ExamplePassword123!"
);

const settingsClient = new HCSettingsClient(
  httpClient,
  loginClient
);

HCLoginClient must be configured and authenticated before calling Settings methods.

API Key

Use setApiKey(...) when the configured environment requires an API key for Settings requests.

const apiKey = process.env.HEALTHCLOUD_API_KEY;

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

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

The API key header name should be x-api-key.

Methods

Dashboard

Get Dashboard

Public signature:

settingsClient.getDashboard()

Returns dashboard information associated with the authenticated patient.

const dashboard =
  await settingsClient.getDashboard();

console.log(dashboard);

API response

{
  "Data": {
    "Record": {
      "Status": 1,
      "Sex": "Male",
      "GenderIdentity": "Male",
      "HasInsurance": true,
      "HasIDCard": true,
      "HasSelfie": true,
      "Flags": null,
      "FirstName": "John",
      "LastName": "Smith",
      "MiddleName": null,
      "BirthDate": "1990-01-01T00:00:00",
      "Email": "[email protected]",
      "Phone": "+15555550123",
      "Gender": "Male",
      "Race": "White",
      "Ethnicity": "",
      "CRMID": null,
      "AppleUserId": null,
      "Address": {
        "StreetAndNumber": "1 Main St",
        "Extension": null,
        "City": "Springfield",
        "State": "IL",
        "PostalCode": "62701",
        "Country": "US"
      },
      "Attributes": {
        "AthenaPatientID": "patient-id-example",
        "AthenaGuarantorFirstName": "John",
        "AthenaGuarantorLastName": "Smith",
        "AthenaCountryCode": "USA",
        "AthenaDepartmentId": "1",
        "AthenaEmailExists": "True",
        "AthenaTestPatient": "False",
        "PatientImageURL": "https://storage.example.com/selfie_example.jpg",
        "CompositeID": "tenant-id/[email protected]",
        "Insurance": "EXAMPLE INSURANCE"
      },
      "CompositeID": "tenant-id/[email protected]",
      "FHIRID": "fhir-id-example",
      "AthenaID": "patient-id-example",
      "Created": "0001-01-01T00:00:00",
      "Modified": "0001-01-01T00:00:00",
      "CreatedByID": null,
      "ModifiedByID": null,
      "IsDeactivated": false,
      "TenantID": "test-tenant",
      "ID": "record-uuid-example"
    },
    "Encounters": null,
    "EHR": "athena",
    "PendingActions": [
      "TAKE_TEST"
    ]
  },
  "IsOK": true,
  "ErrorMessage": null
}

User Image

User image methods allow the patient to upload and update the profile image associated with their account.

Get User Image Canned URL

Public signature:

settingsClient.getUserImageCannedUrl(
  extension
)

Returns upload information for a patient profile image.

const upload =
  await settingsClient.getUserImageCannedUrl(
    "jpeg"
  );

console.log(upload);

API request

{
  "Data": {
    "Extension": "jpeg"
  }
}

API response

{
  "Data": {
    "ImageURL": "https://storage.example.com/selfie_example.jpeg?signature=example",
    "FileName": "selfie_example.jpeg",
    "Extension": "jpeg"
  },
  "ErrorMessage": null,
  "IsOK": true
}

Update User Image

Public signature:

settingsClient.updateUserImage(
  fileName
)

Updates the patient profile image using the uploaded image reference.

const updated =
  await settingsClient.updateUserImage(
    "selfie_example.jpeg"
  );

console.log(updated);

API request

{
  "Data": {
    "FileName": "selfie_example.jpeg"
  }
}

API response

{
  "Data": true,
  "IsOK": true,
  "ErrorMessage": null
}

Identification

Identification methods allow the patient to upload and process identification document images.

Get Driving License Canned URL

Public signature:

settingsClient.getDrivingLicenseCannedUrl(
  extension
)

Returns upload information for an identification document image.

const upload =
  await settingsClient.getDrivingLicenseCannedUrl(
    "jpeg"
  );

console.log(upload);

API request

{
  "Data": {
    "Extension": "jpeg"
  }
}

API response

{
  "Data": {
    "ImageURL": "https://storage.example.com/idcard_example.jpeg?signature=example",
    "FileName": "idcard_example.jpeg",
    "Extension": "jpeg"
  },
  "ErrorMessage": null,
  "IsOK": true
}

Capture Driving License

Public signature:

settingsClient.captureDrivingLicense(
  fileKey
)

Processes the uploaded identification image and returns captured information.

const captured =
  await settingsClient.captureDrivingLicense(
    "idcard_example.jpeg"
  );

console.log(captured);

API request

{
  "Data": {
    "Type": "identification",
    "FileID": "idcard_example.jpeg"
  }
}

API response

{
  "Data": {
    "CapturedData": {
      "FirstName": "John",
      "LastName": "Doe",
      "StreetAddress": "123 Main St",
      "City": "Springfield",
      "ZipCode": "90210",
      "State": "California",
      "IssuedDate": "01/01/2024",
      "ExpiresDate": "01/01/2028",
      "Dob": "01/01/1990",
      "IDNumber": null
    },
    "IsCaptured": true,
    "InsurancePackages": null
  },
  "ErrorMessage": null,
  "IsOK": true
}

Submit Driving License

Public signature:

settingsClient.submitDrivingLicense(
  image
)

Submits the uploaded identification image reference.

const response =
  await settingsClient.submitDrivingLicense(
    "idcard_example.jpeg"
  );

console.log(response);

API request

{
  "Data": {
    "Image": "idcard_example.jpeg"
  }
}

API response

{
  "Data": "true",
  "ErrorMessage": null,
  "IsOK": true
}

Insurance

Insurance methods allow the patient to upload insurance images, process insurance information, and retrieve insurance records.

Get Insurance Canned URL

Public signature:

settingsClient.getInsuranceCannedUrl(
  extension
)

Returns upload information for an insurance image.

const upload =
  await settingsClient.getInsuranceCannedUrl(
    "jpeg"
  );

console.log(upload);

API request

{
  "Data": {
    "Extension": "jpeg"
  }
}

API response

{
  "Data": {
    "ImageURL": "https://storage.example.com/insurancecard_example.jpeg?signature=example",
    "FileName": "insurancecard_example.jpeg",
    "Extension": "jpeg"
  },
  "ErrorMessage": null,
  "IsOK": true
}

Capture Insurance

Public signature:

settingsClient.captureInsurance(
  fileKey
)

Processes the uploaded insurance image and returns captured information.

const captured =
  await settingsClient.captureInsurance(
    "insurancecard_example.jpeg"
  );

console.log(captured);

API request

{
  "Data": {
    "Type": "healthinsurance",
    "FileID": "insurancecard_example.jpeg"
  }
}

API response

{
  "Data": {
    "CapturedData": {
      "FirstName": "John",
      "LastName": "Doe",
      "MemberId": "member-id-example",
      "GroupNumber": "group-number-example",
      "EffectiveDate": "",
      "RxBIN": "",
      "RxPCN": "",
      "RxGRP": "",
      "Carrier": "Carrier Example"
    },
    "IsCaptured": true,
    "InsurancePackages": null
  },
  "ErrorMessage": null,
  "IsOK": true
}

Submit Insurance

Public signature:

settingsClient.submitInsurance(
  coverage
)

Submits insurance coverage information for the authenticated patient.

const response =
  await settingsClient.submitInsurance({
    InsurancePackageId: "693245",
    MemberId: "member-id-example",
    FirstName: "John",
    LastName: "Doe",
    Sex: "",
    Image: "insurancecard_example.jpeg"
  });

console.log(response);

API request

{
  "Data": {
    "InsurancePackageId": "693245",
    "MemberId": "member-id-example",
    "FirstName": "John",
    "LastName": "Doe",
    "Sex": "",
    "Image": "insurancecard_example.jpeg"
  }
}

API response

{
  "Data": {
    "InsuranceId": "insurance-id-example",
    "InsurancePackageId": 693245,
    "InsurancePolicyHolder": "John Doe",
    "InsuranceType": "Insurance",
    "IssueDate": "01/01/2030",
    "MemberId": "member-id-example",
    "Image": "insurancecard_example.jpeg"
  },
  "ErrorMessage": null,
  "IsOK": true
}

Get Insurances

Public signature:

settingsClient.listInsurances()

Returns insurance records associated with the authenticated patient.

const insurances =
  await settingsClient.listInsurances();

console.log(insurances);

API response

{
  "Data": [
    {
      "InsuranceId": "insurance-id-example",
      "InsurancePackageId": 693245,
      "InsurancePolicyHolderFirstName": "John",
      "InsurancePolicyHolderLastName": "Doe",
      "InsurancePolicyHolder": "John Doe",
      "RelationshipToInsured": "Self",
      "EligibilityStatus": "Active",
      "InsurancePlanName": " - ",
      "InsuranceType": "FHIR",
      "MemberId": "member-id-example",
      "Image": "insurancecard_example.jpeg"
    }
  ],
  "ErrorMessage": null,
  "IsOK": true
}

User Photo Capture

User photo capture methods process uploaded patient profile images.

Capture User Photo

Public signature:

settingsClient.captureUserPhoto(
  fileKey
)

Processes the uploaded patient profile image and stores it as the patient user image.

const response =
  await settingsClient.captureUserPhoto(
    "selfie_example.jpeg"
  );

console.log(response);

API request

{
  "Data": {
    "Type": "userphoto",
    "FileID": "selfie_example.jpeg"
  }
}

API response

{
  "Data": {
    "CapturedData": {
      "ImageKey": "patient-image-example.jpeg"
    },
    "IsCaptured": true,
    "InsurancePackages": null
  },
  "ErrorMessage": null,
  "IsOK": true
}

Account

Deactivate User

Public signature:

settingsClient.deactivateUser()

Deactivates the authenticated patient account.

const response =
  await settingsClient.deactivateUser();

console.log(response);

API response

{
  "Data": true,
  "IsOK": true,
  "ErrorMessage": null
}

How It Works

• HCSettingsClient uses the configured HCLoginClient for the API base URL and authorization context.
• Public methods only accept the values required from the application.
• The connector internally creates the backend APIRequest<T> request envelope.
• Image upload methods return upload information only. File uploads are performed outside the connector.
• Capture methods internally attach the required capture type before sending the request.

Notes

• Configure and authenticate HCLoginClient before calling Settings methods.
• Do not pass authorization headers or base URLs manually.
• Upload image files outside the connector using the returned upload URL.
• captureDrivingLicense(...) internally sends Type: "identification".
• captureInsurance(...) internally sends Type: "healthinsurance".
• captureUserPhoto(...) internally sends Type: "userphoto".

Prerequisites

HCLoginClient must be configured and the patient must be logged in before calling any method on this connector.

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

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

loginClient.configure("healthcheck", "dev");
await loginClient.login("[email protected]", "ExamplePassword123!");

See the hc-login-connector documentation for the full authentication flow.

Error Handling

All methods throw errors that extend APIError from @healthcloudai/hc-http.

Backend business failures (IsOK: false) are thrown as HCServiceError.

import { HCServiceError, APIError } from "@healthcloudai/hc-http";

try {
  const result = await client.someMethod();
} catch (err) {
  if (err instanceof HCServiceError) {
    console.error("Backend error:", err.backendMessage);
  } else if (err instanceof APIError) {
    console.error("SDK error:", err.message, err.code);
  }
}

getDashboard vs getPatientHeader

HCSettingsClient.getDashboard() calls /api/patient/dashboard and returns a full patient dashboard including record, encounters, EHR type, and pending actions.

HCLoginClient.getPatientHeader() calls /api/patient/header and returns a lighter patient header used after login to quickly check patient state.

These are different endpoints returning different data shapes. Neither is a duplicate of the other.