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. Capture registration documents before the patient is authenticated.
7. 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 before creating the Settings client. Most Settings methods require an authenticated patient session. getRegistrationDocumentCannedUrl(...) and captureRegistrationDocument(...) are intended for unauthenticated registration flows and do not send the auth token.

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
}

Registration Document Capture

Registration document capture is used during registration, before the user is authenticated. It sends the same capture request shape as patient capture, but it does not attach the patient authorization token.

The full unauthenticated registration document flow is:

1. getRegistrationDocumentCannedUrl(documentType, extension) — get a presigned upload URL and a fileKey (FileName), without an auth token.
2. Upload the file directly to the returned ImageURL (PUT, with the x-amz-acl: public-read header — see warning below).
3. captureRegistrationDocument(fileKey, type) — submit the uploaded file's fileKey for OCR capture, also without an auth token.

Get Registration Document Canned URL

Public signature:

settingsClient.getRegistrationDocumentCannedUrl(
  documentType,
  extension
)

documentType must be one of:

"identification" | "healthinsurance"

Returns a presigned upload URL (ImageURL) and a storage FileName (used as the fileKey for captureRegistrationDocument), without sending the patient auth token. Only loginClient.configure(...) is required.

const response =
  await settingsClient.getRegistrationDocumentCannedUrl(
    "identification",
    "png"
  );

console.log(response.Data?.ImageURL, response.Data?.FileName);

⚠️ You MUST send the x-amz-acl: public-read header on the upload PUT request. The presigned ImageURL is signed with an x-amz-acl: public-read header included in the signature. If your upload request to that URL omits this exact header, S3 recalculates a different signature and rejects the upload with:

<Error>
  <Code>SignatureDoesNotMatch</Code>
  <Message>The request signature we calculated does not match the signature you provided. Check your key and signing method.</Message>
  ...
</Error>

Example upload (must include the header):

await fetch(response.Data!.ImageURL!, {
  method: "PUT",
  headers: {
    "Content-Type": "image/png",
    "x-amz-acl": "public-read",
  },
  body: fileBytes,
});

API request

{
  "Data": {
    "Extension": "png"
  }
}

API response

{
  "Data": {
    "ImageURL": "https://storage.example.com/idcard_example.png?X-Amz-Expires=300&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=example&X-Amz-Date=example&X-Amz-SignedHeaders=host%3Bx-amz-acl&X-Amz-Signature=example",
    "FileName": "idcard_example.png",
    "Extension": "png"
  },
  "ErrorMessage": null,
  "IsOK": true
}

Capture Registration Document

Public signature:

settingsClient.captureRegistrationDocument(
  fileKey,
  type
)

type must be one of:

"identification" | "healthinsurance"

Only loginClient.configure(...) is required for this method so the connector can resolve the API base URL.

const response =
  await settingsClient.captureRegistrationDocument(
    "idcard_example.jpeg",
    "identification"
  );

console.log(response);

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
}

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".
• getRegistrationDocumentCannedUrl(...) and captureRegistrationDocument(...) do not send the patient auth token.
• The ImageURL returned by getRegistrationDocumentCannedUrl(...) is signed with x-amz-acl: public-read — your upload PUT request must include that exact header or S3 rejects it with SignatureDoesNotMatch. See Get Registration Document Canned URL.

Prerequisites

HCLoginClient must be configured before using this connector. Most methods require the patient to be logged in. getRegistrationDocumentCannedUrl(...) and captureRegistrationDocument(...) are the unauthenticated exceptions — they do not send the auth token.

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.