> ## Documentation Index
> Fetch the complete documentation index at: https://wordsmithai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit Decisions

> Accept, reject or counter the counterparty's tracked changes and produce your response draft.

> [!WARNING]
>
> **Proposed — not available yet.** This endpoint is part of a design under review.

Records your decision on each of the counterparty's tracked changes, then writes them into a response draft. It works only on `counterparty_edits` reviews. Each finding in such a review is one tracked change. Read them, with Wordsmith's recommendation, through [List Findings](/api-reference/reviews/list-findings).

The response draft is a new DOCX:

* An **accepted** change is applied and no longer tracked.
* A **rejected** change is reverted.
* A **countered** change is reverted and replaced by your `counter_text`, as a new tracked change.
* A finding **without a decision** stays as the counterparty's tracked change, for you to settle in Word.

Applying decisions runs as an [operation](/proposed/objects#operation). See [Long-running operations](/proposed/long-running-operations).

## Authentication

Requires an API key, or an OAuth token with `reviews:write` and `files:read`.

## Path parameters

**review\_id** `string` *required*

The id of a `counterparty_edits` review. The review must be `completed`.

## Headers

**Idempotency-Key** `string`

A unique key for this request, such as a UUID. A repeat with the same key within 30 days returns the same operation and makes no second draft.

## Body parameters

**decisions** `object[]` *required*

One entry per finding you are deciding. You can send decisions over several calls. A later decision on the same finding replaces the earlier one.

**properties**

**finding\_id** `string` *required*

A finding of this review.

**decision** `string` *required*

`accept`, `reject` or `counter`.

**counter\_text** `string`

The wording you propose instead. Required when `decision` is `counter`, and rejected otherwise.

**apply** `boolean` (default: true)

Produce the response draft from every decision recorded so far. With `false`, the decisions are saved and no draft is made. The operation then comes back already `succeeded`, with `file_id: null`.

**wait** `integer` (default: 0)

Seconds to wait for the draft before responding, from `0` to `20`.

**callback\_url** `string`

An HTTPS URL that receives a signed `operation.succeeded`, `operation.failed` or `operation.cancelled` event when the draft is ready.

## Response

Returns `202` with an [operation](/proposed/objects#operation) of type `review_decisions`. Its `resource` is the review. A repeat with the same `Idempotency-Key` returns `200` with the same operation.

When `status` is `succeeded`, `result` is `{ "file_id" }`: the response draft. The review's `response_file_id` is set to the same id, and each decided finding's `decision` is filled in.

```bash cURL theme={null}
curl -X POST "https://api.wordsmith.ai/api/v1/reviews/d87cb8f9-a92d-4955-881d-2386545cb19f/decisions" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 1e6a4c8b-3f7d-4b29-8a51-d0c9e2b7f346" \
  -d '{
    "decisions": [
      {
        "finding_id": "2c0afcb9-8d68-4340-87ca-ed6dd5ddc60e",
        "decision": "counter",
        "counter_text": "within 45 days of receipt"
      },
      {
        "finding_id": "1bce01c3-11ff-4a9e-8244-9816386908d8",
        "decision": "accept"
      },
      {
        "finding_id": "6deae027-f536-4a0d-95a1-e1084c54f524",
        "decision": "reject"
      }
    ]
  }'
```

```json Running theme={null}
{
  "id": "4ae0de09-7ef8-4dcf-941a-b4d038009288",
  "type": "review_decisions",
  "status": "running",
  "progress": { "stage": "apply", "completed": 0, "total": 3 },
  "resource": { "type": "review", "id": "d87cb8f9-a92d-4955-881d-2386545cb19f" },
  "result": null,
  "error": null,
  "poll_after_seconds": 5,
  "created_at": "2026-10-13T10:20:00Z",
  "updated_at": "2026-10-13T10:20:01Z",
  "completed_at": null
}
```

```json Succeeded theme={null}
{
  "id": "4ae0de09-7ef8-4dcf-941a-b4d038009288",
  "type": "review_decisions",
  "status": "succeeded",
  "progress": { "stage": "apply", "completed": 3, "total": 3 },
  "resource": { "type": "review", "id": "d87cb8f9-a92d-4955-881d-2386545cb19f" },
  "result": { "file_id": "e04f8d68-60d7-40bd-bce1-7edebdd2a4aa" },
  "error": null,
  "poll_after_seconds": null,
  "created_at": "2026-10-13T10:20:00Z",
  "updated_at": "2026-10-13T10:24:18Z",
  "completed_at": "2026-10-13T10:24:18Z"
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `invalid_request_body` | `decisions` is empty, a `decision` is not allowed, or `counter_text` is missing for `counter` or set for another decision. |
| 400 | `unknown_finding` | A `finding_id` does not belong to this review. |
| 402 | `insufficient_credits` | Your account does not have enough credits to apply the decisions. |
| 404 | `resource_not_found` | No review with this id, or the caller cannot read it. |
| 409 | `unsupported_review_type` | The review is not a `counterparty_edits` review. Use [Generate Redline](/api-reference/reviews/generate-redline) for the others. |
| 409 | `review_not_completed` | The review is still running, or it failed or was cancelled. |
| 409 | `idempotency_key_reused` | The `Idempotency-Key` was used within 30 days with a different body. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.