Reference

API documentation

Live catalog of MCP tools and REST endpoints, generated from the platform registry so it stays aligned with production.

Base URL https://api.payrollshack.com

Download the full API collection for Postman — payroll REST, platform provisioning, agentic tools, and portal routes with baseUrl, apayKey, and dkeyKey variables.

Quick start

This documentation is public — no sign-in required. Create an account to manage API keys, billing, and company provisioning.

Subscribe and create a dkey_ key on API keys.
Provision a customer company on Companies — copy the one-time apay_ key.
Use that key for every payroll REST, MCP, and agentic tool call below.

Discover REST resources

curl -s "https://api.payrollshack.com/api/v1/payroll" \
  -H "Authorization: Bearer apay_YOUR_KEY"

Run any tool by name

curl -X POST "https://api.payrollshack.com/api/agentic/tools/execute" \
  -H "Authorization: Bearer apay_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tool_name": "list_employees", "arguments": {} }'

MCP connection·Usage billing·Provisioning

Questions or stuck on an integration? Join Payroll Shack Support on Discord.

Tool risk levels

Every MCP tool and agentic endpoint is tagged with a risk level. This controls whether the call runs immediately or requires a deliberate approval step. The same rules apply to REST, MCP, and /api/agentic/tools/execute.

Risk	When it runs	Approval	Audited	What it means
Read	Immediately on first call	Not required	No	Lookups and reports only — no data changes. Examples: list_employees, search_pay_runs, get_pay_run_summary, get_company_info
Low write	Immediately on first call	Not required	Yes	Routine create/update operations. Changes apply right away and are recorded in the audit log. Examples: create_employee, update_employee, create_pay_run, recalculate_pay_run, create_time_entry
High write	Only after explicit approval	Required — two-step flow	Yes	Sensitive or irreversible payroll actions (approve pay, mark paid, delete records). The first call is blocked until a human confirms. Examples: approve_pay_run, mark_pay_run_paid, void_pay_run, delete_pay_run, delete_employee

Risk

When it runs

Approval

Audited

What it means

Read

Immediately on first call

Not required

Lookups and reports only — no data changes.

Examples: list_employees, search_pay_runs, get_pay_run_summary, get_company_info

Low write

Immediately on first call

Not required

Yes

Routine create/update operations. Changes apply right away and are recorded in the audit log.

Examples: create_employee, update_employee, create_pay_run, recalculate_pay_run, create_time_entry

High write

Only after explicit approval

Required — two-step flow

Yes

Sensitive or irreversible payroll actions (approve pay, mark paid, delete records). The first call is blocked until a human confirms.

Examples: approve_pay_run, mark_pay_run_paid, void_pay_run, delete_pay_run, delete_employee

High-write approval flow

High-write tools use a two-step pattern. Step 1 returns approval_required: true (HTTP 409 on REST). Step 2 repeats the same call with approval set — only then does the action execute.

High-write tools (6)

approve_pay_run, mark_pay_run_paid, void_pay_run, delete_pay_run, delete_employee, approve_change_request

Step 1 — agentic / MCP (blocked)

POST https://api.payrollshack.com/api/agentic/tools/execute
{
  "tool_name": "approve_pay_run",
  "arguments": { "run_id": "..." }
}

// Response:
// { "approval_required": true, "tool": "approve_pay_run", ... }

Step 2 — agentic / MCP (approved)

POST https://api.payrollshack.com/api/agentic/tools/execute
{
  "tool_name": "approve_pay_run",
  "arguments": { "run_id": "..." },
  "approved": true
}

REST — first call returns 409

POST https://api.payrollshack.com/api/v1/payroll/pay-runs/{run_id}/approve
Authorization: Bearer apay_YOUR_KEY

// HTTP 409 — approval_required: true

REST — retry with approval

POST https://api.payrollshack.com/api/v1/payroll/pay-runs/{run_id}/approve?approved=true
Authorization: Bearer apay_YOUR_KEY

// Or header: X-Payroll-Approved: true

Low write vs high write: low-write mutations (create employee, update pay run, import data) execute on the first call. High-write mutations are reserved for payroll-committing or destructive actions and always require your integration or end user to confirm before they run.

Full catalog

Loading API catalog…