---
title: "Set whose document this is (taxpayer / spouse / joint)"
method: PATCH
path: "/internal/api/document/{document_id}/party"
tags: ["DOCUMENT"]
---

# Set whose document this is (taxpayer / spouse / joint)

`PATCH /internal/api/document/{document_id}/party`

## 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/document/{document_id}/party`
- Auth: OAuth 2
  - Password
  - Token URL: `/auth/login`

Records the CPA's decision about which person on a joint return a document belongs to. A manual edit LOCKS the value: no later system write — resolver or backfill — may overwrite it. Rejects a role the document's type does not permit (a W-2 has one employee; an IRA has exactly one owner under IRC 408(a)), and rejects the v2-reserved roles. Joint returns only.

## Path parameters

- `document_id` string, uuid, required: Document to attribute

## Request body

- SetDocumentPartyRequest: Set one document's party — whose document it is on a joint return.
  - `client_id` string, uuid, required: Client ID for the document
  - `party_role` string, nullable, required: TAXPAYER | SPOUSE | JOINT, or null to clear back to undecided. Rejected when the document's type does not permit the role, or when it is a v2-reserved role (DEPENDENT / NOT_ON_RETURN).

## Response `200`

Successful Response

- SetDocumentPartyResponse: Result of a party assignment, single or bulk.
  - `applied_count` integer, required
  - `skipped_count` integer, required
  - `outcomes` DocumentPartyOutcome[], required
    - `document_id` string, uuid, required
    - `applied` boolean, required
    - `reason` string, nullable: Why it was skipped. The UI shows these verbatim — assigning 9 of 12 without saying which 3 were skipped is a correctness bug the CPA cannot see.

## 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)