Payroll

Payroll connections, runs, employees, pay stubs, tax forms, and the payroll calculator. All endpoints require tenant context via entityId unless noted.

Authentication

• Session cookie — set when signed in via the web app
• API key — pass via the x-api-key header

All endpoints require authentication and entity access.

Endpoints

Connections and runs

GET /api/payroll

Query parameters:

Response: Array of connections and runs, or a single run depending on query.

POST /api/payroll

Request body:

{
  "entityId": "string",
  "action": "create-connection" | "manual-run" | "sync",
  "connectionId": "string",
  "provider": "gusto" | "adp" | "deel" | "remote",
  "credentials": { }
}

PATCH /api/payroll

Request body: Connection fields to update (e.g., sync frequency, credentials).

DELETE /api/payroll

Query parameters:

Employees

GET /api/payroll/employees

Query parameters:

Response: Array of employee records with name, status, compensation, and tax info.

POST /api/payroll/employees

Request body:

{
  "entityId": "string",
  "name": "string",
  "email": "string",
  "employeeType": "employee" | "contractor",
  "compensation": { "amount": 0, "currency": "USD", "period": "monthly" },
  "taxInfo": { }
}

PATCH /api/payroll/employees/[id]

Request body: Employee fields to update.

DELETE /api/payroll/employees/[id]

Terminates the employee. Request body may include termination date and reason.

GET /api/payroll/employees/[id]/stubs

Response: Array of pay stubs with gross pay, withholdings, net pay, and period.

Runs

GET /api/payroll/runs/[id]

Query parameters:

Response: Run with status, period, total amounts, and per-employee line items.

PATCH /api/payroll/runs/[id]

Request body:

{
  "action": "approve"
}

Calculator

POST /api/payroll/calculate

Request body:

{
  "entityId": "string",
  "mode": "preview" | "submit",
  "runDate": "YYYY-MM-DD",
  "employees": [
    {
      "employeeId": "string",
      "grossPay": 0,
      "deductions": [ ],
      "employerTaxes": [ ]
    }
  ]
}

Response: For preview, returns net pay and tax withholdings per employee. For submit, creates the payroll run and returns the run ID.

Tax forms

GET /api/payroll/tax-forms

Query parameters:

Response: Tax form data in the format required for filing (SSA/IRS) or distribution to recipients.