Withdraw a review request

Take back a proposal the student has not decided yet, read the two answers the withdrawal can give, and know what the student sees afterwards.

An agent can take back a review request it made, while the student has still not decided and no work has started. This guide shows you how, what the two possible answers mean, and what the student sees once a request is withdrawn.

Send the withdrawal

The tool is actions.cancel. Its whole input is operationId, the identifier the proposing tool returned, and it is the one write tool that takes no idempotency key, because that identifier already names one review request. Sending it a key is refused before the tool runs:

actions.cancel input

{ "operationId": "0123456789abcdef01234567" }

Two separate permission gates apply, and a call has to pass both.

The catalogue requires profile:write on every call to actions.cancel, whatever the withdrawal is about. A connection that holds only booking:write can propose an event type change and cannot withdraw it.

At the moment of the call, the connection must also still hold the scopes the creating tool recorded on the review request. A connection that has lost a permission cannot withdraw work it could no longer propose.

Read the answer

There are two outcomes and no third.

A withdrawal that succeeds, and a repeat of one that already succeeded, both answer with a result whose status is cancelled. There is no tag on either answer this tool gives. OPERATION_CANCELLED is the success here:

actions.cancel result

{
  "status": "cancelled",
  "scenario": "cancelled",
  "operationId": "0123456789abcdef01234567",
  "error": {
    "code": "OPERATION_CANCELLED",
    "retryable": false,
    "correlationId": "0123456789abcdef01234567"
  }
}

Withdrawing twice is the same success. A repeat is safe.

Anything else answers with a conflict. The student had already decided the review request, or it had expired, or Coffee Chats had already started applying it:

actions.cancel result

{
  "status": "failed",
  "scenario": "conflict",
  "operationId": "0123456789abcdef01234567",
  "error": {
    "code": "VERSION_CONFLICT",
    "retryable": false,
    "correlationId": "0123456789abcdef01234567"
  }
}

Poll the review request with its own tool to find out which of those happened, by calling that tool with the same operationId. Do not retry the withdrawal: the review request has moved on, and calling again returns the same conflict.

Only your own requests

A withdrawal reaches only a review request the calling connection itself created. An identifier that names anything else is refused with the fixed text Tool call failed., and that answer says nothing about whether such a review request exists. A review request is not one of the eight kinds of record whose lookup names what it did not find, which failures that carry no code lists.

What the student sees

A withdrawn review request leaves the student’s waiting list with no notification. It appears under the section headed “Recent decisions” on the same page, with one sentence saying how it ended, so the student can still see what happened to it.

Next steps

Propose a booking page change

The proposal this withdrawal takes back.

Approvals

What the student sees while a review request is waiting.