---
title: "Set the party on several documents at once"
method: PATCH
path: "/internal/api/document/party/bulk"
tags: ["DOCUMENT"]
---

# Set the party on several documents at once

`PATCH /internal/api/document/party/bulk`

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

Assigns one party across a selection. The allowed roles are the INTERSECTION across the selected document types, so picking a W-2 alongside a 1099-INT drops Joint from the menu rather than failing on one row. Returns per-document applied/skipped with reasons so the UI can disclose what it did NOT do — silently assigning 9 of 12 is a correctness bug the CPA cannot see.

## Request body

- SetDocumentPartyBulkRequest: Assign one party across a selection of documents.
  - `client_id` string, uuid, required: Client ID for the documents
  - `document_ids` string[], required: Documents to assign
  - `party_role` string, nullable, required: TAXPAYER | SPOUSE | JOINT, or null to clear.

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