Linked Users and Linked Accounts

This guide covers two related but distinct concepts in the Spidr platform:

1. Linked Users: relationships between user records (e.g. guardian/dependent, spouse)
2. Linked Accounts: primary/secondary account relationships, including shared balances

---

Part 1: Linked Users

Overview

Users can be linked to one another to represent real-world relationships. Linkages are bidirectional: when User A is linked to User B, both user records receive a linkedUsers entry. Some linkage types are mirrored (e.g. one side is dependent, the other is guardian), while others are symmetric (e.g. both sides are spouse).

Linkage Types

Spidr supports the following linkage types:

Data Model

Each user record has an optional linkedUsers array. Each entry has the following fields:

API Endpoints

Individual-to-Individual Linkage

Entity Beneficial Owners

Beneficial owner linkage uses a separate set of endpoints:

When a beneficial owner is added, the individual user's linkedUsers array receives a beneficial_owner entry pointing to the entity. The entity stores ownership details (ownershipPercent, prong, cipRequired) in entityDetails.beneficialOwners.

How Linkage CRUD Works

Creating a Linkage at User Creation

When POST /v1/user/create includes primaryUserId and linkageType:

1. The primary user is validated (must exist, not anonymous, not an entity)
2. Linkage type rules are checked (e.g. guardian age requirement)
3. The primary user's linkedUsers gets an entry pointing to the new user
4. The new user is built with a reciprocal linkedUsers entry pointing back to the primary
5. Mirrored types are applied (e.g. if linkageType is dependent, the primary gets guardian)

Adding/Changing a Linkage via Edit

When PATCH /v1/user/:id includes linkedUserId and linkageType:

1. The linked user is validated (must exist, same company, not self, not entity)
2. If no existing linkage exists → add: push new entries on both user records
3. If an existing active linkage exists with a different type → change: archive the old linkage on both sides, then add the new linkage
4. If the same linkage type already exists and is active → no change
5. Separate action records and webhooks are created for both users

Archiving a Linkage

When PATCH /v1/user/:id includes linkedUserId and linkageType: "archive":

1. Sets dateArchived on the linkage entry in both user records
2. The linkage remains in the linkedUsers array but is marked as archived

Business Rules

• Guardian age: The user designated as guardian must be 18 or older
• Dependent age: The user designated as dependent must have a guardian who is 18+
• No self-linking: A user cannot be linked to themselves
• No anonymous users: Anonymous users cannot participate in linkages
• Entity restriction: Linkage changes for entity users must go through the /v1/entity/:id/beneficialOwners endpoint, not PATCH /v1/user/:id
• Beneficial owner cap: Total ownership percentage across non-archived beneficial owners cannot exceed 100%

SST Display

Location

The "Linked Users" tab on the User show page.

Table Columns

Adding a Linked User

The "+" button opens a dialog with:

• Linked User ID: text input for the target user's ObjectId
• Link Type: dropdown with options: dependent, spouse, authorized_user

Note: guardian is not available as an add option; it is automatically set on the reciprocal side when dependent is chosen. beneficial_owner is managed through entity pages.

Changing a Relationship

Clicking the dropdown arrow on the Link Type chip shows a menu listing the other three of the four individual types (dependent, guardian, spouse, authorized_user, minus the current one). The dropdown only appears on active, non-beneficial_owner rows, and only when the SST user has permission to edit the link type.

Archiving

Clicking the dropdown arrow on the Link Status chip shows a menu with a single "archive" option.

Expandable Rows

When the same linked user has multiple linkage history entries (e.g. the type was changed, which archives the old and creates a new one), the most recent linkage is shown as the primary row. Older/archived entries appear as expandable sub-rows.

Permissions

The Compliance and Agent roles cannot add, change, or archive linkages. The CS Manager role can manage linked users.

---

Part 2: Linked Accounts and Shared Balances

Overview

Accounts can be linked in a primary/secondary relationship. A secondary account is always linked to exactly one primary account. When a secondary account has sharedBalance: true, it shares its balance pool with the primary.

Account Variants

Spidr supports four account variants:

How Account Linking Works

There is no dedicated "link account" endpoint. Linking happens at account creation time via POST /v1/account/create:

Eligibility Rules

For a primary account to accept a secondary:

1. Status: Primary must be ACTIVE
2. Not anonymous: Primary must not be an anonymous account
3. Linkable: Primary must not be flagged as non-linkable (controlled via product config)
4. Variant: Primary must be individual.primary or entity.primary
5. Product rules: The primary's product must be configured to permit the secondary's product, and the secondary's product must permit its variant. These product linking rules are configured with Spidr.

Key Account Fields

Shared Balance

• sharedBalance is a boolean set at account creation time
• It can only be true when primaryAccount is provided (i.e., for secondary accounts)
• When true, the secondary account's balance is shared with the primary

linkedAccounts in API Responses

When retrieving an account via GET /v1/account/:id/accountAndCards, the response includes a linkedAccounts array:

Each entry in linkedAccounts:

Note: The bare GET /v1/account/:id does not include linkedAccounts; it returns an accountFeatures array instead. GET /v1/user/:id/userAndAccounts returns the user's own accounts array (a different shape that uses sharedBalance rather than isSharedBalance, with no userId), not linkedAccounts.

Transaction Handling

includeLinkedAccountTxns

The GET /v1/transaction/getTransactions and GET /v1/transaction/getAllTransHistory endpoints accept an includeLinkedAccountTxns query parameter (default: false).

SST Display: Linked Accounts

Location

The "Account & Cards" tab on the Account show page, below the account details and card list. Only visible when the account has linked accounts.

Table Columns

SST Display: Shared Balance

Account Details

For secondary accounts (individual.secondary / entity.secondary), the base account details section shows a "Shared Balance" field with a color-coded chip:

• Yes: green chip
• No: red chip

Transaction Table

The transaction table has several shared-balance-aware features: