Skip to main content
The TaxHomeBase API is a RESTful JSON API that powers the web application. All endpoints are accessible at https://app.taxhomebase.com/api/v1/.

​
Base URL

https://app.taxhomebase.com/api/v1

​
Authentication

All endpoints (except health check and Stripe webhook) require a valid JWT access token from AWS Cognito. Pass it in the Authorization header: 
Authorization: Bearer <access_token>
See Authentication for details.

​
Key Concepts

​
Soft Deletes

Most resources use soft deletion. When you DELETE a resource, it’s marked as deleted but not removed from the database. Use the PATCH /:id/restore endpoint to undo a delete.

​
Year Filtering

Many list endpoints accept a year query parameter (YYYY format) to filter results by year. When omitted, the current year is used as the default.

​
Plan Gating

Three endpoints require a Pro subscription:
  • GET /tax-estimate — Full tax calculations
  • POST /tax-calculate — Contract comparison calculations
  • GET /state-income — Multi-state income breakdown
All other endpoints are available on the Free plan. Pro-gated endpoints return 403 Forbidden for free users.

​
Rate Limiting

API requests are rate-limited to 100 requests per minute per user in production (500 in development). The health check and Stripe webhook endpoints are exempt.

​
Request IDs

Every response includes an X-Request-Id header containing a UUID. Include this ID when reporting issues for faster debugging.

Authentication

JWT tokens and AWS Cognito setup

Error Handling

Status codes and error response format

Pagination

Paginating list endpoints

Assignments

Start with the most common resource