API Reference

Last updated: April 2026 · Changelog · OpenAPI spec · Postman collection

Using Claude Code or an AI assistant?

All error responses include an example field with the correct request format and a docs_url link. Start with Preview payroll to test your payload without creating records. Your employer_id and employee_id UUIDs come from the List employees endpoint.

POST/api/v1/calculateFree

Calculate taxes

Calculate household employer taxes for a single pay period. Returns employer taxes, employee tax estimates, per-paycheck cost, and threshold status.

Note: Free-tier calculations assume zero year-to-date wages. Mid-year, this may overstate Social Security (caps at $184,500 wage base) and FUTA (caps at $7,000/employee). For accurate ongoing calculations, upgrade to a paid plan with automatic YTD tracking.

Required scope: calculator

Auth: Authorization: Bearer nk_live_YOUR_KEY · Content-Type: application/json

Parameters

Name	Type	Required	Description
state	string	Yes	2-letter US state code
annual_wages	number	Yes	Annual wages (0-999,999)
pay_frequency	string	No	weekly, biweekly, semimonthly, monthly. Default: biweekly
filing_status	string	No	single, married, head_of_household. Default: single

curl -X POST https://www.nannykeeper.com/api/v1/calculate \
  -H "Authorization: Bearer nk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "CA",
    "annual_wages": 35000,
    "pay_frequency": "biweekly",
    "filing_status": "single"
  }'

Back to Developer Home