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 annual estimates from annual_wages, with derived per-paycheck amounts. They do not read an existing employee's year-to-date payroll records; use preview_payroll for an existing employee. This tool has no family-relationship or age input, so Social Security, Medicare and FUTA are quoted as if no family-employee exemption (Social Security, Medicare and FUTA) or under-18 exemption (Social Security and Medicare only) applies, and FUTA's household quarterly test is reported as unassessed. threshold.action_required is true when the FICA wage test is met and null otherwise, never false: present null as not determined, not as nothing owed, and pass on the response's limitations. 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. federal.action_required is true when the FICA wage test is met and null otherwise, never false; null means not determined, not nothing owed. 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. Get employee_id from list_employees; employer_id is optional.

Get the pay stub PDF for each employee on a paid payroll. Returns the same stub the family downloads in the dashboard, attached as a PDF file, plus a short summary. A payroll that is not paid yet answers payroll_not_completed; check get_payroll and ask again once it is completed. For a household other than the key's own, pass its employer_id.

Read payrolls. With payroll_id: that payroll's status, dates, and each employee's gross pay, every deduction (federal, Social Security, Medicare, state, local), net pay, and employer taxes. Without payroll_id: the household's payrolls, newest first, with totals. Use it to confirm what run_payroll created. Read-only.

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. The response also carries `obligations`: this household's FICA, FUTA and per-state unemployment status (started, not_started, exempt or unassessed), registration state, estimate, action and the agency's real due date. When `assessment` is incomplete or a status is unassessed, never tell the customer they owe nothing or are all set.

List the household's employees and return the household's employer_id. Call this first: it is how you get the employee_id every payroll tool needs. Each employee shows pay type, pay rate, pay frequency, work state, and what is still missing for payroll (W-4, address, SSN, direct deposit). Read-only.

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 business day on or after pay_period_end, allowing for 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. Get employee_id from list_employees. employer_id is optional: leave it out and the API uses the household your API key belongs to (pass it only when one account manages several households).

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 business day on or after pay_period_end, allowing for 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. Get employee_id from list_employees. employer_id is optional: leave it out and the API uses the household your API key belongs to (pass it only when one account manages several households).