---
title: "Evaluate Workpaper (first-time, async)"
method: POST
path: "/internal/api/clients/{client_id}/workpaper/evaluate"
tags: ["CLIENT", "Workpaper"]
---

# Evaluate Workpaper (first-time, async)

`POST /internal/api/clients/{client_id}/workpaper/evaluate`

## Request

- Base URL: `https://api.signalshq.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.signalshq.io/internal/api/clients/{client_id}/workpaper/evaluate`
- Auth: OAuth 2
  - Password
  - Token URL: `/auth/login`

First-time evaluation: get-or-create draft tax return for this client and tax year. If one already exists, returns that same tax_return_id. Returns 202 + tax_return_id; frontend polls GET workpaper/status?tax_return_id= until COMPLETED or FAILED, then GET workpaper.

## Path parameters

- `client_id` string, uuid, required: Client ID

## Request body

- WorkpaperEvaluateBody: Request body for POST workpaper/evaluate (first-time). No tax_return_id.
  - `tax_year` integer, required: Tax year for workpaper evaluation
  - `triggered_by_user_id` string, uuid, nullable: User who triggered; defaults to current user when omitted.

## Response `202`

Successful Response

- WorkpaperAcceptedResponse: 202 Accepted response body: tax_return_id for polling and subsequent reevaluate.
  - `tax_return_id` string, uuid, required: Tax return UUID; use in GET workpaper and future reevaluate requests.
  - `status` 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED': Job lifecycle. DB: workpaper_regeneration_job_status_enum. API adds IDLE in core.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/signalshq/apis/signals-api.md) - [All operations](https://skmtc.dev/signalshq/apis/signals-api/llms.txt) - [OpenAPI document](https://skmtc.dev/signalshq/apis/signals-api/revisions/2c22af3b5576?raw)