---
title: "Update a household"
method: PATCH
path: "/v1/households/{id}"
tags: ["Households"]
---

# Update a household

`PATCH /v1/households/{id}`

Update a household's name, tier, or became_client_at. Client-only fields (tier, became_client_at) are silently ignored when updating a Prospect.

## Request body

- object
  - `household_name` string — Name of the household
  - `tier` string — Client tier label (Clients only)
  - `became_client_at` string, date-time — When the household became a client (Clients only)

## Response `200`

successful

- Household
  - `id` string, required — The ID of the household
  - `type` 'Client' | 'Prospect', required — The type of household
  - `name` string, required — The name of the household
  - `tier` string, nullable — The tier label for this household (null for Prospects)
  - `became_client_at` string, date-time, nullable — When this household became a client (null for Prospects)
  - `book_id` string, required — The ID of the book this household belongs to
  - `profile_picture_url` string, uri, nullable — URL to the household profile picture
  - `custom_fields` object — Custom field values as key-value pairs
  - `people` Person[], required — The people in this household
    - `id` string, required — The person ID
    - `book_id` string, required — The book ID
    - `household_id` string, nullable — The household ID
    - `contact_id` string, nullable — The contact ID (present when person belongs to a contact)
    - `role_type` 'client' | 'prospect' | 'contact' | 'past_client', nullable — The entity type this person belongs to
    - `first_name` string, required
    - `middle_name` string, nullable
    - `last_name` string, required
    - `salutation` string, nullable
    - `suffix` string, nullable
    - `maiden_name` string, nullable
    - `gender` 'female' | 'male' | 'nonbinary' | 'other' | 'prefer_not_to_say', nullable
    - `designations` string, nullable
    - `household_role` 'head_of_household' | 'partner' | 'spouse' | 'dependent_child' | 'other_adult' | 'other_dependent' | 'unknown' | 'deceased' | 'non_dependent_child' | 'grandchild', nullable — Only present when person belongs to a household
    - `preferred_name` string, nullable
    - `date_of_birth` string, date, nullable — Date of birth
    - `job_title` string, nullable — Job title
    - `ssn` string, nullable — Obfuscated social security number
    - `drivers_license_number` string, nullable — Obfuscated driver's license number
    - `email_addresses` Email[] — Array of email addresses with primary designation
      - `email` string, email, required
      - `email_type` 'personal' | 'business' | 'school' | 'other', required
      - `is_primary` boolean, required
    - `phone_numbers` PhoneNumber[] — Array of phone numbers with primary designation
      - `phone_number` string, required
      - `extension` string, nullable
      - `phone_type` 'mobile' | 'work' | 'home' | 'fax' | 'other', required
      - `is_primary` boolean, required
    - `addresses` Address[] — Array of addresses with primary designation
      - `line1` string, nullable
      - `line2` string, nullable
      - `city` string, nullable
      - `state` string, nullable
      - `zip` string, nullable
      - `country_code` string, nullable
      - `address_type` 'home' | 'work' | 'mailing' | 'other', required
      - `is_primary` boolean, required
    - `employments` Employment[] — Array of employment records
      - `id` string — The employment ID
      - `person_id` string — The person ID
      - `business_name` string, required
      - `role` string, nullable
      - `start_date` string, date, nullable
      - `end_date` string, date, nullable
      - `actively_employed` boolean
    - `custom_fields` object — Custom field values as key-value pairs

## Other responses

- `400` — bad request - invalid JSON
- `401` — unauthorized - missing or invalid token
- `403` — forbidden
- `404` — not found

---

[API](https://skmtc.net/slant/apis/slant-public-api-v1.md) · [All operations](https://skmtc.net/slant/apis/slant-public-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/slant/slant-public-api-v1/revisions/b56e0d137554/schema)