Households API

External integration

Households group contacts or organisations into a single relationship context — typically a family unit, investment group, or trust structure. The API supports household CRUD, linked custodian accounts, member management, and v2 list filtering.

Read endpoints

Endpoint	Purpose
`GET /api/households`	Paginated list of households.
`GET /api/households/{householdUuid}`	Single household by UUID.
`GET /api/households/search?searchTerm=`	Search by household name.
`GET /api/households/manager?rmType=&rmUuid=`	Households by relationship manager.
`GET /api/households/{householdUuid}/detail`	Expanded household detail with member and portfolio data.
`GET /api/households/{householdUuid}/accounts`	Linked custodian account numbers.

Create and update

POST/api/households

{
  "name": "Doe Family Household",
  "relationshipManagerType": "TENANT_STAFF",
  "relationshipManagerUuid": "TS019C06688AA57248B9EA5325DBDFC48E",
  "isActive": true,
  "accountNumbers": ["ACC-1001", "ACC-1002"],
  "members": [
    {
      "memberType": "CONTACT",
      "contactUuid": "C019B9D0FD0E5772F9E8ED189895D40C4"
    }
  ]
}

PUT/api/households/{householdUuid} supports selective updates, account linking/unlinking, and member add/remove in a single call.

{
  "name": "Doe Family Household",
  "accountNumbersToLink": ["ACC-1003"],
  "accountNumbersToUnlink": ["ACC-1001"],
  "membersToAdd": [
    {
      "memberType": "ORGANISATION",
      "organisationUuid": "O019B9D0FD0E5772F9E8ED189895D40C4"
    }
  ],
  "memberUuidsToRemove": ["HM019B9D0FD0E5772F9E8ED189895D40C4"]
}

DELETE/api/households/{householdUuid} returns 204 No Content on success.

Household members

Members are the individual contacts or organisations that belong to a household. Each member can have an optional relationship type that describes how they relate to the household (e.g. spouse, child, trustee).

Endpoint	Purpose
`GET /api/households/{householdUuid}/members`	List members. Supports `includeDeleted` and `searchTerm`.
`GET /api/households/{householdUuid}/members/{memberUuid}`	Get one member.
`POST /api/households/{householdUuid}/members`	Add a member.
`PUT /api/households/{householdUuid}/members/{memberUuid}`	Update a member's relationship type or primary flag.
`DELETE /api/households/{householdUuid}/members/{memberUuid}`	Remove a member.

{
  "memberType": "CONTACT",
  "contactUuid": "C019B9D0FD0E5772F9E8ED189895D40C4",
  "relationshipType": "SPOUSE",
  "isPrimary": true
}

The member response returns both lightweight member fields and, when enriched, embedded contact or organisation data.

V2 filtering

POST/api/v2/households filters within the current tenant and active status rules.

{
  "filters": [
    { "field": "isActive", "operator": "equals", "value": "true" }
  ],
  "page": 0,
  "size": 20,
  "sort": ["updatedAt,desc"]
}

Use POST /api/v2/households/filter-values for distinct field values within the same filtering model.

Enum reference

memberType

Specifies whether a household member is an individual contact or a legal entity.

CONTACT ORGANISATION

relationshipType

Describes how a member relates to the household. Use in member create/update requests.

Family relationships:

SPOUSE CHILD PARENT SIBLING GRANDPARENT GRANDCHILD OTHER_FAMILY

Business relationships:

BUSINESS_PARTNER ADVISOR

Legal relationships:

TRUSTEE BENEFICIARY OTHER