Healthcheck Settings Connector

This library provides a client for authenticated user settings, profile image, identification, insurance, and dashboard-related flows in Healthcheck. It is built on top of the shared Healthcheck HTTP and Login connectors.

Features

1. Retrieve the authenticated patient dashboard
2. Generate canned upload URLs for selfie, ID, and insurance images
3. Submit uploaded identification and insurance file keys for capture
4. Submit patient insurance coverage details
5. Retrieve patient insurances
6. Submit driving license data
7. Update the stored user image file reference
8. Deactivate the authenticated user
9. Built on the shared Healthcheck HttpClient and authentication layer

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 authClient = new HCLoginClient(httpClient);

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

const settingsClient = new HCSettingsClient(
  httpClient,
  authClient
);

API Key

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

const apiKey = process.env.HEALTHCLOUD_API_KEY;

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

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

• Header name should be x-api-key.

Methods

The Settings connector methods are grouped by the main usage flow:

1. Dashboard
2. Profile image upload and update
3. ID document upload, capture, and submit
4. Insurance upload, capture, submit, and retrieval
5. Account actions

Dashboard methods

Get Dashboard

Public signature: settingsClient.getDashboard()

Returns the authenticated patient dashboard.

const dashboard = await settingsClient.getDashboard();

Full API request

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

API response

Status:

200

{
  "Data": {
    "Record": {
      "Status": 0,
      "Sex": "Male",
      "GenderIdentity": "Male",
      "HasInsurance": true,
      "HasIDCard": true,
      "HasSelfie": true,
      "Flags": {
        "IsVerified": "true",
        "NeedsInsurance": "false"
      }
    },
    "Encounters": [
      {
        "FHIRID": "test-fhir-id-001",
        "AthenaID": "test-athena-id-001",
        "Status": 0,
        "Patient": null,
        "EncounterClass": "ambulatory",
        "EHR": "athena",
        "EHRType": "Athena Health",
        "EHRVisitName": "Office Visit",
        "EHRAppointmentID": "test-appointment-id-001",
        "EHRProviderID": "test-provider-id-001",
        "EHRProviderName": "Test Provider",
        "EHRDate": "04/22/2026",
        "EHRStatus": "Finished",
        "EHRStage": "completed"
      }
    ],
    "EHR": "athena",
    "PendingActions": [
      "ADD_INSURANCE",
      "ADD_ID",
      "IMPORT_VITALS"
    ]
  },
  "IsOK": true,
  "ErrorMessage": null
}

Upload and capture flow

Image-related methods follow an upload-first flow. Profile image uses updateUserImage(...) after upload, while driver license and insurance use capture methods after upload.

1. Request upload information by calling the matching canned URL method.
2. Upload the file bytes to the returned upload URL outside this package.
3. Include any signed headers required by the upload URL, such as x-amz-acl: public-read when provided.
4. Submit the returned file name or file key through the matching capture or update method.

The connector does not upload file bytes. It requests upload information and then submits the uploaded file reference after the upload is complete.

Profile image methods

Profile image methods follow this flow:

1. Call getUserImageCannedUrl(extension) to request upload information.
2. Upload the image file to the returned ImageURL outside this package.
3. Include any signed headers required by the upload URL, such as x-amz-acl: public-read when provided.
4. Call updateUserImage(fileName) using the returned FileName.

Get User Image Canned URL

Public signature: settingsClient.getUserImageCannedUrl(extension)

Generates upload information for a user profile image.

Use the returned ImageURL to upload the image file outside this package. After upload, pass the returned FileName to updateUserImage(...).

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

Full API request

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

API response

Status:

200

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

Update User Image URL

Public signature: settingsClient.updateUserImage(fileName)

Updates the stored user image reference using the FileName returned by getUserImageCannedUrl(...).

Call this method after uploading the image file to the returned ImageURL.

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

Full API request

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

API response

Status:

200

true

ID document methods

Get Driving License Canned URL

Public signature: settingsClient.getDrivingLicenseCannedUrl(extension)

Generates upload information for an ID document image.

Use the returned upload information to upload the image file outside this package. If the upload URL requires signed headers, include them in the upload request.

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

Full API request

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

API response

Status:

200

{
  "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)

Submits the uploaded ID document file key after the image has been uploaded.

This method should be called after uploading the file using the upload information returned by getDrivingLicenseCannedUrl(...).

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

Full API request

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

API response

Status:

200

{
  "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(payload)

Submits patient driving license data.

const response = await settingsClient.submitDrivingLicense({
  Image: "idcard_example.jpeg"
});

Full API request

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

API response

Status:

200

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

Insurance methods

Get Insurance Canned URL

Public signature: settingsClient.getInsuranceCannedUrl(extension)

Generates upload information for an insurance card image.

Use the returned upload information to upload the image file outside this package. If the upload URL requires signed headers, include them in the upload request.

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

Full API request

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

API response

Status:

200

{
  "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)

Submits the uploaded insurance file key after the image has been uploaded.

This method should be called after uploading the file using the upload information returned by getInsuranceCannedUrl(...).

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

Full API request

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

API response

Status:

200

{
  "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(payload)

Submits patient insurance coverage details.

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

Full API request

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

API response

Status:

200

{
  "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.getInsurances()

Returns patient insurances.

const insurances = await settingsClient.getInsurances();

Full API request

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

API response

Status:

200

{
  "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
}

Account methods

Deactivate User

Public signature: settingsClient.deactivateUser()

Deactivates the current authenticated user.

await settingsClient.deactivateUser();

Full API request

{
  "Data": {}
}

API response

The client returns the backend response from the authenticated request.

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

How It Works

• HCLoginClient handles tenant configuration, authentication, and authenticated headers.
• HCSettingsClient uses the authenticated login client for the base API URL and authenticated request headers.
• If configured through setApiKey(...), HCSettingsClient also includes its configured API key header with Settings connector requests.
• Profile image methods use getUserImageCannedUrl(...) to request upload information and updateUserImage(...) to store the uploaded image reference.
• Upload URL methods return generated upload information. The caller is responsible for uploading the actual file bytes outside this package.
• Driver license and insurance capture methods submit the uploaded file key after the file has already been uploaded.

Notes

• HCLoginClient must be configured and logged in before calling Settings connector methods.
• Canned URL methods return the backend response containing upload information in Data.
• Profile image upload uses getUserImageCannedUrl(...) followed by updateUserImage(...).
• After requesting upload information, the file must be uploaded outside this package before capture methods can succeed.
• When uploading to the returned storage URL, include any signed headers required by that URL, such as x-amz-acl: public-read when provided.
• captureDrivingLicense() sends the ID document file key using Type: "identification" and FileID inside the request body.
• captureInsurance() sends Type: "healthinsurance" and FileID inside the request body.
• submitDrivingLicense() submits the driving license data payload.