Penny Docs
Categories

Create Category

POST
/v1/households/{household_id}/categories

Creates a household category for classifying transactions as income, expense, or transfer.

The name and emoji must each be unique among active household categories. Supply group_id to place the category in a group, whose type determines the category's effective type; use null for an ungrouped category. Returns the created category.

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

Path Parameters

household_id*Household Id

Request Body

application/json

On PUT, replaces category details; omitted group_id clears the group.

name*Name
Lengthlength <= 255
emoji*Emoji
Lengthlength <= 50
category_type*CategoryType

Value in

  • "income"
  • "transfer"
  • "expense"
group_id?string|null

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/households/string/categories" \  -H "Content-Type: application/json" \  -d '{    "name": "Coffee & Dining",    "emoji": "☕️",    "category_type": "income"  }'
{  "id": "Ct5nR8wY1jFu",  "name": "Coffee & Dining",  "emoji": "☕️",  "category_type": "income",  "group_id": "Cg2mV7pL4zXe"}

List Categories GET

Lists the household's active categories and all category groups in a single response. Match each category's group ID to the returned groups to build a…

Get Category GET

Retrieves an active household category, including its emoji, type, and group assignment. Returns categorynotfound if the category is deleted or does not…