Submit Decisions

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

cURL

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"
      }
    ]
  }'

Running

{
  "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
}

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.

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. See 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.

Show 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 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.

cURL

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"
      }
    ]
  }'

Running

{
  "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
}

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 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.