Add controls to a project’s scope

Description

Add up to 250 controls to a project’s scope, identified by control id (as returned by the Controls API). Takes no rationale; the project-level narrative is set on the project’s scopingRationale (see PATCH /assuranceProjects/{id}). A control already in scope is rejected; restore a previously removed control with the reAddition operation instead. Returns the newly scoped controls, each with its assigned ScopedControl.id. Supported only for Independent Controls Testing projects.

POST /assuranceProjects/{id}/scopedControls/addition

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	AddControlsToScopeRequest	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": [
    "019cafc7-4901-7181-a53b-b2263115961d",
    "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  ]
}

Code Samples

curl

curl -X POST 'https://api.app.wdesk.com/assuranceProjects/{id}/scopedControls/addition' \
    -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":["019cafc7-4901-7181-a53b-b2263115961d","a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"]}'

httpie

echo '{"data":["019cafc7-4901-7181-a53b-b2263115961d","a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"]}' | http POST https://api.app.wdesk.com/assuranceProjects/{id}/scopedControls/addition \
    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/addition" \
    --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":["019cafc7-4901-7181-a53b-b2263115961d","a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"]}'

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": [
    "019cafc7-4901-7181-a53b-b2263115961d",
    "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  ]
}

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

print(r.json())

Returns

200 - The controls now 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 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-4d5e6f7a8b92",
      "scopeRationale": null,
      "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."
}