Dependents Connector

This connector handles authenticated dependent person retrieval and dependent updates for the active patient session.

HCDependentsClient uses the active authenticated session from HCLoginClient, so dependent requests do not require a separate authentication setup.

The resources in this section follow the dependent management workflow from retrieving the patient's current dependents through updating dependent person records.

Node.js Package

@healthcloudai/hc-dependents-connector

Client

HCDependentsClient

Authentication

Reuses the authenticated patient session from HCLoginClient.

Features

1. Retrieve dependent persons for the authenticated patient
2. Update dependent persons for the authenticated patient
3. Reuse the authenticated login client for headers and base URL
4. Optionally attach API key headers to Dependents connector requests

Setup

Configure and authenticate HCLoginClient before passing it into HCDependentsClient.

Reuse the same authenticated HCLoginClient instance so both connectors share the same authentication state.

const httpClient = new FetchClient();

const authClient = new HCLoginClient(
  httpClient
);

authClient.configure(
  "healthcheck",
  "dev"
);

await authClient.login(
  "<PATIENT_EMAIL>",
  "ExamplePassword123!"
);

const dependentsClient =
  new HCDependentsClient(
    httpClient,
    authClient
  );

API Key

Use setApiKey(...) to attach an API key header to Dependents connector requests.

const apiKey =
  process.env.HEALTHCLOUD_API_KEY;

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

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

Parameters

| Parameter | Type | Description | | ------------ | -------- | ------------------- | | headerName | string | API key header name | | value | string | API key value |

Notes

• Header name should typically be x-api-key.
• API key headers are attached only to Dependents connector requests.

Resources

Get Dependents

Method Signature

dependentsClient.listDependents(): Promise<
  APIResponse<DependentPerson[]>
>

Behavior

Sends an authenticated GET request and returns dependent persons for the authenticated patient.

Does not send a request body.

Returns

Returns a raw backend response:

APIResponse<DependentPerson[]>

Usage

const response =
  await dependentsClient.listDependents();

if (!response.IsOK) {
  console.error(
    response.ErrorMessage
  );

  return;
}

console.log(response.Data);

API Response

{
  "Data": [
    {
      "FirstName": "Jane",
      "LastName": "Doe",
      "BirthDate": "01/01/2015",
      "Relationship": "Child"
    }
  ],
  "IsOK": true,
  "ErrorMessage": null
}

Notes

• The connector preserves the raw backend response contract.
• The API returns dependent person records inside the Data field.

Update Dependents

Method Signature

dependentsClient.updateDependents(
  dependents: DependentPerson[]
): Promise<
  APIResponse<boolean>
>

Behavior

Sends an authenticated PUT request and updates dependent persons for the authenticated patient.

Parameters

| Parameter | Type | Description | | ------------ | ------------------- | ------------------------ | | dependents | DependentPerson[] | Dependent person records |

Payload Fields (Sent Inside Data)

| Field | Type | Required | | -------------- | -------- | -------- | | FirstName | string | Yes | | LastName | string | Yes | | BirthDate | string | Yes | | Relationship | string | Yes |

Returns

Returns a raw backend response:

APIResponse<boolean>

Usage

const response =
  await dependentsClient.updateDependents([
    {
      FirstName: "Jane",
      LastName: "Doe",
      BirthDate: "01/01/2015",
      Relationship: "Child"
    }
  ]);

if (!response.IsOK) {
  console.error(
    response.ErrorMessage
  );

  return;
}

console.log(response.Data);

API Request

{
  "Data": [
    {
      "FirstName": "Jane",
      "LastName": "Doe",
      "BirthDate": "01/01/2015",
      "Relationship": "Child"
    }
  ]
}

API Response

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

Notes

• HCLoginClient must be configured and authenticated before calling Dependents connector methods.

• Reuse the same authenticated HCLoginClient instance when constructing HCDependentsClient.

• Public SDK methods do not require consumers to manually provide:

  • Data wrappers
  • authorization headers
  • tenant identifiers
  • resolved service URLs

• The connector returns raw backend APIResponse<T> responses without response transformation or unwrapping.

• Backend-defined failure responses remain part of the returned API contract.

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);
  }
}