Reference

API documentation

Build payroll into your product with REST APIs or MCP tools. New to payroll? Read the glossary first — then use the live catalog below (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.

Payroll terms (plain English)

If you are new to payroll products, start here. These are the words used throughout the API, MCP tools, and examples.

Typical payday flow

Set up people — Create employees with address, pay type (salary or hourly), and tax ID (SSN in the US, SIN in Canada).
Create a pay run — Pick the pay period dates and which employees to include. The system calculates gross pay, taxes, and net.
Review & reconcile — Check blockers, missing hours, and reconciliation warnings. Fix anything incomplete.
Approve — Confirm the numbers. This locks in the run for payment.
Mark paid & documents — Record payment, export bank files if needed, and download payslips or year-end tax forms (W-2 / T4).

Company: The employer you are running payroll for. One API key usually belongs to one company. Everything else (employees, pay runs, tax forms) sits under that company.
Work locationalso: location: A physical or tax work site (office, warehouse, remote state). Tax rules often follow where the employee works, not only the company HQ address.
Employee: A person on payroll (W-2 / salaried / hourly) or a contractor you pay through the platform. Creating an employee stores identity, pay type, and tax IDs.
Pay schedule: How often people get paid — for example Weekly, Biweekly (every two weeks), or Monthly. It defines the rhythm of pay periods; it is not a country setting.
Pay period: The date range you are paying for (for example March 1–15). A pay run always belongs to one pay period.
Pay runalso: payroll run: One batch of payroll for a pay period: who gets paid, gross pay, taxes, deductions, and net pay. Think of it as “this payday’s payroll batch.” Status moves from draft/calculated → approved → paid.
Payslip: The employee-facing breakdown for one person in a pay run (earnings, taxes, net). Often downloaded as PDF after the run is calculated or paid.
Approve pay run: A manager confirms the calculated numbers are correct. After approval, banking exports and “mark paid” become available. This is a high-risk action and needs explicit approval in the API.
Mark paid: Records that money was (or will be) disbursed for an approved pay run. Usually the last step before treating the payday as complete.
Reconciliation: A checklist that looks for missing or inconsistent data before or after a pay run (for example missing hours, banking, or tax profile). Fix issues it finds so payroll can finish cleanly.
Time entry: Hours worked on a specific date (regular or overtime). Hourly employees usually need time entries so the pay run can calculate gross pay.
Deduction: Money taken from an employee’s pay for things like benefits premiums or other withholdings (separate from government tax).
Garnishment: A court- or agency-ordered deduction (for example child support or tax levy) taken from net pay.
Compensation: How the person is paid: SALARY uses annual_salary only; HOURLY uses hourly_rate only. Sending both (or zeros) causes validation errors.
Credit (billing): On the developer platform, one successful API/MCP/tool call usually costs one credit. Failed validation and approval previews do not.
MCP: Model Context Protocol — how AI apps like Claude Desktop call Payroll Shack tools over HTTPS. You connect with an MCP URL plus an API key or OAuth sign-in.
High-write action: A sensitive change (approve pay, mark paid, delete employee). The first API call returns a preview asking for confirmation; the second call must include approved: true.

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": "get_company_info", "arguments": {} }'

MCP connection·Usage billing·Provisioning

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

Tool risk levels

Every tool is tagged by how carefully it should be used. Read only looks up data. Low write creates or updates records (including creating a pay run — a payday batch). High write confirms payday or deletes data — the first call is blocked until you confirm, then call again with approved: true. 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 — e.g. add an employee or create a pay run (a payday batch). 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 payday actions (approve the run, mark it paid, delete records). The first call is blocked until a human confirms; call again with approved: true. 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 — e.g. add an employee or create a pay run (a payday batch). 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 payday actions (approve the run, mark it paid, delete records). The first call is blocked until a human confirms; call again with approved: true.

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…