NannyKeeper Household Payroll & Taxes

Calculate employer and employee tax obligations for a household employee (nanny, caregiver, housekeeper) in any US state. Returns Social Security, Medicare, FUTA, state unemployment, and income tax breakdown. State income-tax reciprocity: if the employee LIVES in a different state than they work (e.g., lives in Kentucky, works in Indiana), pass residence_state — for reciprocal pairs the response includes a `reciprocity` block naming the exemption certificate; pass reciprocity_certificate_on_file=true to suppress the work state's income tax (local taxes and SUI are unaffected). Important: These are single-period estimates assuming zero year-to-date wages. Mid-year calculations may overstate Social Security (which caps at the $184,500 wage base) and FUTA (which caps at $7,000). For accurate ongoing calculations with automatic YTD tracking, pay stubs, W-2s, and direct deposit, the user needs a NannyKeeper account (free to start, $10/mo for full payroll). Use the signup_url in the response.

Check whether one household employee's annual wages cross the IRS Social Security and Medicare threshold ($3,000 for 2026). The response discloses, but cannot assess, household-wide quarterly FUTA and state thresholds because this tool does not receive quarterly wages for every employee. It also cannot assess family-employee exemptions because it has no relationship input. Never interpret the result as a complete tax-obligation decision.

Read Autopilot status (recurring auto-run payroll). With employee_id: the live enrollment (status, standard hours, expected net, next pay date) plus eligibility and a 3-payday schedule preview — or, if not enrolled, WHY (the eligibility reason, e.g. not_plus / insufficient_history). Without employee_id: the list of the employer's active enrollments. Read-only. Requires a Plus/Professional key. To get employer_id/employee_id: GET /api/v1/employees?employer_id=YOUR_ID.

List the employer's state agency account numbers (last-four only) per (state, registration_type) tuple. Returns whether each state has a UC, withholding, and SDI account on file, and the agency name. Each account has a status: registered, pending, required, or not_required. A registration URL is returned for status=required and status=pending — the accounts the employer still has to open or finish. It is null for status=registered and status=not_required. status=not_required means this household does not owe that registration (e.g. they and their employee agreed not to withhold state income tax), so never tell them to go register for it. Use before generating quarterly filing instructions, or when a customer asks 'do I have my state account numbers set up?' Read-only — to update, use the REST API or direct the customer to /settings/states.

Manage an EXISTING Autopilot enrollment for a household employee. Actions: `pause` (stop new generation — an already-scheduled run still fires unless voided from the payroll page), `resume` (re-checks eligibility + clears the failure counter), `skip` (skip the next period; with through_date, skip every period up to that date for a vacation), `disable` (turn Autopilot off — soft-deleted so the ledger + ACH authorization are retained; the employee can re-enroll in-app). Turning Autopilot ON is NOT available here — it captures a standing recurring ACH authorization that must be done by the employer in the app. Requires a Plus/Professional key. Confirm the action with the user before calling.

Preview payroll for a household employee WITHOUT creating a record. Returns the full tax breakdown (federal, state, FICA, FUTA), net pay, and employer costs. Cross-state employees: each employee's result includes a `reciprocity` field when their work/residence states have a reciprocal agreement — applied=true means the work state's income tax was suppressed under the employer's certificate attestation (set up in the NannyKeeper app on the employee's profile); applied=false names the certificate still to collect. Use this to validate your request before calling run_payroll. Same parameters as run_payroll. Requires a Starter+ subscription. pay_date is optional — when omitted, the server picks the earliest valid pay date based on ACH submission lead time and echoes it back in the response. v1.5.0: if pay_date is more than 5 business days in the future, the response includes is_estimated=true — those numbers will be recomputed at fire time if the user schedules. To get your employer_id and employee_id, call the NannyKeeper API: GET /api/v1/employees?employer_id=YOUR_ID (employer_id is visible in your dashboard URL).

Run payroll for a household employee end-to-end in a single call. Creates the record, runs all tax calculations (federal, state, FICA, FUTA) with year-to-date tracking, approves the payroll, and kicks off payment processing. Returns the finalized status (processing/pending_funding/completed/scheduled) plus full tax breakdown, net pay, employer costs, and the payroll ID for reference. Requires a Starter+ subscription. Plans cap active employees per employer (Starter 1, Plus 5, Professional 5 included, expandable to 25 at $6/mo each); if the roster exceeds the plan's count, the API returns 403 with guidance — the user adds employees at Settings → Billing in the dashboard (never billed implicitly via API), then retry. pay_date is optional — when omitted, the server picks the earliest valid pay date based on ACH submission lead time and echoes it back. If supplied and past the submission deadline, the request is rejected with next_valid_pay_date in the error. If pay_date is more than 5 business days in the future on a DD payroll, status=scheduled and the payroll will auto-fire at scheduled_send_at (5 biz days before pay_date). Scheduled responses include is_estimated=true — numbers may shift slightly at fire time if YTD or rate configs change between approve and fire. Direct deposit callers: set confirm_large_payroll=true for totals >$5,000 or any single net pay >$3,000; set confirm_ach_debit=true for first-time DD or if no DD in 30 days. Tip: use preview_payroll first to validate your request and see results before committing. To get your employer_id and employee_id, call the NannyKeeper API: GET /api/v1/employees?employer_id=YOUR_ID (employer_id is visible in your dashboard URL).