API reference

Class

The business's own groups for income and expenses (a line of work, a team, a fund), once it tracks classes (Settings › Advanced). A class goes on each line of an invoice, bill or expense (class_id), and the profit and loss can show a column for each.

GET /classes
POST /classes
GET /classes/{id}
PATCH /classes/{id}

The class object

object string: string; Always "class".
id id: id; The class's id (a UUID). Use it to fetch it, or to refer to it from other things.
name string: string; Its name.
full_name string: string; Its name with what it sits under, like "Retail / Online".
parent_id id or null: id or null; The class it sits under, or null at the top.
active boolean: boolean; False once it's made inactive in TallyPip (it's kept, with its history, but left out of pickers).
created_at timestamp: timestamp; When it was added, in UTC.

Example

{
  "object": "class",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708190",
  "name": "Online",
  "full_name": "Retail / Online",
  "parent_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708189",
  "active": true,
  "created_at": "2026-10-06T14:30:00.000Z"
}

List classes

GET /api/v1/classes

Classes (Settings › Advanced), newest first, each with its full name.

Key: any (Read only works).

Query

limit integer: integer; How many, 1 to 100 (default 25).
starting_after id: id; The last id of the page before, for the next page (when has_more is true).

Newest first. Answers a list: { object: "list", url, has_more, data }.

Request

curl https://tallypip.com/api/v1/classes?limit=3 \
  -H "Authorization: Bearer tpk_your_key"

Answer: 200

{
  "object": "list",
  "url": "/api/v1/classes",
  "has_more": false,
  "data": [
    {
      "object": "class",
      "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708190",
      "name": "Online",
      "full_name": "Retail / Online",
      "parent_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708189",
      "active": true,
      "created_at": "2026-10-06T14:30:00.000Z"
    }
  ]
}

Try it

With your own key (Settings › Connected apps). It stays in this page only, and reading can't change anything.

Create a class

POST /api/v1/classes

Add a class (or a sub-class, with parent_id).

Key: Read and change.

Body (JSON)

Answers 201 with the new class. Refused with 400 and the reason (nothing is saved); send an Idempotency-Key so a retry can't make it twice.

Request

curl https://tallypip.com/api/v1/classes \
  -H "Authorization: Bearer tpk_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <a new id for each change>" \
  -d '{
    "name": "Online",
    "parent_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708189"
  }'

Answer: 201

{
  "object": "class",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708190",
  "name": "Online",
  "full_name": "Retail / Online",
  "parent_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708189",
  "active": true,
  "created_at": "2026-10-06T14:30:00.000Z"
}

Retrieve a class

GET /api/v1/classes/{id}

One class.

Key: any (Read only works).

Request

curl https://tallypip.com/api/v1/classes/3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708190 \
  -H "Authorization: Bearer tpk_your_key"

Answer: 200

{
  "object": "class",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708190",
  "name": "Online",
  "full_name": "Retail / Online",
  "parent_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708189",
  "active": true,
  "created_at": "2026-10-06T14:30:00.000Z"
}

Try it

With your own key (Settings › Connected apps). It stays in this page only, and reading can't change anything.

Update a class

PATCH /api/v1/classes/{id}

Change a class: its name, what it sits under, or make it inactive.

Key: Read and change.

Body (JSON)

Send only what changes. Answers 200 with the class as it is now. Refused with 400 and the reason (nothing is changed).

Request

curl -X PATCH https://tallypip.com/api/v1/classes/3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708190 \
  -H "Authorization: Bearer tpk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "active": false
  }'

Answer: 200

{
  "object": "class",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708190",
  "name": "Online",
  "full_name": "Retail / Online",
  "parent_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708189",
  "active": true,
  "created_at": "2026-10-06T14:30:00.000Z"
}