Households

A household groups the accounts of one family or client that your firm manages together, with the people who belong to it. A household has a model, trade proposal and tolerance settings, billing settings and security restrictions, and it can be linked to a household record in your firm's CRM. The console shows households on the Households tab of the Clients page.

A household is active until its archiveDate. List households returns active households unless you send include-inactive=true. Fields that come from the household's CRM records, such as its tags, tasks and contact information, are filled only when you send crm=true.

The holdings, performance, risk allocation, asset allocation and notes of a household are operations of this tag. To create a task, a workflow or a note, link the household to a CRM record first; see Household data connections.

📄️List households

Returns your firm's active households, in order of name. Send `include-inactive=true` to include archived households, and `hasModel` to return only the households with a model or only those without one; `totalCount` counts only the households that match. Send `balances=true` to add each household's current balance and cash, and `crm=true` to add the CRM user the household is assigned to, its tags and its service tier, from its linked CRM records.

📄️Create a household

Creates a household with the name in `name`, and returns it as **Get a household** returns it without `accounts` or `crm`. The household takes your firm's default fee structure. If you have connected Wealthbox, a Wealthbox household with the same name is also created and linked to the household.

📄️List household custom fields

Returns the custom fields that your CRM defines for households. These are the fields that the console offers under 'Custom fields' on the household lists. Each item gives the field's key, its name, its type and, for a select field, its options. The list is empty when your CRM is not Slant.

📄️Get a household

Returns the household with the given ID, with its members and its security restrictions. Send `accounts=true` to add its current balance and cash, the time of its most recent trade, and each of its accounts with its holdings, balances and year-to-date performance. Send `crm=true` to add what the household's linked CRM records hold, such as its contact information, tags, tasks, events and workflows. If your firm has no household with that ID, the response is `404`.

📄️Update a household

Replaces the model, billing, trade proposal and tolerance settings and the security restrictions of the household with the given ID with the ones in the request body, and returns the household as **Get a household** returns it without `accounts` or `crm`. Send every required field. A field you leave out or send as `null` is cleared, except `feeChargeLocation`, which is set to `Custodian Billed`. The security restrictions you send replace all of the household's security restrictions. Other fields, such as `name`, are not read. If your firm has no household with that ID, the response is `404`.

📄️Create a task for a household

Creates a task for the household with the given ID in each CRM the household is linked to: Wealthbox, Redtail and Slant. The response is the task as the CRMs return it; where more than one CRM gives a field, the value is the last of Wealthbox, Redtail and Slant. The response is `201` with `data: null` when no CRM created a task, for example when the household is linked to no CRM. Wealthbox takes the priority `Urgent` as `High`. If your firm has no household with that ID, the response is `404`.

📄️Create a workflow for a household

Creates a workflow for the household with the given ID from a workflow template of its linked CRM: an integer `template` in Wealthbox, a string `template` in Redtail. A CRM whose template is of the other form is skipped. With a Redtail template, send `category`. The response is `201` with `data: null` when no workflow was created, for example when the household is linked to neither Wealthbox nor Redtail. If your firm has no household with that ID, the response is `404`.

📄️Get the risk allocation of a household

Returns the current allocation of the household with the given ID to your firm's risk levels, and that of each of its accounts, keyed by account ID. `current` is `{}` for an account with no current holdings. `target` is always `{}`. If your firm has no household with that ID, the response is `404`.

📄️Archive a household

Archives the household with the given ID and each of its active accounts, and returns the household as **Get a household** returns it without `accounts` or `crm`. `archiveDate` is the time of the request, and `isActive` is `false`. A household that is already archived keeps its `archiveDate`. If your firm has no household with that ID, the response is `404`.

📄️Unarchive a household

Makes the household with the given ID and each of its accounts active again, including accounts that were archived before the household, and returns the household as **Get a household** returns it without `accounts` or `crm`. `archiveDate` is `null`, and `isActive` is `true`. If your firm has no household with that ID, the response is `404`.

📄️Get the AUM history of a household

Returns the total, cash and securities value of the accounts of the household with the given ID on each date of the period that has a balance, oldest first. If your firm has no household with that ID, the response is `404`.

📄️Get the performance history of a household

Returns the cumulative return of the household with the given ID on each date of the period that has a balance, oldest first: its return from the first date of the period to that date. If your firm has no household with that ID, the response is `404`.

📄️List the performance of a household's accounts

Returns the performance over a period of each account of the household with the given ID that has a balance in the period, in order of account ID. If your firm has no household with that ID, the response is `404`.

📄️Get the holdings of a household

Returns, for each account of the household with the given ID, the securities it held over a period: each position on `end-date`, with its income and its realized gains and losses of the period. A security the account sold in the period and does not hold on `end-date` is included with `units` and `value` `0`. If your firm has no household with that ID, the response is `404`.

📄️List the model weights of a household's accounts

Returns, for each active account of the household with the given ID, in order of account ID, the target weight in the household of each security of the model assigned to the account, or else to the household. Each weight is the security's weight in the model, from 0 to 100, times the account's share of the household balance. If your firm has no household with that ID, the response is `404`.

📄️Get the asset allocation of a household

Returns the allocation of the household with the given ID to asset classes: its current allocation, its target allocation, and its target from the household's model alone. The target allocation is the household's model when one is assigned to the household and the household's `modelAssignmentStrategy` is `completion` or `soft_completion`, otherwise the model of each account weighted by the account's share of the household balance. When the household's `modelAssignmentStrategy` is `null`, the firm's applies. If your firm has no household with that ID, the response is `404`.

📄️Assign a model to households

Assigns the model in `modelId` to each household whose ID is a key of `households`, and returns each household it assigned. Every key is assigned, whatever its value. A key that is not the ID of one of your firm's households is skipped, and the response leaves it out. Send the ID of one of your firm's models in `modelId`.

📄️Update the name of a household

Changes the name of the household with the given ID to the name in `name`, and returns the household as **Get a household** returns it without `accounts` or `crm`. The name of the Wealthbox household the household is linked to changes too. If your firm has no household with that ID, the response is `404`.

📄️Update the members of a household

Replaces the members of the household with the given ID with the contacts in the request body, and returns the household as **Get a household** returns it without `accounts` or `crm`. The household's members you leave out are left with no household. The members of the Wealthbox household and the Redtail family the household is linked to change the same way. Send the IDs of one or more of your firm's contacts. If your firm has no household with that ID, or no contact with an ID in the request body, the response is `404` and nothing changes.

📄️Update the trading settings of a household

Replaces the model, trade proposal, tolerance, lot selection and model assignment settings of the household with the given ID with the ones in the request body, and, for each account in `accounts`, its model and its security restrictions. An account's security restrictions become the entries of `holdings` with its `accountId` and `restrictSecurity` `true`. Accounts you leave out of `accounts` do not change. A field you leave out or send as `null` is cleared. `securityRestrictions` is not read. Returns the household as **Get a household** returns it without `accounts` or `crm`. If your firm has no household with that ID, or an account in `accounts` is not an account of that household, the response is `404` and nothing changes.

📄️List the notes of a household

Returns the notes on the CRM records linked to the household with the given ID: its Wealthbox household and the household's members, the members of its Redtail family, and its Slant household. The notes of the three CRMs are merged into one list, in order of ID, integer IDs before string IDs, and the page is taken from the merged list, so `totalCount` counts the notes of every CRM. Link the household to a CRM record first; see **Update household data connections**. If your firm has no household with that ID, the response is `404`.

📄️Create a note for a household

Creates a note with the text in `content` on each CRM record linked to the household with the given ID: its Wealthbox household, the head of its Redtail family, and its Slant household. The response is the note created last, in that order, or `data: null` when no note was created, for example when your firm's Slant connection is not connected. Link the household to a CRM record first; see **Update household data connections**. If your firm has no household with that ID, the response is `404`.

📄️Assign a fee structure to households

Assigns the fee structure in `feeStructureId` to each household in `householdsIds`, and returns each household it assigned. Send `feeStructureId` as `null` to remove the households' fee structure. A household ID that is not one of your firm's households is skipped, and the response leaves it out. Send the ID of one of your firm's fee structures, as **List fee structures** returns it.