Restore previously removed controls to a project’s scope#

Description#

Restore up to 250 previously removed controls to a project’s scope, identified by scope-entry id (ScopedControl.id). A rationale is required and recorded against every entry as its scopeRationale, explaining the restoration and replacing any earlier one. The operation is idempotent: an entry that is already in scope stays in scope and takes the new rationale, so a retried request leaves the same state and returns the same response. An id that doesn’t match a scope entry in the project is skipped; add a never-scoped control with the addition operation instead. Returns the matched entries in request order, in their resulting state. After a timeout, read the scoped-controls list or retry the same request. Supported only for Independent Controls Testing projects; a request against any other project type returns 409 with code unsupportedProjectType.

POST /assuranceProjects/{id}/scopedControls/restoration

Required OAuth Scopes

grc:write

Parameters#

Parameter	In	Type	Required	Description
X-Version	header	string	true	Version of the API (2026-09-01.grc.preview)
body	body	ChangeScopedControlsRequest	true
Wk-Workspace	header	string	true	The id of the Workiva workspace to operate in. Authorization is enforced against the authenticated user’s access within this workspace.
id	path	string	true	The unique system identifier of the resource.

Body parameter example#

{
  "data": [
    "019cb0a1-2f3e-7c22-9a10-4d5e6f7a8b90"
  ],
  "rationale": "Business retained; control back in scope for FY26."
}

Code Samples#

curl

curl -X POST 'https://api.app.wdesk.com/assuranceProjects/{id}/scopedControls/restoration' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Wk-Workspace: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d' \
    -H 'Authorization: Bearer {access-token}' \
    -H 'X-Version: 2026-09-01.grc.preview' \
    --data-raw '{"data":["019cb0a1-2f3e-7c22-9a10-4d5e6f7a8b90"],"rationale":"Business retained; control back in scope for FY26."}'

httpie

echo '{"data":["019cb0a1-2f3e-7c22-9a10-4d5e6f7a8b90"],"rationale":"Business retained; control back in scope for FY26."}' | http POST https://api.app.wdesk.com/assuranceProjects/{id}/scopedControls/restoration \
    X-Version:2026-09-01.grc.preview \
    Content-Type:application/json \
    Accept:application/json \
    Wk-Workspace:1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d \
    Authorization:"Bearer {access-token}"

wget

wget --method=POST "https://api.app.wdesk.com/assuranceProjects/{id}/scopedControls/restoration" \
    --output-document - \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Wk-Workspace: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d' \
    --header 'Authorization: Bearer {access-token}' \
    --header 'X-Version: 2026-09-01.grc.preview' \
    --body-data='{"data":["019cb0a1-2f3e-7c22-9a10-4d5e6f7a8b90"],"rationale":"Business retained; control back in scope for FY26."}'

python

import requests

headers = {
  'X-Version': '2026-09-01.grc.preview',
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Wk-Workspace': '1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d',
  'Authorization': 'Bearer {access-token}'
}

body = {
  "data": [
    "019cb0a1-2f3e-7c22-9a10-4d5e6f7a8b90"
  ],
  "rationale": "Business retained; control back in scope for FY26."
}

r = requests.post('https://api.app.wdesk.com/assuranceProjects/{id}/scopedControls/restoration', headers = headers, json=body)

print(r.json())

Returns#

200 - The scope entries of the requested ids after the restoration.#

The scope entries a scope change affected, in their resulting state and in request order. For an add, only the entries the call created, each with its assigned ScopedControl.id and an inScope status. Removed and restored entries reflect their new status and rationale. Ids that don’t resolve are omitted. Not paginated.