Re-add 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 re-addition. An entry that is not currently removed is rejected; add a never-scoped control with the addition operation instead. Returns the affected scoped controls. Supported only for Independent Controls Testing projects.

POST /assuranceProjects/{id}/scopedControls/reAddition

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/reAddition' \
    -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/reAddition \
    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/reAddition" \
    --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/reAddition', headers = headers, json=body)

print(r.json())

Returns

200 - The controls now back in scope.

The scope entries affected by an add, remove, or re-add, with their resulting state. Added controls appear with their newly assigned ScopedControl.id and an inScope status; removed and re-added entries reflect their new status and rationale. Not paginated.

400 - The request was invalid.

Error response indicating the service could not process the request.

401 - Authentication is missing or invalid.

Error response indicating the service could not process the request.

403 - The caller is not permitted to access this resource.

Error response indicating the service could not process the request.

404 - The requested resource was not found.

Error response indicating the service could not process the request.

409 - The request conflicts with the state of the target resource, for example an operation attempted on an unsupported project type.

Error response indicating the service could not process the request.

429 - The rate limit has been exceeded.

Error response indicating the service could not process the request.

500 - An unexpected error occurred.

Error response indicating the service could not process the request.

Example Responses

The controls now back in scope.

{
  "data": [
    {
      "control": {
        "controlId": "COSO-C-001",
        "id": "019cafc7-4901-7181-a53b-b2263115961d",
        "name": "Code of Conduct and Ethics Policy"
      },
      "id": "019cb0a1-2f3e-7c22-9a10-4d5e6f7a8b90",
      "scopeRationale": "Business retained; control back in scope for FY26.",
      "scopeStatus": "inScope"
    }
  ]
}

The request was invalid.

{
  "code": "invalidFilter",
  "message": "The $filter value could not be parsed.",
  "target": "$filter"
}

Authentication is missing or invalid.

{
  "code": "unauthenticated",
  "message": "Authentication credentials were missing or invalid."
}

The caller is not permitted to access this resource.

{
  "code": "permissionDenied",
  "message": "You do not have permission to access this resource."
}

The requested resource was not found.

{
  "code": "notFound",
  "message": "No resource with this id was found."
}

The request conflicts with the state of the target resource, for example an operation attempted on an unsupported project type.

{
  "code": "unsupportedProjectType",
  "message": "This operation is only supported for Independent Controls Testing projects.",
  "target": "/type"
}

The rate limit has been exceeded.

{
  "code": "rateLimitExceeded",
  "message": "Rate limit exceeded. Retry after the period indicated in the response headers."
}

An unexpected error occurred.

{
  "code": "internalError",
  "message": "An unexpected error occurred. Please try again later."
}