canonical: https://jentic.com/apis/nannykeeper.com/nannykeeper # NannyKeeper API The NannyKeeper API calculates US household employer taxes for nannies and other household workers in all 50 states and DC, and runs payroll for NannyKeeper households. It estimates taxes for a single pay period from a state and annual wages, checks whether a worker's wages meet the per-worker FICA threshold, and previews or runs payroll with federal and state taxes and year-to-date tracking. It also lists and creates employers and employees, returns pay stub PDFs for a payroll, and starts direct deposit transfers. Live keys act on real households, while test keys act only on sandbox households where nothing is emailed, charged, or sent to a bank. ## For AI agents Calculate US nanny taxes by state, check the FICA threshold, preview and run household payroll, fetch pay stubs, and start direct deposit for NannyKeeper households. ## Scope Does not file tax returns, collect SSNs or bank details, or issue W-2s through the API. Use for US household employer tax calculation and NannyKeeper payroll only. ## Capabilities - Estimate household employer taxes for one pay period from state, annual_wages, pay_frequency, and filing_status - Check whether a worker's annual wages meet the per-worker FICA threshold for a tax_year - Preview a payroll as a dry run with full tax breakdown, net pay, and employer costs before committing - Run payroll for one or more employees with regular_hours, overtime_hours, bonus, and payment_method - Return pay stub PDFs for every employee on a payroll, base64-encoded in JSON - Create employer households and employees, and list employees with cursor pagination - Start a direct deposit ACH transfer for a payroll ## Use cases ### Agent-run household payroll through Jentic A parent's agent, connected through Jentic, handles the nanny's payroll each pay period. It sends the period dates, pay_date, pay_frequency, and each employee's hours to the preview operation, checks the net pay and employer costs, and only then submits the same payload to the run operation. Federal and state taxes and year-to-date totals are tracked by NannyKeeper. Example prompt: Call POST `/payroll/preview` with employer_id, pay_period_start='2026-11-02', pay_period_end='2026-11-15', pay_date='2026-11-20', pay_frequency='biweekly', and employees=[{employee_id, regular_hours: 80}], then POST `/payroll/run` with the same body ### Nanny tax estimates before hiring Families deciding on a salary want to know the full cost before making an offer. The calculate operation takes a two-letter state code and annual_wages, plus optional pay_frequency, filing_status, and residence_state for workers who live in another state, and returns the employer and employee tax picture for a single pay period in any of the 50 states or DC. Example prompt: Call POST /calculate with state='NY', annual_wages=52000, pay_frequency='weekly', and filing_status='single', then report the employer's total cost per pay period ### FICA threshold checks for occasional help Occasional sitters and housekeepers may or may not trigger household employer taxes. The threshold operation takes state and annual_wages, and an optional tax_year, and reports whether one worker's wages meet the per-worker FICA threshold, which the spec gives as $3,000 for 2026. FUTA and state unemployment depend on household quarterly wages and come back as unassessed. Example prompt: Call GET /threshold with state='TX', annual_wages=4200, and tax_year=2026, and tell the user whether FICA applies ### Pay stubs and direct deposit After a payroll runs, the pay stub operation returns a PDF for every employee on it, base64-encoded in data.documents with employee_id, file_name, and mime_type. The ACH transfer operation starts direct deposit to the employee, with a fee per subscription tier. W-2 and Schedule H endpoints exist but return 501 not_available_via_api, so those forms come from the dashboard. Example prompt: Call POST `/documents/paystub` for the latest payroll, decode each data.documents[] entry from base64, and save it under its file_name ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/calculate` | Calculate household employer taxes | | GET | `/threshold` | Check the FICA threshold | | POST | `/payroll/preview` | Preview payroll without saving | | POST | `/payroll/run` | Run payroll | | GET | `/employees` | List employees for an employer | | POST | `/documents/paystub` | Generate pay stub PDFs | | POST | `/ach/transfer` | Initiate direct deposit transfer | ## Key resources - **Tax calculations** — Per-pay-period household employer tax estimates by state - **Payrolls** — Previewed and committed payrolls with tax breakdown and YTD tracking - **Employers** — Household employer accounts, live or sandbox - **Employees** — Household employees attached to an employer - **Documents** — Pay stub PDFs returned as base64 in JSON ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 45 / 100 - **Maturity:** Foundational - **Dimensions:** - Foundational Compliance: 74 / 100 - Developer Experience & Jentic Compatibility: 62 / 100 - AI-Readiness & Agent Experience: 21 / 100 - Agent Usability: 94 / 100 - Security: 60 / 100 - AI Discoverability: 66 / 100 - **View full report:** https://jentic.com/apis/nannykeeper.com/nannykeeper/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring NannyKeeper by hand means juggling live and test bearer keys, knowing which operations need a Starter or Professional plan, and matching the date and pay_frequency formats the payroll body expects. Through Jentic you install once, import NannyKeeper from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** NannyKeeper carries the employer and employee ids in the request body for payroll, so rules bound which operations your agent may call, not which household. Limit the agent to the operations it needs, such as tax calculation and payroll preview; committing payroll or starting an ACH transfer is not included unless you add it. - **Credential handling:** Your NannyKeeper API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'calculate nanny taxes' or 'run household payroll', and Jentic returns the matching NannyKeeper operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Gusto Embedded Payroll API** — Embedded payroll for businesses with employees, contractors, and tax filing - **Paychex External API** — Payroll and HR data for Paychex client companies ## FAQ ### What authentication does the NannyKeeper API use? Per its OpenAPI spec, the NannyKeeper API uses a bearer API key. Live keys start with nk_live_ and act on real households; test keys start with nk_test_, are available on the Professional plan, and act only on sandbox households where nothing is emailed, charged, or sent to a bank. Through Jentic, the key is stored once by your own Jentic One instance and injected at call time. ### Can I preview payroll before running it with the NannyKeeper API? Yes. POST `/payroll/preview` takes the same body as POST `/payroll/run`, with employer_id, pay_period_start, pay_period_end, pay_date, pay_frequency, and employees, and returns the full tax breakdown, net pay, and employer costs without creating a payroll record. Both operations need a Starter plan or higher. ### Can the NannyKeeper API generate W-2s and Schedule H? Not through the API. POST `/documents/w2` and POST `/documents/schedule-h` validate the request and then answer 501 not_available_via_api; download those forms from Documents in the NannyKeeper dashboard. Pay stubs are available through POST `/documents/paystub.` ### What are the rate limits for the NannyKeeper API? The OpenAPI spec includes a rate limit exceeded error but does not state the limit itself. Plan limits do apply: each plan caps active employees per employer, and creating past the cap returns 403 with seat_limit_reached. See https://www.nannykeeper.com/developers for current limits. ### How do I calculate nanny taxes through Jentic? Install Jentic One with `curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh`, import the NannyKeeper API from the API Directory, and store your API key once. Your agent searches for 'calculate nanny taxes', gets the calculate operation with its input schema, and calls POST /calculate with state and annual_wages. To run it on your own infrastructure, install Jentic One from its GitHub repo. ### Can I limit what my agent is allowed to do with the NannyKeeper API? Yes. For an estimating assistant, write a rule that allows only POST /calculate, GET /threshold, and POST `/payroll/preview`, so the agent can price out wages and dry-run payroll but cannot commit a payroll or move money. Storing a test key instead of a live key keeps any calls on sandbox households.