Bookkeeper Organizations

Manage bookkeeper organizations (the top-level tenant in PayPunch). All endpoints require an admin JWT (Authorization: Bearer <token>).

Method	Path	Purpose
`GET`	`/api/v1/admin/bookkeeper-orgs`	List organizations (paginated)
`POST`	`/api/v1/admin/bookkeeper-orgs`	Create an organization
`GET`	`/api/v1/admin/bookkeeper-orgs/{id}`	Get one organization
`PUT`	`/api/v1/admin/bookkeeper-orgs/{id}`	Update an organization
`DELETE`	`/api/v1/admin/bookkeeper-orgs/{id}`	Deactivate (soft delete)

List organizations

GET /api/v1/admin/bookkeeper-orgs

Query parameters

integer

default:"1"

Page number (1-based).

integer

default:"20"

Number of results per page.

string

Case-insensitive match against name, slug, and email.

string

Pass true to return only active organizations. Any other value returns all.

Response

object

Paginated envelope: items, total, page, pageSize, totalPages. Each item includes a _count of related companies and adminUsers.

curl "https://app.paypunch.io/api/v1/admin/bookkeeper-orgs?page=1&pageSize=20&active=true" \
  -H "Authorization: Bearer <admin-token>"

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "a1c2...",
        "name": "Acme Bookkeeping",
        "slug": "acme-bookkeeping",
        "email": "billing@acmebookkeeping.com",
        "timezone": "America/New_York",
        "overtimeThreshold": 40,
        "overtimeMultiplier": 1.5,
        "active": true,
        "_count": { "companies": 4, "adminUsers": 2 }
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20,
    "totalPages": 1
  }
}

Create an organization

POST /api/v1/admin/bookkeeper-orgs

Request body

string

required

Organization name.

string

URL slug. If omitted, generated from name. Must be unique.

string

Contact email (validated as an email when present).

string

default:"USA"

string

default:"America/New_York"

string

default:"MM/DD/YYYY"

number

default:"40"

Weekly hours before overtime applies. Minimum 0.

number

default:"1.5"

Overtime pay multiplier. Minimum 1.

Returns 201 with the created organization (and _count). Returns 400 Slug already exists if the slug collides.

curl -X POST https://app.paypunch.io/api/v1/admin/bookkeeper-orgs \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Bookkeeping",
    "email": "billing@acmebookkeeping.com",
    "timezone": "America/Chicago",
    "overtimeThreshold": 40,
    "overtimeMultiplier": 1.5
  }'

{
  "success": true,
  "data": {
    "id": "a1c2...",
    "name": "Acme Bookkeeping",
    "slug": "acme-bookkeeping",
    "active": true,
    "_count": { "companies": 0, "adminUsers": 0 }
  },
  "message": "Bookkeeper organization created successfully"
}

Get an organization

GET /api/v1/admin/bookkeeper-orgs/{id}

string

required

The organization’s UUID.

Returns the organization including its companies (with employee counts) and adminUsers. Returns 404 if not found.

Response (200)

{
  "success": true,
  "data": {
    "id": "a1c2...",
    "name": "Acme Bookkeeping",
    "companies": [
      { "id": "c9d8...", "name": "Builders R Us", "active": true, "_count": { "employees": 12 } }
    ],
    "adminUsers": [
      { "id": "0b6f...", "firstName": "Sarah", "lastName": "Lee", "email": "sarah@acmebookkeeping.com", "role": "SUPER_ADMIN", "active": true }
    ]
  }
}

Update an organization

PUT /api/v1/admin/bookkeeper-orgs/{id}

string

required

The organization’s UUID.

All body fields are optional; only provided fields are updated.

string

number

Minimum 0.

number

Minimum 1.

boolean

Set false to deactivate or true to reactivate.

Returns 200 with the updated organization, or 404 if not found.

Deactivate an organization

DELETE /api/v1/admin/bookkeeper-orgs/{id}

string

required

The organization’s UUID.

This is a soft delete — it sets active = false and returns the updated record. Returns 404 if not found.

Response (200)

{
  "success": true,
  "data": { "id": "a1c2...", "active": false },
  "message": "Bookkeeper organization deactivated successfully"
}

These handlers call requireAuth(request, 'admin'), so a valid admin token is required. The source comments mark create as “super admin only” but the handlers do not enforce a specific admin role beyond the admin token type.

Overview

Admin API

Employee API

Bookkeeper Organizations

List organizations

Query parameters

Response

Create an organization

Request body

Get an organization

Update an organization

Deactivate an organization

​List organizations

​Query parameters

​Response

​Create an organization

​Request body

​Get an organization

​Update an organization

​Deactivate an organization

List organizations

Query parameters

Response

Create an organization

Request body

Get an organization

Update an organization

Deactivate an organization