Skip to content

Household (People)

A household links people together and can have a primary contact.

A household links people together and can have a primary contact. To add a person to an existing household, use the HouseholdMemberships endpoint.

Property Value
Product People (pco.people, API version 2026-10-05)
Resource type Household
TypeScript People.Household, attributes People.HouseholdAttributes, schema People.HouseholdSchema
Planning Center path /people/v2/households
Planning Center docs Household

How to reach it

Client path Returns Filters Create
pco.people.households Collection Yes
pco.people.households.id(householdId).household_memberships.id(householdMembershipId).household Collection No
pco.people.people_imports.id(peopleImportId).histories.id(peopleImportHistoryId).household Collection No
pco.people.people.id(personId).households Collection No

From a collection, .id(householdId) addresses one Household: pco.people.households.id(householdId). Collections support where, include, order, and pagination; single resources have get().

Attributes

On People.HouseholdAttributes. Every resource also has id and type ('Household') next to its attributes.

Name Type Description
avatar string | null File UUID (see File Uploads section)
created_at string | null
member_count number | null
name string | null
primary_contact_id string | null
primary_contact_name string | null
updated_at string | null

Relationships and includes

Side-load with include() (or get({ include })) and read with related(resource, name): people.

Relationship Type To Includable
people To many Person Yes
primary_contact To one Person No

Querying

Where

where(field, value) for equality; where(field, op, value) with the operators listed.

Field Value type Operators
created_at string | Date gt, gte, lt, lte
member_count number Equality only
name string Equality only
primary_contact_name string Equality only
updated_at string | Date gt, gte, lt, lte

Order

order(...) accepts these fields, ascending, or descending with a - prefix: created_at, member_count, name, primary_contact_name, updated_at.

Edges

Follow these from one Household, ref = pco.people.households.id(householdId):

Edge Leads to Returns Filters Create
ref.household_memberships HouseholdMembership Collection Yes
ref.people Person Collection non_pending, without_deceased No

Writing

Property Value
Create Yes, create() on pco.people.households
Update Yes, update() on a reference
Delete Yes, delete() on a reference

Create attributes

Typed as People.HouseholdSchema['create'].

Attribute Type
avatar string | null
member_count number | null
name string | null
people_ids string[]
primary_contact_id string | null

Update attributes

Typed as People.HouseholdSchema['update'].

Attribute Type
avatar string | null
member_count number | null
name string | null
people_ids string[]
primary_contact_id string | null

See Writing data.

Example

import type { People } from '@mackenly/planningcenterkit';

const page = await pco.people.households.order('created_at').perPage(25).list();
const items: People.Household[] = page.data;

Type to search…

↑↓ navigate↵ selectEsc close