Controls

Retrieve controls and their relationships.

AutomatedManual

Whether the control is automated or performed manually. Known values: automated, manual. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.

Properties

Name	Type	Description	Restrictions
anonymous	string	Whether the control is automated or performed manually. Known values: automated, manual. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.

Example

"manual"

BatchRetrievalRequest

A request to retrieve a set of resources by id.

Properties

Name	Type	Description	Restrictions
data	[string]	The system ids of the resources to retrieve.	required, Minimum items: 1, Maximum items: 250

Example

{
  "data": [
    "d9c09501-214c-432e-85c9-8cd1009b9660",
    "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  ]
}

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.

Properties

Name	Type	Description	Restrictions
automatedManual	AutomatedManual	Whether the control is automated or performed manually. Known values: automated, manual. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.
controlId	string	The user-defined identifier of the control.	required
controlType	ControlType	The dimensionality type of the control. Standalone controls are independent; definition controls are templates that spawn instances across location/system dimensions; instance controls are concrete controls derived from a definition for a specific location/system. Known values: standalone, definition, instance. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.
customFields	[CustomField]	User-defined custom fields configured for controls in this workspace.
definition	object	Definition-specific data. Present only when controlType is definition; absent for standalone and instance controls.
definition.instanceCount	integer(int32)	The number of instances derived from this definition.
description	string	A description of the control.
frequency	ControlFrequency	How often the control operates. Known values: continuous, daily, weekly, monthly, quarterly, semiAnnually, annually, adHoc. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.
id	string	The unique system identifier of the control.	required
instance	object	Instance-specific data. Present only when controlType is instance; absent for standalone and definition controls.
instance.definition	Control	The parent definition this instance was derived from.
instance.overriddenFields	[string]	The fields on this instance that differ from its parent definition. Each entry is a field identifier: a public standard field name such as frequency or significance, or the stable custom-field schema identifier. An empty array means the instance is fully aligned with its definition.
locations	[Location]	The locations this control applies to. For standalone controls this may contain multiple items; for instance controls it contains zero or one; for definitions it is empty.
name	string	The name of the control.
owner	User	The user who owns this control.
preventiveDetective	PreventiveDetective	Whether the control prevents or detects an issue. Known values: preventive, detective. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.
process	Process	The process this control belongs to.
risks	[Risk]	The risks this control mitigates.
significance	Significance	Whether the control is a key control. Known values: key, nonKey. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.
subProcess	SubProcess	The subprocess this control belongs to.
systems	[System]	The systems this control operates within. For standalone controls this may contain multiple items; for instance controls it contains zero or one; for definitions it is empty.

Example

{
  "automatedManual": "manual",
  "controlId": "BEN.001",
  "controlType": "standalone",
  "customFields": [
    {
      "enumValue": "High",
      "id": "8f3c1a2b-4d5e-4f6a-8b7c-9d0e1f2a3b4c",
      "name": "Risk Rating",
      "type": "singleSelectEnum"
    }
  ],
  "definition": {
    "instanceCount": 3
  },
  "description": "Ensures general ledger balances are reconciled monthly.",
  "frequency": "monthly",
  "id": "d9c09501-214c-432e-85c9-8cd1009b9660",
  "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": "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"
    }
  ]
}

ControlBatchResult

The controls requested by a batch get, in request order. Batch results are not paginated.

Properties

Name	Type	Description	Restrictions
data	[Control]	The requested controls, in the order of the requested ids.	required

Example

{
  "data": [
    {
      "controlId": "BEN.001",
      "controlType": "standalone",
      "id": "d9c09501-214c-432e-85c9-8cd1009b9660",
      "name": "General Ledger Reconciliation",
      "process": {
        "id": "2b1e5a7c-3d4f-4a1b-9c2d-6e7f8a9b0c1d",
        "name": "Financial Reporting"
      }
    }
  ]
}

ControlCollection

A collection of controls.

Properties

Name	Type	Description	Restrictions
@nextLink	string	URL of the next page of results, with the $next cursor already applied. Omitted on the last page. Follow it to fetch the next page.
data	[Control]	The controls in this page.	required

Example

{
  "@nextLink": "https://api.app.wdesk.com/controls?$next=b3BhcXVlLWN1cnNvci10b2tlbi05ZjhlN2Q=",
  "data": [
    {
      "controlId": "BEN.001",
      "controlType": "standalone",
      "id": "d9c09501-214c-432e-85c9-8cd1009b9660",
      "name": "General Ledger Reconciliation",
      "process": {
        "id": "2b1e5a7c-3d4f-4a1b-9c2d-6e7f8a9b0c1d",
        "name": "Financial Reporting"
      }
    }
  ]
}

ControlFrequency

How often the control operates. Known values: continuous, daily, weekly, monthly, quarterly, semiAnnually, annually, adHoc. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.

Properties

Name	Type	Description	Restrictions
anonymous	string	How often the control operates. Known values: continuous, daily, weekly, monthly, quarterly, semiAnnually, annually, adHoc. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.

Example

"monthly"

ControlType

The dimensionality type of the control. Standalone controls are independent; definition controls are templates that spawn instances across location/system dimensions; instance controls are concrete controls derived from a definition for a specific location/system. Known values: standalone, definition, instance. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.

Properties

Name	Type	Description	Restrictions
anonymous	string	The dimensionality type of the control. Standalone controls are independent; definition controls are templates that spawn instances across location/system dimensions; instance controls are concrete controls derived from a definition for a specific location/system. Known values: standalone, definition, instance. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.

Example

"standalone"

CustomField

A user-defined custom field value on a resource. id is the stable custom-field schema identifier (names can change). The type indicates which value field is populated; exactly one value field is set for a given type (none is set when the field has no value). Custom fields are defined per workspace and may be configured on multiple resource types. New field types may be introduced over time, so treat type as an open string and tolerate unrecognized values.

Properties

Name	Type	Description	Restrictions
dateValue	string(date)	The value when type is date.
enumValue	string	The selected option when type is singleSelectEnum.
enumValues	[string]	The selected options when type is multiSelectEnum.
id	string	The stable custom-field schema identifier.	required
invalidValue	string	The raw stored value when type is invalid.
name	string	The display name of the custom field.	required
stringValue	string	The value when type is string.
type	string	Indicates which value field is populated. Known values: string, singleSelectEnum, multiSelectEnum, date, invalid. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.	required

Example

{
  "dateValue": "2026-01-15",
  "enumValue": "High",
  "enumValues": [
    "SOX",
    "COSO"
  ],
  "id": "8f3c1a2b-4d5e-4f6a-8b7c-9d0e1f2a3b4c",
  "invalidValue": "not-a-date",
  "name": "Risk Rating",
  "stringValue": "Reviewed by internal audit.",
  "type": "singleSelectEnum"
}

ErrorDetail

An individual error detail.

Properties

Name	Type	Description	Restrictions
code	string	A stable, machine-readable identifier for the error.
message	string	A human-readable representation of the error.	required
target	string	The target of the error, for example /data/0 to identify the offending item in a batch request.

Example

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

ErrorResponse

Error response indicating the service could not process the request.

Properties

Name	Type	Description	Restrictions
code	string	A stable, machine-readable identifier for the error.
details	[ErrorDetail]	A list of detailed errors, one per offending item.
message	string	A human-readable representation of the error.	required
target	string	The target of the error. A value starting with / refers to a field in the request payload using the JSON Pointer spec; a value starting with $ refers to a query parameter.

Example

{
  "code": "invalidFilter",
  "details": [
    {
      "code": "notFound",
      "message": "No resource with this id was found.",
      "target": "/data/2"
    }
  ],
  "message": "The request was unacceptable, often due to a missing or invalid parameter.",
  "target": "$filter"
}

Location

A place that a control applies to.

Properties

Name	Type	Description	Restrictions
id	string	The unique identifier of the location.	required
name	string	The name of the location.	required

Example

{
  "id": "7f6e5d4c-3b2a-4c1d-9e8f-0a1b2c3d4e5f",
  "name": "North America"
}

PreventiveDetective

Whether the control prevents or detects an issue. Known values: preventive, detective. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.

Properties

Name	Type	Description	Restrictions
anonymous	string	Whether the control prevents or detects an issue. Known values: preventive, detective. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.

Example

"preventive"

Process

A top-level business process that groups risks, controls, and subprocesses.

Properties

Name	Type	Description	Restrictions
controls	[Control]	The controls within this process. A process may have at most 300 controls.	Maximum items: 300
description	string	A description of the process.
id	string	The unique identifier of the process.	required
name	string	The name of the process.	required
risks	[Risk]	The risks within this process. A process may have at most 300 risks.	Maximum items: 300
subProcesses	[SubProcess]	The subprocesses within this process. A process may have at most 100 subprocesses.	Maximum items: 100

Example

{
  "controls": [
    {
      "controlId": "BEN.001",
      "id": "d9c09501-214c-432e-85c9-8cd1009b9660",
      "name": "General Ledger Reconciliation"
    }
  ],
  "description": "The end-to-end financial reporting process.",
  "id": "2b1e5a7c-3d4f-4a1b-9c2d-6e7f8a9b0c1d",
  "name": "Financial Reporting",
  "risks": [
    {
      "id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "name": "Misstated account balances",
      "riskId": "R.001"
    }
  ],
  "subProcesses": [
    {
      "id": "3c2f6b8d-4e5a-4b2c-8d3e-7f8a9b0c1d2e",
      "name": "Account Reconciliation"
    }
  ]
}

Risk

A potential event that controls are designed to mitigate.

Properties

Name	Type	Description	Restrictions
customFields	[CustomField]	User-defined custom fields configured for risks in this workspace.
description	string	A description of the risk.
id	string	The unique system identifier of the risk.	required
mitigatingControls	[Control]	The controls that mitigate this risk.
name	string	The name of the risk.
owner	User	The user who owns this risk.
process	Process	The process this risk belongs to.
riskId	string	The user-defined identifier of the risk.	required
subProcess	SubProcess	The subprocess this risk belongs to.

Example

{
  "customFields": [
    {
      "enumValue": "High",
      "id": "8f3c1a2b-4d5e-4f6a-8b7c-9d0e1f2a3b4c",
      "name": "Risk Rating",
      "type": "singleSelectEnum"
    }
  ],
  "description": "Risk that account balances are materially misstated.",
  "id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "mitigatingControls": [
    {
      "controlId": "BEN.001",
      "id": "d9c09501-214c-432e-85c9-8cd1009b9660",
      "name": "General Ledger Reconciliation"
    }
  ],
  "name": "Misstated account balances",
  "owner": {
    "id": "u_4cc9f9128a684f45a7a37b08b70b54c1"
  },
  "process": {
    "id": "2b1e5a7c-3d4f-4a1b-9c2d-6e7f8a9b0c1d",
    "name": "Financial Reporting"
  },
  "riskId": "R.001",
  "subProcess": {
    "id": "3c2f6b8d-4e5a-4b2c-8d3e-7f8a9b0c1d2e",
    "name": "Account Reconciliation"
  }
}

Significance

Whether the control is a key control. Known values: key, nonKey. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.

Properties

Name	Type	Description	Restrictions
anonymous	string	Whether the control is a key control. Known values: key, nonKey. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.

Example

"key"

SubProcess

A subdivision of a process; also groups risks and controls.

Properties

Name	Type	Description	Restrictions
controls	[Control]	The controls within this subprocess. Bounded by the parent process’s limit of 300 controls.	Maximum items: 300
description	string	A description of the subprocess.
id	string	The unique identifier of the subprocess.	required
name	string	The name of the subprocess.	required
parentProcess	Process	The process this subprocess belongs to.
risks	[Risk]	The risks within this subprocess. Bounded by the parent process’s limit of 300 risks.	Maximum items: 300

Example

{
  "controls": [
    {
      "controlId": "BEN.001",
      "id": "d9c09501-214c-432e-85c9-8cd1009b9660",
      "name": "General Ledger Reconciliation"
    }
  ],
  "description": "Reconciliation of general ledger accounts.",
  "id": "3c2f6b8d-4e5a-4b2c-8d3e-7f8a9b0c1d2e",
  "name": "Account Reconciliation",
  "parentProcess": {
    "id": "2b1e5a7c-3d4f-4a1b-9c2d-6e7f8a9b0c1d",
    "name": "Financial Reporting"
  },
  "risks": [
    {
      "id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "name": "Misstated account balances",
      "riskId": "R.001"
    }
  ]
}

System

An application or system that a control operates within.

Properties

Name	Type	Description	Restrictions
id	string	The unique identifier of the system.	required
name	string	The name of the system.	required

Example

{
  "id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
  "name": "Workday"
}

User

A user referenced by their unique identifier. Resolve the user’s profile details through the appropriate Workiva identity API.

Properties

Name	Type	Description	Restrictions
id	string	The unique identifier of the user.	required

Example

{
  "id": "u_4cc9f9128a684f45a7a37b08b70b54c1"
}