All notable changes to the NannyKeeper API, newest first.
v1.9.0Autopilot management
GET /v1/autopilot + /v1/autopilot/history
New read endpoints for Autopilot — recurring auto-run payroll that generates, approves, and fires each period's payroll automatically so a household never misses a paycheck. GET `/v1/autopilot?employer_id=…&employee_id=…` returns the live enrollment, eligibility, and a 3-payday schedule preview; omit `employee_id` to list the employer's active enrollments.
GET `/v1/autopilot/history?employer_id=…&employee_id=…` returns the durable event ledger (newest first) — every enroll/skip/pause/generate/fire/fail decision with actor and source, for support and reconciliation.
Requires the `ach` scope (Plus/Professional) — Autopilot is a Plus+ feature.
POST /v1/autopilot/{pause,resume,skip,disable}
Manage an existing enrollment: `pause` (stops new generation), `resume` (re-checks eligibility, clears the failure counter), `skip` (skip the next period; add `through_date` to skip through a vacation), `disable` (turn off — soft-deleted so the ledger and standing ACH authorization are retained).
Enrolling is deliberately NOT exposed via the API — turning Autopilot on captures a standing recurring ACH authorization that must be employer-driven in the app. POST `/v1/autopilot/enroll` returns 403 pointing back to the in-app flow.
Note: `pause` stops NEW generation only — a payroll already in `scheduled` is a separate delayed task and still fires unless you void it from the payroll page.
`disable` is different: it is a revocation of the standing ACH authorization, so it ALSO voids that employee's AUTOPILOT-generated payrolls still in `scheduled` (not yet sent to the banking network). A scheduled payroll you created manually is left alone — void it yourself if you meant to cancel it. A run already firing, funding, or processing has been initiated and cannot be recalled.
MCP server (1.9.0)
New `get_autopilot` (read status/enrollments) and `manage_autopilot` (pause/resume/skip/disable via an `action` enum) tools. Enrolling stays in-app by design — there is no enroll tool.
v1.7.0State filing status
GET /v1/state-registrations
New read-only endpoint returning the employer's state agency account numbers (UC, withholding, SDI) per (state, registration_type) tuple. Last-four only by default; pass `?reveal=true` for full account numbers (audit-logged).
Response includes the agency name and a registration URL for any states the employer is registered in but missing an account on file. Use before generating quarterly filing instructions or prompting customers to complete state setup.
Write operations are not exposed via the API — state account numbers must be entered by the customer via /settings/states.
MCP server (1.7.0)
New `get_state_filing_status` tool. No arguments — calls the new endpoint and returns the same shape. Use before drafting filing instructions so agents can cite the actual last-four (e.g., "file Form UC-2 for Q2 — your PA UC account is ••••5678").
Read-only by design. Upsert of account numbers is deliberately not exposed via MCP — LLMs are very capable of fabricating plausible numbers and we don't want one silently landing on a quarterly UC return.
v1.6.0Voluntary set-aside override
POST /v1/payroll/run + /v1/payroll/preview
New optional `voluntary_set_aside` field on each employee in the request. Use it to override or skip the employee's recurring voluntary set-aside rule for this paycheck only.
Shape: `{ skip?: boolean, amount?: number }`. `skip: true` bypasses the rule for this paycheck; `amount: <number>` overrides the computed amount ($0–$9,999). Omit the field to apply the recurring rule normally.
The recurring rule itself (rate-of-gross or fixed-per-period) is configured via the dashboard on the employee profile — the API can only override or skip per-paycheck.
Voluntary set-asides are post-tax — they reduce the employee's net pay and accrue to a balance the employer holds in escrow. They do NOT affect gross pay, federal/state taxes, FICA, FUTA, SUTA, W-2 box 1, or Schedule H.
MCP server (1.6.0)
`run_payroll` and `preview_payroll` accept the new `voluntary_set_aside` override field. Existing 1.5.0 callers continue to work without any change — omitting the field applies the recurring rule normally.
v1.5.0Scheduled payroll
POST /v1/payroll/run — new `scheduled` return status
When `pay_date` is more than 5 business days in the future on a direct-deposit payroll, the API no longer fires ACH immediately. Instead the response returns `status: scheduled` and the payroll auto-fires at `scheduled_send_at` (5 biz days before pay_date).
New response fields: `scheduled_send_at` (ISO UTC timestamp) and `is_estimated: true`. The net pay and tax amounts returned are estimates — they're recomputed against current YTD and rate configs at fire time, which may shift the final numbers slightly if a rate fix shipped or another payroll landed in between.
In-window pay dates (within 5 business days) behave exactly as in v1.4.0 — `status: processing`/`pending_funding`/`completed`. No changes to that path.
Non-DD payrolls (check/cash) always fire immediately regardless of pay_date — no scheduled status.
Amount safeguards (`confirm_large_payroll`) and ACH debit authorization (`confirm_ach_debit`) gates now run at approve time for scheduled payrolls; callers still pass them through the same parameters.
POST /v1/payroll/preview
Response now includes `is_estimated: true` when pay_date is far enough out that a real run would schedule. Flag lets agents tell users that scheduled numbers will be recomputed at fire.
MCP server (1.5.0)
`run_payroll` and `preview_payroll` pass through the new `scheduled` status, `scheduled_send_at`, and `is_estimated` fields with no parameter changes — v1.4.0 callers continue to work (the new status is an additive enum value).
v1.4.0Single-call payroll (breaking)
POST /v1/payroll/run now finalizes in a single call
Breaking: the endpoint now creates, approves, and processes the payroll end-to-end. Previously it stopped at `status: draft` and required a human in the dashboard to finish.
Response `status` now reflects the real finalized state — `processing` (direct deposit ACH debit in flight), `pending_funding` (async DD funding), or `completed` (check/cash).
`pay_date` is now OPTIONAL. When omitted, the server picks the earliest valid pay date based on ACH submission lead time (5 business days, holiday-aware) and echoes it back as `pay_period.pay_date` in the response.
If `pay_date` is supplied and past the submission deadline, the API returns HTTP 400 with `details.next_valid_pay_date` so callers can self-correct.
Direct-deposit callers must now set `confirm_large_payroll: true` for totals >$5,000 or any single net pay >$3,000, and `confirm_ach_debit: true` for first-ever DD or when >30 days have elapsed since the last authorization. Mirrors the dashboard safety gates.
POST /v1/payroll/preview
`pay_date` is now optional on preview too, defaulting to the same server-computed value. Use this to validate a request before calling /v1/payroll/run.
MCP server
`run_payroll` and `preview_payroll` tools: `pay_date` is now optional.
`run_payroll`: added `confirm_large_payroll` and `confirm_ach_debit` parameters for direct-deposit safety gates.
v1.0.0Initial release
Public endpoints (no account required)
POST /v1/calculate — calculate household employer taxes for a single pay period across all 50 states
GET /v1/threshold — check if annual wages cross the IRS FICA threshold ($3,000 for 2026) and state-specific thresholds
Authenticated endpoints (Starter and above)
POST /v1/payroll/run — run payroll for one or more employees with YTD tax tracking
GET /v1/payroll/:id — retrieve a completed payroll by ID
GET /v1/employees — list employees for an employer (cursor-based pagination, PII-safe)
POST /v1/employees — create a new employee
GET /v1/employers — list all employers in your organization (Professional)
POST /v1/employers — create a new employer in your organization (Professional)
GET /v1/employers/:id/dd-status — check direct deposit readiness
POST /v1/documents/paystub — generate a pay stub PDF for a completed payroll
POST /v1/documents/w2 — generate a W-2 for a given tax year
POST /v1/ach/transfer — initiate direct deposit ACH transfer (Plus and above)
MCP server
Published @nannykeeper/mcp-server to npm
Supports calculate_nanny_taxes, check_threshold, and run_payroll tools via stdio transport
Compatible with Claude Desktop, Cursor, and any MCP-compliant client