# NannyKeeper — Complete API & Tax Reference

> Household employer tax compliance API. All 50 US states + DC.
> This file is auto-generated. Last updated: 2026-05-04

## API Overview

Base URL: `https://www.nannykeeper.com/api/v1`
Authentication: `Authorization: Bearer nk_live_YOUR_KEY`
Get a free key: https://www.nannykeeper.com/developers/keys

## Endpoints

### POST /api/v1/calculate
Calculate household employer taxes for a single pay period.

**Request body:**
```json
{
  "state": "CA",
  "annual_wages": 35000,
  "pay_frequency": "biweekly",
  "filing_status": "single"
}
```

**Parameters:**
- `state` (required): 2-letter US state code
- `annual_wages` (required): Annual wages, 0-999999
- `pay_frequency` (optional): weekly, biweekly (default), semimonthly, monthly
- `filing_status` (optional): single (default), married, head_of_household

**Response includes:** employer_taxes, employee_taxes_estimate, per_paycheck, threshold status, limitations, next_actions, signup_url

### GET /api/v1/threshold
Check if wages cross the household employer tax threshold.

**Query parameters:**
- `state` (required): 2-letter US state code
- `annual_wages` (required): Annual wages amount
- `tax_year` (optional): Tax year (default: current year)

### GET /api/v1/employers
List all employer accounts accessible to the API key. Requires Professional tier and multi_employer scope.

**Response fields (per employer):** id, first_name, last_name, email, state, is_primary, ein_status, created_at

### POST /api/v1/employers
Create a new employer account under the organization. Requires Professional tier and multi_employer scope.

**Request body:**
```json
{
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@example.com",
  "state": "CA"
}
```

**Parameters:**
- `first_name` (required): Employer first name
- `last_name` (required): Employer last name
- `email` (required): Employer email address
- `state` (required): 2-letter US state code for the employer's primary state

**Response fields:** id, first_name, last_name, email, state, is_primary, organization_id, created_at

## Pricing

| Plan | Monthly | Annual | Rate Limit | Employers | Employees |
|------|---------|--------|-----------|-----------|-----------|
| Free | $0 | — | 50/day | 1 | 1 (calc only) |
| Starter | $10 | $100 | 500/day | 1 | 1 |
| Plus | $18 | $180 | 2,000/day | 1 | 5 |
| Professional | $20 + $6/emp | $192 + $60/emp | 2,000/day | Up to 50 | 5/emp |
| W-2 Only | $10 one-time | — | — | 1 | 1 |

## Federal Tax Facts (2026)

- FICA cash wage threshold: $3,000/year per employee
- Social Security rate: 6.2% employer + 6.2% employee
- Social Security wage base: $184,500 (2026)
- Medicare rate: 1.45% employer + 1.45% employee
- Additional Medicare Tax: 0.9% on wages over $200,000 (employee only)
- FUTA rate: 0.6% on first $7,000 per employee
- FUTA quarterly threshold: $1,000 (aggregate across all employees)
- Schedule H: Filed with personal Form 1040
- W-2 deadline: January 31 of following year
- Quarterly deadlines: April 15, June 15, September 15, January 15

## State Tax Summary (2026)

| State | Income Tax | SUI Rate (New Emp) | SUI Wage Base | SDI | PFL | Local |
|-------|-----------|-------------------|--------------|-----|-----|-------|
| CA (California) | Progressive | 3.40% | $7,000 | 1.30% | 0.000% | — |
| NY (New York) | Progressive | 4.10% | $13,000 | 0.50% | 0.432% | Yes |
| TX (Texas) | None | 2.70% | $9,000 | — | — | — |
| FL (Florida) | None | 2.70% | $7,000 | — | — | — |
| PA (Pennsylvania) | Flat 3.07% | 3.07% | $10,000 | — | — | Yes |
| WA (Washington) | None | 0.90% | $78,200 | — | 0.807% | — |
| NJ (New Jersey) | Progressive | 2.79% | $44,800 | 0.19% | 0.230% | — |
| AK (Alaska) | None | 1.80% | $54,200 | — | — | — |
| NV (Nevada) | None | 2.75% | $43,700 | — | — | — |
| NH (New Hampshire) | None | 1.70% | $14,000 | — | — | — |
| SD (South Dakota) | None | 1.20% | $15,000 | — | — | — |
| TN (Tennessee) | None | 2.70% | $7,000 | — | — | — |
| WY (Wyoming) | None | 1.75% | $33,800 | — | — | — |
| GA (Georgia) | Flat 5.19% | 2.70% | $9,500 | — | — | — |
| IN (Indiana) | Flat 2.95% | 2.50% | $9,500 | — | — | Yes |
| KY (Kentucky) | Flat 3.50% | 2.70% | $12,000 | — | — | Yes |
| NC (North Carolina) | Flat 3.99% | 1.00% | $34,200 | — | — | — |
| MS (Mississippi) | Progressive | 1.00% | $14,000 | — | — | — |
| MO (Missouri) | Progressive | 2.70% | $9,000 | — | — | Yes |
| OH (Ohio) | Progressive | 2.70% | $9,000 | — | — | Yes |
| LA (Louisiana) | Flat 3.00% | 1.07% | $7,700 | — | — | — |
| AZ (Arizona) | Flat 2.50% | 2.00% | $8,000 | — | — | — |
| CO (Colorado) | Flat 4.40% | 1.72% | $30,600 | — | 0.440% | Yes |
| ID (Idaho) | Progressive | 1.00% | $58,300 | — | — | — |
| IL (Illinois) | Flat 4.95% | 3.40% | $14,250 | — | — | — |
| IA (Iowa) | Flat 3.80% | 1.00% | $20,400 | — | — | — |
| MA (Massachusetts) | Flat 5.00% | 2.56% | $15,000 | — | 0.460% | — |
| MI (Michigan) | Flat 4.25% | 2.70% | $9,500 | — | — | Yes |
| UT (Utah) | Flat 4.50% | 1.20% | $50,700 | — | — | — |
| AL (Alabama) | Progressive | 2.70% | $8,000 | — | — | Yes |
| AR (Arkansas) | Progressive | 3.10% | $7,000 | — | — | — |
| CT (Connecticut) | Progressive | 3.40% | $27,000 | — | 0.500% | — |
| DE (Delaware) | Progressive | 1.00% | $14,500 | — | 0.500% | Yes |
| DC (District of Columbia) | Progressive | 2.70% | $9,000 | — | 0.000% | — |
| HI (Hawaii) | Progressive | 5.40% | $64,500 | 0.50% | — | — |
| KS (Kansas) | Progressive | 2.70% | $15,100 | — | — | — |
| ME (Maine) | Progressive | 2.54% | $12,000 | — | 0.500% | — |
| MD (Maryland) | Progressive | 2.60% | $8,500 | — | 0.000% | Yes |
| MN (Minnesota) | Progressive | 1.00% | $44,000 | — | 0.440% | — |
| MT (Montana) | Progressive | 1.32% | $47,300 | — | — | — |
| NE (Nebraska) | Progressive | 1.50% | $9,000 | — | — | — |
| NM (New Mexico) | Progressive | 1.00% | $34,800 | — | — | — |
| ND (North Dakota) | Progressive | 1.07% | $46,600 | — | — | — |
| OK (Oklahoma) | Progressive | 1.70% | $25,000 | — | — | — |
| OR (Oregon) | Progressive | 2.10% | $56,700 | — | 0.600% | Yes |
| RI (Rhode Island) | Progressive | 1.15% | $30,800 | 1.10% | 0.000% | — |
| SC (South Carolina) | Progressive | 0.54% | $14,000 | — | — | — |
| VT (Vermont) | Progressive | 1.00% | $15,400 | — | 0.400% | — |
| VA (Virginia) | Progressive | 2.54% | $8,000 | — | — | — |
| WV (West Virginia) | Progressive | 2.70% | $9,500 | — | — | — |
| WI (Wisconsin) | Progressive | 3.50% | $14,000 | — | — | — |

## MCP Server

npm package: `@nannykeeper/mcp-server`

```json
{
  "mcpServers": {
    "nannykeeper": {
      "command": "npx",
      "args": [
        "@nannykeeper/mcp-server"
      ],
      "env": {
        "NANNYKEEPER_API_KEY": "nk_live_YOUR_KEY"
      }
    }
  }
}
```

### Tools
- `calculate_nanny_taxes(state, annual_wages, pay_frequency?)` — full tax breakdown
- `check_threshold(state, annual_wages, tax_year?)` — threshold status check
- `preview_payroll(employer_id, employee_id, ...)` — dry-run payroll calc, returns taxes/net pay without creating a record (Starter+ required)
- `run_payroll(employer_id, employee_id, pay_period_start, pay_period_end, pay_date, pay_frequency, ...)` — run payroll with YTD tracking and DB persistence (Starter+ required)

## Contact

- Website: https://www.nannykeeper.com
- API docs: https://www.nannykeeper.com/developers
- Email: hello@nannykeeper.com