Enrolling in a Dependent Care FSA?How to claim up to $7,500
Skip to main content

API Changelog

All notable changes to the NannyKeeper API, newest first.

v1.30.3California's 2026 FUTA credit reduction is priced in

POST /v1/calculate and /v1/calculate/demo

  • employer_taxes.futa now includes a state's published FUTA credit reduction, and total includes it with it. For 2026 that is California only: the Department of Labor's final determination (as of November 10, 2026) sets its reduction at 1.5%, so California FUTA is 2.1% of the first $7,000 of wages, up to $147 per employee, instead of 0.6% ($42).
  • Example, California, annual_wages 52000 ($25 an hour, 40 hours a week): employer_taxes.futa was 42 and is now 147; employer_taxes.total was 4265 and is now 4370. Texas at the same wages is unchanged: futa 42.
  • A year whose reduction the Department of Labor has not published yet is still priced at 0.6% and never forecast. No field is added or removed.
v1.30.2Mileage rates are capped at the IRS rate

POST /v1/payroll/run and /v1/payroll/preview

  • rate_per_mile on a mileage reimbursement now prices only up to the IRS standard mileage rate for the pay period and pay date. A higher rate prices at the IRS rate, because mileage paid above it counts as wages and a reimbursement here is never taxed.
  • A rate at or below the IRS rate prices as sent, as before. A rate of 0 is treated as no rate.
  • If NannyKeeper has no IRS rate for the pay date's year, the request is refused with a 400, code mileage_rate_unavailable, even when rate_per_mile is sent: without the IRS rate the cap cannot be checked.
  • A mileage line with an amount above 0 and no miles is refused with a 400, code validation_error. Mileage is priced from the miles; pay a non-mileage amount on an other line.
  • When rate_per_mile is left out, the miles price at the rate the household set for that employee if it has one (never above the IRS rate), else at the IRS rate.
  • A mileage line in the response's reimbursements.items may now also carry rateSource: irs, family (the household's or your own lower rate) or family_capped (a higher rate that priced at the IRS rate). Additive: lines priced before this change have none.

MCP server

  • preview_payroll and run_payroll describe the same cap: rate_per_mile, or the household's own rate, prices as sent at or below the IRS rate, and at the IRS rate above it.
v1.30.1The 9pm deadline-day cutoff applies all year

POST /v1/payroll/run

  • For a run that pays anyone by direct deposit, the submission deadline closes at 9pm ET whenever the day after that deadline is a weekday, not only at the year end. A Friday deadline still closes at midnight ET.
  • After 9pm the run is refused with a 400, code pay_date_past_deadline, and details.next_valid_pay_date. The message starts with a sentence you can show the household, such as "It's past 9pm Eastern, so your nanny's deposit can't land by Friday, November 13. Choose Monday, November 16, or pay your nanny by check."
  • A run paid entirely by check or cash is unchanged, and an omitted pay_date defaults to a date that can still be met.
v1.30.0The calculator follows the tax year

POST /v1/calculate and /v1/calculate/demo

  • tax_year is the year payroll prices a pay date falling today in, and every figure is that year's. From January the response is for the new year, not the old one.
  • Two new arrays are always present, empty when every figure is tax_year's own. fallback lists state figures served from the year before because tax_year's value isn't in NannyKeeper yet, each as { figure, from_tax_year }. not_published lists fields that read 0 because tax_year's value isn't in NannyKeeper yet and nothing stands in for it; total leaves them out.
  • employer_taxes.state_unemployment_not_published ({ tax_year, explanation }) is present when state_unemployment is 0 for that reason, alongside the existing state_unemployment_unassessed.
  • When tax_year's federal figures, or a state's figures, aren't in NannyKeeper yet, the response is the same 503 with code tax_year_not_supported it is today. Nothing else changes for callers that ignore the new fields.
v1.29.2Bank transfer and other as ways a household paid

GET /v1/payroll/{id}

  • paid_outside.family_method can now also be bank_transfer or other, alongside venmo, zelle, cash_app, paypal, check and cash. other means the household paid another way and didn't name it. Additive: treat a value you don't recognize as "paid outside".
  • payment_method on POST /v1/payroll/run is unchanged: check or cash for a paycheck the household pays itself, direct_deposit for one NannyKeeper deposits.
v1.29.1Setup status links open the right household

GET /v1/employers/:id/setup-status

  • ein.where_to_enter and bank.where_to_connect now carry ?employer={employer_id}, so the page opens on the household the response describes. Before, both opened the signed-in user's own household, and an EIN typed there was saved to it.
  • The link opens that household only for the account that owns it. Anyone else signed in sees, and saves to, their own household.
v1.29.0A notice for a pay period that has not ended

POST /v1/payroll/run and /v1/payroll/preview

  • When pay_period_end is after the date the server judged on, the response carries notices: [{ code: "period_in_progress", period_end, as_of, message }]. as_of is that date, in Eastern time. The run still goes through; the notice says the hours are final once the payroll is approved and time tracking for those days closes.
  • The notices key is absent when the period has ended. A period whose last day is as_of has ended.

MCP server 1.21.0

  • preview_payroll and run_payroll describe the notice, and preview_payroll tells the agent to confirm with the family before paying a period early. No parameter changes.
v1.28.8Minnesota's Workforce Development Assessment

GET /v1/taxes/quarterly

  • data.state_lines[].workforce_development_assessment: Minnesota's Workforce Development Assessment for the quarter, 0.10% of the quarter's taxable wages, from Q4 2026. It is 0 outside Minnesota and for earlier quarters.
  • The Minnesota unemployment destination's amount_owed (data.state_destinations) includes it, so the state's lines add up to it. Paychecks and pay stubs do not carry it. The field is additive.
v1.28.7MCP lookups are read-only

MCP server 1.20.3

  • get_pay_stub, get_w2, get_schedule_h and get_quarter_taxes are now marked read-only, as the API already treats them, so an assistant no longer asks for approval before each one. run_payroll, record_tax_payment, void_payroll and manage_autopilot stay marked as changes.
  • No tool, parameter or response changes.
v1.28.6Direct deposit pay dates are banking days

POST /v1/payroll/run

  • A run that pays anyone by direct deposit is refused when pay_date falls on a weekend or a Federal Reserve holiday, because a deposit cannot land that day. The refusal is a 400 with code pay_date_bank_closed and details.next_valid_pay_date, the banking day before it when the lead time reaches that day, otherwise the one after, or, when neither can be reached, the next payday the lead time reaches. It is never before the period end.
  • A run paid entirely by check or cash is unchanged, and an omitted pay_date is still defaulted to a banking day.
  • For a run that pays anyone by direct deposit on the last banking day of a year, the submission deadline closes at 9pm ET when the day after that deadline is a banking day. After that the run is refused with pay_date_past_deadline and details.next_valid_pay_date.
v1.28.5MCP tool descriptions state the bonus limit

MCP server 1.20.2

  • The bonus and other_earnings descriptions now say they take 0 to 99,999, the limit the API enforces since v1.28.4. No tool, parameter or response changes.
  • The reimbursements description on preview_payroll and run_payroll now says a transit or parking line over the month's IRS limit is refused, how much is left, and that the rest goes as other_earnings.
v1.28.4Bonus and other earnings: up to 99,999 per paycheck

POST /v1/payroll/run and /v1/payroll/preview

  • bonus and other_earnings now accept 0 to 99,999 for each employee on a payroll, the same limit as the payroll screen. A value above that returns a 400 validation error on employees[].bonus or employees[].other_earnings, with the message "Enter $99,999.00 or less." Before this, each accepted up to 999,999.
v1.28.3Transit and parking count the whole month

POST /v1/payroll/run and /v1/payroll/preview

  • A transit or parking reimbursement line is now refused when it would take the employee's total for the month over the IRS monthly limit. The month is the pay date's month, and every payroll for that employee with a pay date in it counts, drafts included. Voided payrolls do not count, and neither does a failed payroll the employee was not paid on.
  • The refusal is a 400 validation error on employees[].reimbursements[].amount. Its message says how much is left for the month. Pay any amount above that as other_earnings, which counts as wages.
v1.28.2Reimbursement lines are capped by type

POST /v1/payroll/run and /v1/payroll/preview

  • A transit or parking reimbursement line is refused above the IRS monthly limit for a tax-free transportation benefit: $325.00 for pay dates in 2025 and $340.00 for pay dates in 2026. The limit is per month across all of an employee's payrolls, so keep the month's total within it. Pay any amount above the limit as other_earnings, which is taxed.
  • An other reimbursement line is refused above $500.00. Mileage lines keep their existing bounds.
  • The refusal is a 400 validation error on employees[].reimbursements[].amount, from preview as well as run, so a preview never quotes a line that run would refuse. The payroll screen already applied these limits.
v1.28.1MCP tool descriptions name the Pro plan

MCP server 1.20.1

  • Tool descriptions now name the Pro plan, in get_autopilot, manage_autopilot and the employee-limit note, matching the hosted connector. The Autopilot tools' missing-key message says Pro too.
  • run_payroll's display title reads "Run payroll". No tools, parameters or response fields were added or removed.
  • Updated dependencies to fix security advisories.
  • Now requires Node 20 or newer.
v1.28.0An exempt W-4 claim reads as exempt only while it is in effect

W-4 exempt

  • w4.exempt on GET /v1/employees/{id} and GET /v1/employees/{id}/w4 is now true only while the employee's exempt claim covers today. An exempt claim covers pay dates through February 15 of the year after it was made; from February 16 payroll treats the W-4 as Single with no adjustments until a new W-4 is recorded.
  • w4.exempt_through is new: the last pay date the exempt claim covers, or null when the W-4 is not exempt. Additive.
  • PUT /v1/employees/{id}/w4 with exempt true on an employee whose claim has ended records a new claim dated today. It covers the current calendar year's pay dates through February 15 of next year. Sending back exempt false, as a GET now returns for an ended claim, keeps it ended.
  • PUT with exempt true while the claim is still in effect keeps the claim's original date, so it cannot extend it. The PUT response now returns exempt and exempt_through as stored, the same shape as GET.
v1.27.0A W-4 counts only once someone has entered it

Employee W-4 status

  • has_w4 on GET /v1/employees/{id}, w4.provided and missing on GET /v1/employees/{id}/setup-status, and w4_provided on GET /v1/employers/{id}/dd-status are now true only when the employee or the household entered a W-4. Before, an employee with no W-4 read as having one, because the default withholding answers were stored for them.
  • So for an employee whose W-4 was never entered, has_w4 is now false, missing includes "w4", and fully_onboarded is false until one is. The w4 object still returns the default answers payroll withholds on.
v1.26.0See whether a paycheck paid outside NannyKeeper arrived

GET /v1/payroll/{id} shows how it was paid

  • Each employee now has paid_outside. It is null for a direct deposit. For a paycheck the household pays itself, it has family_method (venmo, zelle, cash_app, paypal, check or cash, or null when the household didn't say) and confirmation: confirmed, mismatch, waiting or not_asked. Additive.
  • mismatch means the employee said the pay doesn't match what arrived. NannyKeeper never asks for the amount, so there is no difference to report. waiting and not_asked are ordinary states, never an error.

GET /v1/payrolls

  • Each payroll now has paid_outside_confirmation: mismatch if any employee said so, otherwise waiting, otherwise confirmed, and null when nobody was asked. Additive.

MCP server 1.20.0

  • get_payroll and list_payrolls return the new fields, on the hosted connector and the npm package alike.
v1.25.0Record a tax payment, and void a payroll that has not moved money

POST /v1/taxes/payments

  • New endpoint. Record that the household paid a quarter's tax to the IRS (destination federal) or a state agency (an id from GET /v1/taxes/quarterly), as "I've paid this" on the Taxes page does. Once it covers what is owed, NannyKeeper stops reminding them about it. NannyKeeper does not send the payment.
  • Send expected_amount when the household paid the figure NannyKeeper showed. It must still be the current figure: if a payroll changed it, the answer is 409 figures_changed with the current_amount. Send amount when they paid something else, with closes_filing: true when that amount settles a state agency's filing.
  • Idempotency-Key, so a retry never records a payment twice; required with amount. Scope payroll, Starter+. employer_id is optional.

POST /v1/payroll/{id}/void

  • New endpoint. Call it with no body and nothing is voided: you get the payroll (employees, pay period, gross, pay date) and a confirmation_code that works for 10 minutes, for that payroll and that API key only. Call it again with confirmation_code and a reason, and the payroll is voided exactly as the app's Void button does it.
  • Only a draft, or a scheduled direct deposit whose bank debit has not started. A payroll with money already on the move (approved, pending funding, processing) or a completed one answers 409 payroll_not_voidable_via_api with details.app_url: void it in the app, where you see what undoing it means.
  • If the payroll's debit started between the two calls, the second answers payroll_not_voidable_via_api too. A code is refused if it has expired (confirmation_expired), was issued for another payroll or key (confirmation_invalid), or the payroll changed in another way after it was issued (payroll_changed). Nothing is voided; start again from the first call.
  • Scope payroll, Starter+. employer_id is optional, like every other endpoint.

MCP server 1.19.0

  • New tool record_tax_payment(year, quarter, destination, expected_amount or amount, closes_filing?, idempotency_key, employer_id?), on the hosted connector and the npm package alike. Tell your assistant you paid this quarter's taxes and it records it.
  • New tool void_payroll(payroll_id, confirmation_code?, reason?, employer_id?), on the hosted connector and the npm package alike. Your assistant shows you the payroll and asks before it voids anything.
v1.24.0Mileage and payroll history from your assistant

GET /v1/payrolls filters by employee and pay date

  • New optional filters: employee_id (only payrolls that paid that employee; one not in the household answers 404) and pay_date_from / pay_date_to (an inclusive pay-date range, YYYY-MM-DD).
  • Each payroll now lists employee_ids, the employees it paid. Additive.
  • Fixed: a second page could skip some payrolls and repeat others, because the cursor did not follow the list's order. next_cursor now does, and a cursor issued before this change still works.
  • A cursor the list did not issue now answers 400 invalid_cursor instead of starting over at page 1.

POST /v1/payroll/run totals include reimbursements

  • Fixed: totals.total_cost left out reimbursements, so a payroll with a mileage line reported the family's cost short by that amount. It now matches /v1/payroll/preview.
  • dd_status.message on preview and run no longer reads as if this paycheck goes by direct deposit. It says direct deposit is set up for the household, and that a check or cash paycheck is the family's to hand over.

MCP server 1.18.0

  • preview_payroll and run_payroll take reimbursements: up to 10 mileage, transit, parking or other lines, the same lines and limits as the API. For mileage, send the miles and amount 0.
  • New tool list_payrolls(employee_id?, pay_date_from?, pay_date_to?, limit?, cursor?): ask your assistant what you paid your nanny last time, or for your last three payrolls.
  • Setup now runs @nannykeeper/mcp-server@latest, so npx picks up each new release instead of a cached older one. If you added the server before, change the package to @nannykeeper/mcp-server@latest in your config (or run claude mcp remove nannykeeper and add it again), then restart your client.
v1.23.0A quarter's tax figures over the API

GET /v1/taxes/quarterly

  • New endpoint. Pass year and quarter, and get the quarter as the household's Taxes page shows it: the checklist of what to pay or file, to whom and by when (data.items), the optional federal estimated payment for the IRS installment (data.federal), each state agency's amount and due date (data.state_destinations), and wages with each state and local line (data.state_lines).
  • A null amount means NannyKeeper will not stand behind a figure yet, and waiting_on says why: unemployment_rate, state_figures or payment_review. Never read it as $0.
  • Scope payroll, Starter+. employer_id is optional, like every other endpoint.

MCP server 1.17.0

  • New tool get_quarter_taxes(year, quarter, employer_id?), on the hosted connector and the npm package alike. Ask your assistant what you owe or have to file this quarter.
v1.22.0Oregon's Workers' Benefit Fund on payroll

Payroll responses carry the Oregon Workers' Benefit Fund

  • A household that tells NannyKeeper it carries workers' comp coverage for an Oregon employee, with the date the coverage started, now has the Workers' Benefit Fund assessment priced on each paycheck. Half is withheld from pay and the employer pays an equal half.
  • POST /v1/payroll/preview: employee_deductions.workers_benefit_fund and employer_taxes.workers_benefit_fund, each inside its total. POST /v1/payroll/run: employee_deductions.workers_benefit_fund. GET /v1/payroll/{id}: workers_benefit_fund, employer_workers_benefit_fund and workers_benefit_fund_basis.
  • Every field is 0 outside an elected Oregon household. A basis starting not_assessed means the paycheck was not priced (the pay period began before the coverage did, or Oregon has not set the year's rate), so the 0 beside it is not an amount. All fields are additive.
v1.21.0Maryland county tax under a DC, Virginia or West Virginia exemption

POST /v1/calculate returns no Maryland county tax when the exemption covers it

  • For a Maryland job held by a District of Columbia, Virginia or West Virginia resident, with reciprocity_certificate_on_file true, employee_taxes_estimate.local_tax is now 0 and total falls by the same amount. The reciprocity note already said no county tax is withheld; the number now agrees with it and with what payroll withholds. On $60,000 that is about $1,870 a year.
  • A Pennsylvania resident working in Maryland is unchanged: that exemption covers state tax only, so the county line stays. Quotes without the certificate, and quotes for Maryland residents, are unchanged too.
  • meta.tax_data_version is now 2026.8.
v1.20.0A bank link for the employer

POST /v1/setup/bank returns a link the employer opens

  • The response is data.setup_url and data.expires_at: a link on nannykeeper.com that works for one hour. The employer opens it, connects the bank that funds payroll and accepts the debit authorization, with no NannyKeeper login.
  • When the bank connects, the employer is sent to your return_url with status=connected and employer_id added. An account entered by hand needs a small deposit first, so it comes back with status=pending_verification and we email the employer how to finish.
  • return_url must be https on a host you list under Allowed return hosts on your API key. Anything else returns 400 return_url_not_allowed.
  • Only for a household with no funding bank. A household that has one returns 409 funding_bank_exists, with the dd-status path in details. Each key can create 10 links an hour.

It stops answering 501

  • Since October 2026 this endpoint answered 501 not_available_via_api. If your code handles that code here, it can come out.
v1.19.0W-2s and Schedule H over the API

POST /v1/documents/w2 returns the W-2

  • The response is JSON. data.document has file_name, mime_type, encoding ("base64") and data, the PDF. It is the W-2 the household downloads in the dashboard. New optional copy (A, B, C, D, 1 or 2) picks the copy, and B is the default.
  • The household generates the W-2 in NannyKeeper first. Until then the answer is 409 w2_not_generated. A tax year that has not ended answers 409 tax_year_not_ended.
  • NannyKeeper records each W-2 a key takes.

POST /v1/documents/schedule-h returns Schedule H

  • The response is JSON with the same data.document shape. It is the Schedule H the household downloads in the dashboard.
  • When the dashboard would not produce the form, the answer is 409 schedule_h_unavailable with details.reason: year_not_ended, no_household_data, prior_wage_overlap, prior_wage_withholding_unknown or futa_prior_year_unanswered.

A download link in place of the PDF

  • Both endpoints take a new optional delivery. Leave it out, or pass "file", and you get the PDF as before. Pass "link" and you get data.download with url, expires_at and file_name: a link on nannykeeper.com that needs no key and works for 15 minutes. Use it to send the PDF straight to a person's browser.

Both stop answering 501

  • Since v1.18.0 these two endpoints answered 501 not_available_via_api. If your code handles that code, it can come out.

MCP server 1.16.0

  • Two new tools, get_w2 and get_schedule_h. They return a download link, not the PDF: a W-2 shows a full Social Security number, so the tool never sends the form to the assistant. The assistant gives you the link, you open it in your browser, and it works for 15 minutes.
v1.18.0Pay stubs over the API, and MCP tools that find your household

POST /v1/documents/paystub returns the pay stub

  • The response is JSON. data.documents has one entry per employee on the payroll, with employee_id, document_id, file_name, mime_type, encoding ("base64") and data, the PDF. It is the stub the household downloads in the dashboard.
  • Before this release the endpoint answered status: "generated" with no PDF. If your code read that, read data.documents instead.

Social Security and Medicare an employer pays for the employee

  • A household can now pay its employee's share of Social Security and Medicare instead of withholding it (work in California or Washington for now, set on the employee's page). preview, run and GET /v1/payroll/{id} carry a new per-employee field, employer_paid_employee_fica: the part of social_security and medicare the employer paid. preview and run also carry totals.total_employer_paid_employee_fica. Both are 0 unless the household turned this on.
  • When you reconcile gross to net on those paychecks, add employer_paid_employee_fica back: the tax lines and total_employee_taxes still show the full share, because it is still owed, and net_pay no longer has it taken out. total_cost includes the amount.
  • In Washington the household also pays Paid Leave and WA Cares premiums on the share it covers. That is our choice, because the state has not said whether the covered share counts as wages. The Paid Leave part is inside employer_paid_family_leave, and the WA Cares part is a new field: employer_paid_wa_cares on GET /v1/payroll/{id}, and employer_taxes.wa_cares on preview. Both are inside total_employer_taxes and total_cost, and neither is taken from the employee's pay.

POST /v1/documents/w2 and /v1/documents/schedule-h answer 501 (breaking)

  • They now validate the request and answer 501 not_available_via_api, with where_to_download in details. Before, they answered 200 status: "generated" with no document. Download W-2s and Schedule H from Documents in the dashboard until these return the PDF.

Payroll dates

  • Leave out pay_date and we now pick the earliest valid pay date that is a business day on or after pay_period_end. Before, a period still running could get a pay date before it ended: preview priced it and run refused it.
  • preview and run answer 400 when pay_date is before pay_period_end, or pay_period_end is not after pay_period_start, naming the field.
  • preview sets is_estimated only when a direct-deposit line would be scheduled. Check and cash payrolls run at once, so their figures are final.

Reading what you ran

  • GET /v1/payroll/{id}: each employee now carries local_tax, additional_medicare, state_disability, paid_family_leave, wa_cares, employee_unemployment, total_employee_taxes, total_reimbursements, total_voluntary_set_asides, catchup_fica_recovery and employer_paid_family_leave, so the deductions add up from gross to net.
  • GET /v1/employees and /v1/employees/{id}: new effective_work_state, the state whose payroll rules apply. work_state is still the stored override and is usually null.
  • When a request fails a check inside payroll creation, the message is now a sentence naming the field (with details.issues), not a JSON list.

MCP server 1.15.0

  • New tools: list_employees (returns your employer_id and each employee_id, so an agent never has to ask you for them), get_payroll and get_pay_stub (the PDF arrives as an attached file).
  • employer_id is optional on preview_payroll, run_payroll, get_autopilot and manage_autopilot. Leave it out and the household your key belongs to is used.
  • Claude Code: claude mcp add nannykeeper --env NANNYKEEPER_API_KEY=nk_live_YOUR_KEY -- npx -y @nannykeeper/mcp-server
  • Claude Desktop shows the server only after you add it to claude_desktop_config.json or install its .mcpb bundle. A listing in the MCP registry does not add it. The setup page now says so.
v1.17.0New Jersey's threshold is a calendar year

GET /v1/threshold: threshold_annual (OpenAPI 1.3.0)

  • For New Jersey, state_threshold and state_unemployment_threshold now return an object with threshold_annual: 1000, status "unassessed" and an explanation. A New Jersey household becomes an employer once it pays $1,000 in a calendar year, this year or last, not in one quarter.
  • In that object threshold_quarterly is present and null, so code that reads threshold_quarterly gets null, the same answer it got before 1.3.0. Before this, both fields were null for New Jersey, which this API documents as following the federal quarterly threshold. Every other state is unchanged.
v1.16.3Paid time off: the year it runs on

POST /v1/payroll/preview and POST /v1/payroll/run

  • New on time_off: year. It is null when the paycheck's time-off year is the calendar year, or { starts_on, next_starts_on } (dates, next_starts_on not included) when the family set another year, such as the employee's work anniversary. Nothing else in time_off or sick_leave changes.

GET /v1/employees/{id}

  • New on time_off: year, with starts_on, next_starts_on and basis (calendar, anniversary or date): the time-off year that holds today in the employee's work time zone. Both balances run on this year, except where the state's sick leave rule does not accept it: then sick_year carries sick leave's own { starts_on, next_starts_on }. sick_year is null otherwise.
v1.16.2W-4 amounts: limits, and a saved W-4 now takes effect

PUT /v1/employees/{id}/w4

  • The four amounts now have limits. dependents_amount (Step 3) is 0 to 100,000; other_income (Step 4(a)) and deductions (Step 4(b)) are each 0 to 1,000,000 a year; extra_withholding (Step 4(c)) is 0 to 10,000 a paycheck. Each takes at most two decimal places. A value outside these returns a 400 validation error naming the field; nothing is rounded or capped for you. Before this, each field accepted up to 999,999.
  • A W-4 saved here now sets the employee's w4_status to employer_entered, as saving it in the app does. Before this, a W-4 saved for an employee whose status was pending was stored and returned by GET, but payroll kept withholding at the IRS defaults until the status changed some other way.
v1.16.1Payroll preview: a state's figures not yet loaded

POST /v1/payroll/preview

  • New 400 error code state_figures_unavailable, returned when the work state's tax figures for the pay date's year aren't loaded yet. error.details carries state and tax_year. It is not retryable: it clears when we publish that state's figures for the year. Before this, the same request returned a 500.
v1.16.0Paid time off: sick leave and vacation balances

POST /v1/payroll/preview and POST /v1/payroll/run

  • New on each employee in both responses: time_off, with two entries, sick and vacation. Each is null when that balance isn't tracked for the employee, or { hours_earned_this_period, hours_used_this_period, balance } in hours.
  • sick also carries source, either state_default (the state's own rule) or family (a policy the family set, or hours they gave up front), and method: state_rule, accrual or frontloaded. vacation carries method: accrual or frontloaded. A vacation balance can be below zero.
  • sick_leave is unchanged. On run, time_off is read from what the paycheck stored; a paycheck stored before this change reports source state_default when sick leave was tracked.

GET /v1/employees/{id}

  • New: time_off, with sick ({ tracked, method, balance }) and vacation ({ method, balance }), each null when not tracked. Balances are as of today in the employee's work time zone. It is on the single employee only, not on the list.
v1.15.2Local taxes not withheld: Philadelphia residents working outside the city

POST /v1/payroll/preview and POST /v1/payroll/run

  • local_taxes_not_withheld has a second reason, resident_not_withheld: the employee's home address is in Philadelphia, which taxes its residents' pay wherever they work, while the job is outside the city. A household employer isn't required to take it out, so the employee pays it to the city directly as the Earnings Tax. jurisdiction is Philadelphia and rate is the city's resident rate on the pay date.
  • An employee can have two entries: for example, a Philadelphia resident working for a Wilmington family has an employee_consent_absent entry for Wilmington and a resident_not_withheld entry for Philadelphia.
  • There is no entry for pay dates before 2026 or past the city's latest published rate, or when the home address on file isn't recognised as Philadelphia, PA. local_tax and the totals do not change: nothing is withheld for this reason.
v1.15.1Payroll preview: local taxes not withheld, and why

POST /v1/payroll/preview and POST /v1/payroll/run

  • New on each employee in both responses: local_taxes_not_withheld, a list of local taxes we priced and did not take out, each as { state, jurisdiction, rate, reason }, where rate is a fraction (0.03425 means 3.425%). It is an empty list when there are none, and local_tax already excludes them. On run it is read from what the paycheck stored, so paychecks stored before this change return an empty list.
  • reason is one of a fixed set, today only employee_consent_absent. More reasons may be added later, so treat an unknown one as not withheld.
  • Philadelphia's wage tax is no longer withheld from a household employee's pay unless the employee agrees to it, the same rule Wilmington's earned income tax already followed. NannyKeeper does not record that agreement yet, so these employees show local_tax 0 with an employee_consent_absent entry.
  • The warnings array no longer carries a sentence about either city's tax not being withheld; local_taxes_not_withheld replaces it. Before this, a Wilmington employee's preview included one.
v1.15.0Calculator responses say what they cannot know

action_required is now true or null (OpenAPI 1.2.0)

  • On POST /v1/calculate, POST /v1/calculate/demo and GET /v1/threshold, action_required is true when the worker's annual wages meet the FICA threshold and null otherwise. It is never false.
  • Before this, /v1/calculate and the demo returned false below the threshold, which read as nothing owed, and /v1/threshold returned null on every response. Below the threshold a household can still owe FUTA or state unemployment tax. If your code checks for false, treat null the same way: not determined, not nothing owed.

New fields on /v1/calculate and the demo

  • threshold.assessment_scope is fica_only, matching /v1/threshold.
  • A futa block reports FUTA as unassessed, with the year's quarterly trigger, because it depends on the household's quarterly wages across all employees in this year and last year.
  • limitations now says that no employee relationship or age was provided, so neither a family-employee exemption (from Social Security, Medicare and FUTA) nor the under-18 exemption (from Social Security and Medicare only) is applied to the taxes quoted. The demo response gains a limitations array.
  • No existing field was removed or renamed, and no tax amount changed.
v1.14.1MCP documentation corrections

Bundled guidance

  • Example prompts now direct clients to current tool results, with their assumptions and limitations, instead of outdated sample tax totals.
  • The privacy description explains the personal and financial information exchanged by account tools. State-account instructions document household selection for sandbox and multi-household accounts.
v1.14.0MCP transport support and connection safeguards

MCP server

  • All seven tools now share one server implementation for local and hosted connections. Existing stdio API-key configuration continues to work.
  • Hosted connections use account consent, short-lived OAuth access tokens, and revocable connections. Hosted payroll calls require an idempotency key so retries reuse the original request.
v1.13.2Payroll preview now checks your employee list the same way run does

POST /v1/payroll/preview

  • POST /v1/payroll/preview returns 400 for a duplicate employee id, a list over your plan's limit, an id that isn't on your household, or an employee whose start date falls after the pay period ends.
  • Before this, an id you don't own was dropped silently and the preview total quietly left someone out.
  • Any payload that run already accepted is unchanged.
v1.13.1Test keys stay out of real households

Two endpoints were not enforcing the test/live boundary

  • Test and live keys are meant to reach different households: a test key only sandbox ones, a live key only real ones. `GET` and `POST /v1/state-registrations` never actually checked, and the four Autopilot manage routes (`pause`, `resume`, `skip`, `disable`) checked in a way that could never fail. Both now enforce it, the same way every other endpoint already did.
  • The practical effect: a `nk_test_` key could read and write a real household's state agency account numbers — including decrypting them with `?reveal=true` — and could pause or disable Autopilot on live payroll. A mismatched call now returns `403` with a message naming which key type the household needs.
  • The Autopilot routes were also not enforcing employer ownership. Passing an `employer_id` you don't own did not fail; it silently fell back to your primary household and acted on that one instead. It now returns `403`.
  • `GET` and `POST /v1/state-registrations` now accept an optional `employer_id`, matching every other endpoint. Leave it off and you get the household your key is tied to, exactly as before — nothing to change. Pass it to reach a specific household, which is what a test key needs (its stamped household is your real one) and what a Pro account with more than one household needs to reach any but the primary.
  • ⛔ `employer_id` is not a way to switch modes. Whatever you pass is checked for both ownership and test/live, so a test key naming a real household is still refused — it just now tells you why instead of silently reading it.
  • ⚠️ No integration is affected. Every active key was checked before this shipped: all 12 are live keys pointed at real households, and there were no test-mode keys at all — so every existing call, with or without the new parameter, behaves exactly as it did. To build against the sandbox, create a sandbox household with `POST /v1/employers` using a test key, then pass its id as `employer_id`.
  • One narrow case to know about if you mint keys programmatically: a key stores the household it was created under. If a live key was somehow created while a sandbox household was selected, it would now be refused when called without `employer_id` — pass the real household id, or create a fresh key. No such key existed when this shipped.
v1.13.0State registrations a household doesn't owe

GET /v1/state-registrations — new `not_required` status

  • `status` gains a fourth value, `not_required`, alongside `registered`, `pending` and `required`. It means this household genuinely does not owe that registration — most often because the family and their employee agreed not to withhold state income tax in a state that treats withholding as voluntary.
  • Previously the status was derived from account-number presence and the registered flags alone, so a household that had opted out still came back as `required` with a registration URL, while every screen in the app told them the opposite. If your integration switches on `status`, add a `not_required` branch.
  • `registration_url` is now `null` on a `not_required` row. It is still returned for `required` and `pending` rows -- the accounts they have to open or finish -- and, on this endpoint, for `registered` rows too. Treat `required: false` rather than the presence of a URL as the signal to stop prompting. (The MCP tool additionally nulls it for `registered`, so an agent sees a URL only where there is something left to do.)
  • Each item also carries a new `required` boolean: true when there is still something to do for that account (nothing recorded, or recorded as pending), false once it is on file or the household does not owe it. If your integration branches on `registered` alone, switch to `required` — `registered` is `false` for a household that does not owe the account at all, so a `!registered` loop keeps prompting them.
  • ⚠️ Household-awareness currently covers the `withholding` account only. The `sui` row still reports `required: true` for a household whose whole workforce is family (a spouse, parent, or child under 21), where the app shows "Not required". If you surface unemployment registrations, do not treat that row as household-scoped yet.
  • Withholding rows are no longer returned for Alabama, Arizona, Arkansas, Oklahoma or South Carolina. Those states levy an income tax but exclude domestic service from withholding, so there is no account to open and no return to file -- the app has never shown that row, and this endpoint should not have either.
  • This is per-household, not per-state: two families in the same state can legitimately get different answers, and the answer changes when they hire, terminate, or turn withholding back on.

MCP server — shipped in 1.10.2

  • `get_state_filing_status` reports the new status and withholds the registration URL for it, so an agent drafting filing instructions no longer tells a household to open an account they don't owe. Its tool description now defines `not_required` for the model.
  • ⚠️ Update to 1.10.2. npm sat on 1.7.1 from June while this, the `employer_id` parameter, and the Autopilot tools were all finished, so any earlier install is missing every one of them. `npx @nannykeeper/mcp-server@latest` picks up the current build; pinned installs need the pin moved.
  • ⛔ Skip 1.9.0, 1.10.0 and 1.10.1. 1.9.0 was published from a stale build directory and contains none of the above — it is mid-June code carrying a later version number. 1.10.0 has the right code but introduces itself to your client as `1.9.0`, because the version in the handshake was a separate hardcoded string that release checklists never covered; it is now derived from the package itself and cannot drift again. 1.10.1 is functionally identical to 1.10.2 and safe to stay on. Nothing in any of them is broken or unsafe and no behaviour regressed, but npm versions are immutable, so none could be corrected in place.
  • Why the old build matters specifically: 1.7.1's tool description still promises "a registration URL for any that are missing" and has never heard of `not_required`. An agent handed that promise, a status its prompt never defines, and a null URL may well treat the null as an omission and tell the family to register anyway — the exact thing this change exists to stop. The REST endpoint has been correct for everyone throughout; it is the prompt that was stale.
v1.12.0Employee invitations actually send

POST /v1/employees/{id}/invite now emails the employee

  • This endpoint created a valid invitation but never sent the email, while reporting `email_sent: true`. It now sends the same email the dashboard sends, and `email_sent` reflects what actually happened.
  • If you were working around this by delivering `portal_url` yourself, nothing breaks — but the employee will now also get our email. Pass `send_email: false` to keep delivery entirely in your hands.
  • The endpoint now shares one implementation with the dashboard rather than its own. Three behaviors come with that: sending a new invitation cancels any pending one of the same type (previously every call minted another live token), bank invitations require direct deposit to be available, and bank invitations are limited to one per employee per 24 hours.
  • That rate limit returns HTTP 412 with the time you can retry. It does not apply when `send_email` is false, since nothing reaches the employee's inbox.
v1.11.0Bank setup docs & one retirement

POST /v1/ach/transfer is retired — use /v1/payroll/run

  • This endpoint returned `{"status": "initiated"}` without moving money — the transfer itself was never implemented. It now returns 410 Gone and has been removed from the reference, so it can't be mistaken for a working call.
  • Direct deposit is initiated by `POST /v1/payroll/run` with `payment_method: "direct_deposit"` on each employee. That single call runs the payroll and fires the ACH, with the debit authorization and large-payroll checks applied.
  • If you integrated against /v1/ach/transfer, no ACH was ever sent by it — check those payrolls in `GET /v1/payrolls` and re-run any that never funded.

POST /v1/employees/{id}/invite — now documented

  • Creates a secure portal link so an employee can enter their own bank account (`type: "bank_account"`) or tax details (`type: "tax_info"`). It was always available; it just wasn't in the reference.
  • Bank account and SSN details are never accepted as API fields, by design — the account holder enters and authorizes their own direct deposit. This endpoint is how you get them there.
  • Returns `portal_url`, valid for 7 days. Automatic email delivery isn't wired up yet, so `email_sent` now always reports false (it previously reported true without sending) — deliver the link yourself for now.

Connecting an employer's bank

  • There's no API equivalent for the employer's own funding bank yet — the employer connects it once at Settings → Bank in the app, after which your integration can run direct deposit for them indefinitely. A hosted link version is on the roadmap.
v1.10.0Test mode & sandbox households

Test-mode API keys (nk_test_)

  • You can now build against NannyKeeper without creating households in production. Create a test key at /developers/keys (Pro plan) — it looks like `nk_test_…` and works on every endpoint a live key does.
  • A test key reaches ONLY sandbox households, and a live key reaches ONLY real ones. There's no request parameter to switch — the credential you call with decides, so a test key can never write into a real household by accident.
  • Sandbox households are exempt from all outbound side effects: no email to employees, no Stripe charges, no ACH, no filings. Tax math is the real engine, so previews and payroll runs return the same numbers production would.

POST /v1/employers (test mode) — create a sandbox household

  • Same endpoint and payload as creating a real household, but called with a test key. `email` is optional in test mode (nothing is ever sent to it) and the response carries `sandbox: true`.
  • Up to 3 sandbox households per account, and they don't count toward your Pro employer limit or your bill.
  • GET /v1/employers is mode-scoped the same way: a live key lists your real households, a test key lists your sandboxes.

DELETE /v1/employers/{id} — clean up after yourself

  • Delete a sandbox household and everything in it, or pass `?reset=true` to wipe its employees and payrolls while keeping the household id so your fixtures keep resolving.
  • Test keys only. Real households can't be deleted through the API — their payroll records are tax records.
  • You can also create, reset, and delete sandboxes from /developers/keys if you'd rather click.
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/Pro) — 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 (Pro)
  • POST /v1/employers — create a new employer in your organization (Pro)
  • 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

Rate limits

  • Free tier: 50 requests/day
  • Starter: 500 requests/day
  • Plus: 2,000 requests/day
  • Pro: 2,000 requests/day