---
title: "Create a household"
method: POST
path: "/v1/households"
tags: ["Households"]
---

# Create a household

`POST /v1/households`

## Request

- Base URL: `https://api.slant.app`
- URL: `https://api.slant.app/v1/households`
- Auth: HTTP bearer

Create a new household (Client or Prospect). Requires a `type` parameter to specify the household type. Provide at least a first or last name. Client households also require at least one contact method (email or phone). Client-only fields (tier, became_client_at) are silently ignored when creating a Prospect. Top-level ssn and drivers_license_number are only supported when creating a Client. Creating a household does not deduplicate or merge by email; search by exact email first if you need sync-style upsert behavior.

## Request body

- object
  - `book_id` string, required: The book ID
  - `type` 'Client' | 'Prospect', required: The type of household to create
  - `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)
  - `first_name` string: Head of household first name
  - `last_name` string: Head of household last name
  - `email` string, email: Primary email address
  - `phone_number` string: Primary phone number
  - `phone_extension` string: Optional extension for the primary phone number
  - `preferred_name` string: Preferred name of the head of household
  - `ssn` string: Head of household SSN (Clients only)
  - `drivers_license_number` string: Head of household driver's license number (Clients only)
  - `tag_ids` string[]: Existing household tag IDs
  - `custom_fields` object: Household custom field values keyed by field_key
  - `head_of_household` object: Advanced format: Full person schema with nested contacts. Takes priority over flat fields if provided.
    - `first_name` string
    - `last_name` string
    - `middle_name` string
    - `preferred_name` string
    - `salutation` string
    - `suffix` string
    - `gender` 'female' | 'male' | 'nonbinary' | 'other' | 'prefer_not_to_say'
    - `designations` string
    - `email` string, email: Simple: single email as string
    - `phone_number` string: Simple: single phone as string
    - `phone_extension` string: Simple: extension for the single phone
    - `email_addresses` object[]: Advanced: array of email objects with types
      - `email` string, email
      - `email_type` 'personal' | 'business' | 'school' | 'other' | 'inactive'
      - `is_primary` boolean
    - `phone_numbers` object[]: Advanced: array of phone objects with types
      - `phone_number` string
      - `extension` string
      - `phone_type` 'mobile' | 'work' | 'home' | 'fax' | 'other'
      - `is_primary` boolean
    - `addresses` object[]: Array of addresses
      - `line1` string
      - `line2` string
      - `city` string
      - `state` string
      - `zip` string
      - `country_code` string
      - `address_type` 'home' | 'work' | 'mailing' | 'other'
      - `is_primary` boolean
    - `employments` object[]: Array of employment records
      - `business_name` string
      - `role` string
      - `start_date` string, date
      - `end_date` string, date
      - `actively_employed` boolean
    - `ssn` string: Social security number
    - `drivers_license_number` string: Driver's license number
    - `custom_fields` object: Person custom field values as key-value pairs

## Response `201`

created

- Household
  - `id` string, required: The ID of the household
  - `type` 'Client' | 'Prospect' | 'PastClient', 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
    - `created_at` string, date-time, required: When the person was created
    - `updated_at` string, date-time, required: When the person record was last updated. Associated record changes do not advance this timestamp.
    - `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
    - `date_of_death` string, date, nullable: Date of death
    - `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' | 'inactive', required
      - `is_primary` boolean, required
      - `id` string: The email address ID
    - `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
      - `id` string: The phone number ID
    - `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
      - `id` string: The address ID
    - `employments` Employment[]: Included for contacts; otherwise retrieve employment history through GET /v1/people/{person_id}/employments.
      - `id` string: The employment ID
      - `person_id` string: The person ID
      - `business_id` string, nullable: Linked employer Business ID, when available
      - `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
  - `tags` object[]
    - `id` string
    - `name` string

## Other responses

- `400`: invalid type
- `401`: unauthorized - missing or invalid token
- `403`: Access denied. Policy and membership failures may have an empty body. A read-only personal token cannot perform writes.
- `429`: An hourly API rate limit was exceeded. Wait Retry-After seconds before retrying.

## Changes

- **2026-11-03** `173c41bf6be9`: 1 breaking, 2 warning, 16 info
  - removed the media type `application/json` for the response with the status `400`
  - added the new `PastClient` enum value to the `type` response property for the response status `201`
  - added the new `inactive` enum value to the `people/items/email_addresses/items/email_type` response property for the response status `201`
  - added the new optional request property `custom_fields`
  - …15 more

[Operation history](https://skmtc.dev/slant/apis/slant-public-api-v1/changes/v1/households/post.md)

---

[API](https://skmtc.dev/slant/apis/slant-public-api-v1.md) - [All operations](https://skmtc.dev/slant/apis/slant-public-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/slant/apis/slant-public-api-v1/revisions/173c41bf6be9?raw)