Project Scope

Everything about what an assurance project covers. Reads use the scoped-controls collection (GET /assuranceProjects/{id}/scopedControls); writes are three behavioral operations, each acting on one set of controls:

• Add (POST /assuranceProjects/{id}/scopedControls/addition) — put controls in scope by control id. No rationale.

• Remove (POST /assuranceProjects/{id}/scopedControls/removal) — take scope entries out of scope by ScopedControl.id, with a required rationale recorded on each entry.

• Re-add (POST /assuranceProjects/{id}/scopedControls/reAddition) — restore previously removed entries by ScopedControl.id, with a required rationale.

The project-level scopingRationale and the attached Workiva files are set separately, with PATCH /assuranceProjects/{id}. So there are two distinct pieces of reasoning: the project’s scopingRationale (the overall scope narrative, set on the project) and a control’s scopeRationale (why that scope entry was removed or re-added). They are independent — removing a control never changes the project rationale.

Setting scope is supported only for Independent Controls Testing projects.

AddControlsToScopeRequest

A request to add controls to a project’s scope, by control id.

Properties

Name	Type	Description	Restrictions
data	[string]	The ids of the controls to add to scope, as returned by the Controls API.	required, Minimum items: 1, Maximum items: 250

Example

{
  "data": [
    "019cafc7-4901-7181-a53b-b2263115961d",
    "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  ]
}

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"

ChangeScopedControlsRequest

A request to remove or re-add scope entries, by ScopedControl.id, with a required rationale recorded against every entry in the request.

Properties

Name	Type	Description	Restrictions
data	[string]	The ids of the scope entries to change. Each is a ScopedControl.id (from the scoped-controls list), not the control’s own id.	required, Minimum items: 1, Maximum items: 250
rationale	string	The reason for the change, recorded against every entry in the request and surfaced as each control’s scopeRationale. Distinct from the project-level scopingRationale.	required

Example

{
  "data": [
    "019cb0a1-2f3e-7c22-9a10-4d5e6f7a8b90"
  ],
  "rationale": "Below materiality threshold for FY26."
}

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

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

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

ScopeStatus

Whether a control is in a project’s scope. Known values: inScope, removedFromScope. 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 a control is in a project’s scope. Known values: inScope, removedFromScope. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.

Example

"inScope"

ScopedControl

A control’s membership in a project’s scope. id identifies this scope entry; control is the control it is for; scopeStatus indicates whether it is currently in scope. Use id when removing this entry from scope.

Properties

Name	Type	Description	Restrictions
control	Control	The control this scope entry is for.	required
id	string	The unique id of this scope entry. Stable for the life of the entry, including while it is removed from scope. Pass these ids to the scopedControls/removal and scopedControls/reAddition operations to remove or re-add controls.	required
scopeRationale	string¦null	The rationale recorded when this control was removed from scope. Present while scopeStatus is removedFromScope; null while the control is in scope. Distinct from the project-level scopingRationale, which is one narrative for the whole engagement.
scopeStatus	ScopeStatus	Whether a control is in a project’s scope. Known values: inScope, removedFromScope. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.	required

Example

{
  "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": "Below materiality threshold for FY26.",
  "scopeStatus": "inScope"
}

ScopedControlBatchResult

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.

Properties

Name	Type	Description	Restrictions
data	[ScopedControl]	The affected scope entries, with resulting state.	required

Example

{
  "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",
      "scopeStatus": "inScope"
    }
  ]
}

ScopedControlCollection

A collection of a project’s scoped 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	[ScopedControl]	The scoped controls in this page.	required

Example

{
  "@nextLink": "https://api.app.wdesk.com/assuranceProjects/019f14d1-7c8a-7f81-bd63-0677ee3fa6f8/scopedControls?$next=b3BhcXVlLWN1cnNvci10b2tlbi05ZjhlN2Q=",
  "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",
      "scopeStatus": "inScope"
    }
  ]
}

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