List all households

client.households.list(?, ?): HouseholdListResponse { data, pagination }

get/households

Retrieve a paginated list of households

ParametersExpand Collapse

query: HouseholdListParams { limit, offset }

limit?: number

Maximum number of households to return

maximum1000

minimum1

offset?: number

Number of households to skip

minimum0

ReturnsExpand Collapse

HouseholdListResponse { data, pagination }

data: Array<Household { id, created_at, primary_relationship_owner_id, 4 more } >

id: string

Unique identifier with household_ prefix

created_at: string

Timestamp when the household was created

formatdate-time

primary_relationship_owner_id: string

User ID of the primary relationship owner

updated_at: string

Timestamp when the household was last updated

formatdate-time

name?: string

Display name for the household

notes?: string | null

Notes about the household

maxLength65536

primary_individuals?: Array<Individual { id, created_at, first_name, 21 more } >

Primary client profiles for this household (at most 2)

id: string

Unique identifier with client_profile_ prefix

created_at: string

Timestamp when the individual was created

formatdate-time

first_name: string

First name of the individual

household_id: string

Household ID this individual belongs to

is_beneficiary: boolean

Whether this client profile should be an eligible beneficiary for entities and gifts

is_deceased: boolean

Whether this client profile is deceased

is_grantor: boolean

Whether this client profile should be an eligible grantor/owner/other principal for entities

is_primary: boolean

Whether this is one of the (at most) two primary clients on this household

is_trustee: boolean

Whether this client profile should be an eligible trustee for entities

last_name: string

Last name of the individual

updated_at: string

Timestamp when the individual was last updated

formatdate-time

address_line1?: string | null

Street address line 1 (from address edge)

address_line2?: string | null

Street address line 2 (from address edge)

city?: string | null

City (from address edge)

country?: string | null

Country (from address edge)

date_of_birth?: string | null

Date of birth (encrypted field)

formatdate

date_of_death?: string | null

Date of death if applicable (encrypted field)

formatdate

deleted_at?: string | null

Timestamp when the individual was soft deleted

formatdate-time

email?: string | null

Email address

formatemail

middle_name?: string | null

Middle name of the individual

notes?: string | null

Notes about the client profile

maxLength65536

postal_code?: string | null

ZIP or postal code (from address edge)

state?: string | null

State or province (from address edge)

suffix?: string | null

Name suffix (Jr., Sr., III, etc.)

pagination: Pagination { limit, offset, total }

limit: number

Number of items per page

minimum1

offset: number

Number of items skipped

minimum0

total: number

Total number of items available

minimum0

List all households

import Luminary from 'withluminary';

const client = new Luminary();

const households = await client.households.list();

console.log(households.data);

{
  "data": [
    {
      "id": "household_01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "created_at": "2024-01-15T09:30:00Z",
      "primary_relationship_owner_id": "user_01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "updated_at": "2024-01-20T14:45:00Z",
      "name": "Smith Family",
      "notes": "notes",
      "primary_individuals": [
        {
          "id": "client_profile_01ARZ3NDEKTSV4RRFFQ69G5FAV",
          "created_at": "2024-01-15T09:30:00Z",
          "first_name": "John",
          "household_id": "household_01ARZ3NDEKTSV4RRFFQ69G5FAV",
          "is_beneficiary": true,
          "is_deceased": true,
          "is_grantor": true,
          "is_primary": true,
          "is_trustee": true,
          "last_name": "Smith",
          "updated_at": "2024-01-20T14:45:00Z",
          "address_line1": "123 Main St",
          "address_line2": "Apt 4B",
          "city": "San Francisco",
          "country": "USA",
          "date_of_birth": "1980-05-15",
          "date_of_death": "2019-12-27",
          "deleted_at": "2019-12-27T18:11:19.117Z",
          "email": "john.smith@example.com",
          "middle_name": "Michael",
          "notes": "notes",
          "postal_code": "94102",
          "state": "CA",
          "suffix": "Jr."
        }
      ]
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 150
  }
}

Returns Examples

{
  "data": [
    {
      "id": "household_01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "created_at": "2024-01-15T09:30:00Z",
      "primary_relationship_owner_id": "user_01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "updated_at": "2024-01-20T14:45:00Z",
      "name": "Smith Family",
      "notes": "notes",
      "primary_individuals": [
        {
          "id": "client_profile_01ARZ3NDEKTSV4RRFFQ69G5FAV",
          "created_at": "2024-01-15T09:30:00Z",
          "first_name": "John",
          "household_id": "household_01ARZ3NDEKTSV4RRFFQ69G5FAV",
          "is_beneficiary": true,
          "is_deceased": true,
          "is_grantor": true,
          "is_primary": true,
          "is_trustee": true,
          "last_name": "Smith",
          "updated_at": "2024-01-20T14:45:00Z",
          "address_line1": "123 Main St",
          "address_line2": "Apt 4B",
          "city": "San Francisco",
          "country": "USA",
          "date_of_birth": "1980-05-15",
          "date_of_death": "2019-12-27",
          "deleted_at": "2019-12-27T18:11:19.117Z",
          "email": "john.smith@example.com",
          "middle_name": "Michael",
          "notes": "notes",
          "postal_code": "94102",
          "state": "CA",
          "suffix": "Jr."
        }
      ]
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 150
  }
}