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.
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;