Get a control by id

Table Of Contents

Get a control by id#

Description#

Return the full representation of a single control.

GET /controls/{id}

Required OAuth Scopes

grc:read

Parameters#

Parameter	In	Type	Required	Description
X-Version	header	string	true	Version of the API (2026-09-01.grc.preview)
id	path	string	true	The unique system identifier of the resource.
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.

Code Samples#

curl

curl -X GET https://api.app.wdesk.com/controls/{id} \
    -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'

httpie

http GET https://api.app.wdesk.com/controls/{id} \
    X-Version:2026-09-01.grc.preview \
    Accept:application/json \
    Wk-Workspace:1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d \
    Authorization:"Bearer {access-token}"

wget

wget --method=GET "https://api.app.wdesk.com/controls/{id}" \
    --output-document - \
    --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'

python

import requests

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

r = requests.get('https://api.app.wdesk.com/controls/{id}', headers = headers)

print(r.json())

Returns#

200 - The requested control.#

A control — a safeguard or activity that mitigates one or more risks. A control may be standalone (classic), a definition (template), or an instance (derived from a definition for a specific location or system). Each type uses the same unified shape. The controlType discriminator indicates which type-specific sub-object is populated: the definition object carries the instance rollup for template controls, and the instance object carries the parent definition and overridden fields for derived controls. Both are absent for standalone controls. A workspace is in either standalone mode or multi-instance mode. Unfiltered list results contain standalone controls in standalone mode, or definition and instance controls in multi-instance mode. controlType filters request a subset of the types available in that workspace mode.

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.

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

{
  "automatedManual": "manual",
  "controlId": "BEN.002",
  "controlType": "definition",
  "customFields": [
    {
      "enumValue": "Medium",
      "id": "8f3c1a2b-4d5e-4f6a-8b7c-9d0e1f2a3b4c",
      "name": "Risk Rating",
      "type": "singleSelectEnum"
    }
  ],
  "definition": {
    "instanceCount": 3
  },
  "description": "Approves AP invoices before payment is released.",
  "frequency": "monthly",
  "id": "4a3b2c1d-0e9f-4a8b-7c6d-5e4f3a2b1c0d",
  "locations": [],
  "name": "AP Invoice Approval",
  "owner": {
    "id": "u_4cc9f9128a684f45a7a37b08b70b54c1"
  },
  "preventiveDetective": "detective",
  "process": {
    "id": "2b1e5a7c-3d4f-4a1b-9c2d-6e7f8a9b0c1d",
    "name": "Financial Reporting"
  },
  "risks": [
    {
      "id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "name": "Misstated account balances",
      "riskId": "R.001"
    }
  ],
  "significance": "key",
  "subProcess": {
    "id": "3c2f6b8d-4e5a-4b2c-8d3e-7f8a9b0c1d2e",
    "name": "Account Reconciliation"
  },
  "systems": []
}

{
  "automatedManual": "manual",
  "controlId": "BEN.002",
  "controlType": "instance",
  "customFields": [
    {
      "enumValue": "Medium",
      "id": "8f3c1a2b-4d5e-4f6a-8b7c-9d0e1f2a3b4c",
      "name": "Risk Rating",
      "type": "singleSelectEnum"
    }
  ],
  "description": "Approves AP invoices before payment is released.",
  "frequency": "quarterly",
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "instance": {
    "definition": {
      "controlId": "BEN.002",
      "id": "4a3b2c1d-0e9f-4a8b-7c6d-5e4f3a2b1c0d",
      "name": "AP Invoice Approval"
    },
    "overriddenFields": [
      "frequency",
      "8f3c1a2b-4d5e-4f6a-8b7c-9d0e1f2a3b4c"
    ]
  },
  "locations": [
    {
      "id": "7f6e5d4c-3b2a-4c1d-9e8f-0a1b2c3d4e5f",
      "name": "North America"
    }
  ],
  "name": "AP Invoice Approval",
  "owner": {
    "id": "u_4cc9f9128a684f45a7a37b08b70b54c1"
  },
  "preventiveDetective": "detective",
  "process": {
    "id": "2b1e5a7c-3d4f-4a1b-9c2d-6e7f8a9b0c1d",
    "name": "Financial Reporting"
  },
  "risks": [
    {
      "id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "name": "Misstated account balances",
      "riskId": "R.001"
    }
  ],
  "significance": "key",
  "subProcess": {
    "id": "3c2f6b8d-4e5a-4b2c-8d3e-7f8a9b0c1d2e",
    "name": "Account Reconciliation"
  },
  "systems": [
    {
      "id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
      "name": "Workday"
    }
  ]
}

{
  "automatedManual": "manual",
  "controlId": "BEN.001",
  "controlType": "standalone",
  "customFields": [
    {
      "enumValue": "High",
      "id": "8f3c1a2b-4d5e-4f6a-8b7c-9d0e1f2a3b4c",
      "name": "Risk Rating",
      "type": "singleSelectEnum"
    },
    {
      "enumValues": [
        "SOX",
        "COSO"
      ],
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Frameworks",
      "type": "multiSelectEnum"
    },
    {
      "dateValue": "2026-01-15",
      "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
      "name": "Last Reviewed",
      "type": "date"
    },
    {
      "id": "3c4d5e6f-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
      "name": "Review Notes",
      "stringValue": "Reviewed by internal audit.",
      "type": "string"
    },
    {
      "id": "4d5e6f7a-8b9c-4d0e-1f2a-3b4c5d6e7f8a",
      "invalidValue": "not-a-date",
      "name": "Legacy Date",
      "type": "invalid"
    }
  ],
  "description": "Ensures general ledger balances are reconciled monthly.",
  "frequency": "monthly",
  "id": "d9c09501-214c-432e-85c9-8cd1009b9660",
  "locations": [
    {
      "id": "7f6e5d4c-3b2a-4c1d-9e8f-0a1b2c3d4e5f",
      "name": "North America"
    }
  ],
  "name": "General Ledger Reconciliation",
  "owner": {
    "id": "u_4cc9f9128a684f45a7a37b08b70b54c1"
  },
  "preventiveDetective": "preventive",
  "process": {
    "id": "2b1e5a7c-3d4f-4a1b-9c2d-6e7f8a9b0c1d",
    "name": "Financial Reporting"
  },
  "risks": [
    {
      "id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "name": "Misstated account balances",
      "riskId": "R.001"
    }
  ],
  "significance": "key",
  "subProcess": {
    "id": "3c2f6b8d-4e5a-4b2c-8d3e-7f8a9b0c1d2e",
    "name": "Account Reconciliation"
  },
  "systems": [
    {
      "id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
      "name": "Workday"
    }
  ]
}

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