Penny Docs
Households

Create Household

POST
/v1/households

Creates a household with the supplied name, reporting currency, and timezone, and makes the authenticated user its owner.

The household is initialized with default categories, preferences, and a manual cash account. Returns the created household, including its ID for subsequent requests and its current access status.

Authorization

PersonalApiToken
AuthorizationBearer <token>

Use your personal API token (penny_pat_…) as the bearer credential. Enter the token only; the client adds the Bearer prefix. Read-only tokens permit read requests. Read/write tokens remain limited by your current household membership and role. See https://penny.finance/docs/api#authentication for setup.

In: header

Request Body

application/json

name*Name
Lengthlength <= 255
currency*Currency

Value in

  • "AED"
  • "AFN"
  • "ALL"
  • "AMD"
  • "AOA"
  • "ARS"
  • "AUD"
  • "AWG"
  • "AZN"
  • "BAM"
  • "BBD"
  • "BDT"
  • "BHD"
  • "BIF"
  • "BMD"
  • "BND"
  • "BOB"
  • "BOV"
  • "BRL"
  • "BSD"
  • "BTN"
  • "BWP"
  • "BYN"
  • "BZD"
  • "CAD"
  • "CDF"
  • "CHE"
  • "CHF"
  • "CHW"
  • "CLF"
  • "CLP"
  • "CNY"
  • "COP"
  • "COU"
  • "CRC"
  • "CUP"
  • "CVE"
  • "CZK"
  • "DJF"
  • "DKK"
  • "DOP"
  • "DZD"
  • "EGP"
  • "ERN"
  • "ETB"
  • "EUR"
  • "FJD"
  • "FKP"
  • "GBP"
  • "GEL"
  • "GHS"
  • "GIP"
  • "GMD"
  • "GNF"
  • "GTQ"
  • "GYD"
  • "HKD"
  • "HNL"
  • "HTG"
  • "HUF"
  • "IDR"
  • "ILS"
  • "INR"
  • "IQD"
  • "IRR"
  • "ISK"
  • "JMD"
  • "JOD"
  • "JPY"
  • "KES"
  • "KGS"
  • "KHR"
  • "KMF"
  • "KPW"
  • "KRW"
  • "KWD"
  • "KYD"
  • "KZT"
  • "LAK"
  • "LBP"
  • "LKR"
  • "LRD"
  • "LSL"
  • "LYD"
  • "MAD"
  • "MDL"
  • "MGA"
  • "MKD"
  • "MMK"
  • "MNT"
  • "MOP"
  • "MRU"
  • "MUR"
  • "MVR"
  • "MWK"
  • "MXN"
  • "MXV"
  • "MYR"
  • "MZN"
  • "NAD"
  • "NGN"
  • "NIO"
  • "NOK"
  • "NPR"
  • "NZD"
  • "OMR"
  • "PAB"
  • "PEN"
  • "PGK"
  • "PHP"
  • "PKR"
  • "PLN"
  • "PYG"
  • "QAR"
  • "RON"
  • "RSD"
  • "RUB"
  • "RWF"
  • "SAR"
  • "SBD"
  • "SCR"
  • "SDG"
  • "SEK"
  • "SGD"
  • "SHP"
  • "SLE"
  • "SOS"
  • "SRD"
  • "SSP"
  • "STN"
  • "SVC"
  • "SYP"
  • "SZL"
  • "THB"
  • "TJS"
  • "TMT"
  • "TND"
  • "TOP"
  • "TRY"
  • "TTD"
  • "TWD"
  • "TZS"
  • "UAH"
  • "UGX"
  • "USD"
  • "USN"
  • "UYI"
  • "UYU"
  • "UYW"
  • "UZS"
  • "VED"
  • "VES"
  • "VND"
  • "VUV"
  • "WST"
  • "XAD"
  • "XAF"
  • "XAG"
  • "XAU"
  • "XBA"
  • "XBB"
  • "XBC"
  • "XBD"
  • "XCD"
  • "XCG"
  • "XDR"
  • "XOF"
  • "XPD"
  • "XPF"
  • "XPT"
  • "XSU"
  • "XTS"
  • "XUA"
  • "XXX"
  • "YER"
  • "ZAR"
  • "ZMW"
  • "ZWG"
timezone*Timezone

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/households" \  -H "Content-Type: application/json" \  -d '{    "name": "Chen Household",    "currency": "USD",    "timezone": "America/Los_Angeles"  }'
{  "id": "Hh4vK8pQ2sLm",  "name": "Chen Household",  "currency": "AED",  "timezone": "America/Los_Angeles",  "image_url": "https://cdn.penny.finance/households/Hh4vK8pQ2sLm.png",  "role": "owner",  "preferences": {    "show_recurring_suggestions": true,    "show_advanced_details": true  },  "access_status": "available"}

List Households GET

Lists every household the authenticated user belongs to, including its currency, timezone, preferences, and the user's role. Use accessstatus to determine…

Update Household PATCH

Updates a household's name, reporting currency, or timezone and returns the updated household. Only the household owner can make this change. Send only the…