Issues

Retrieve and update remediation issues. Use PATCH /issues/{id} with JSON Patch (replace only) to update supported fields. Retrieve up to 50 issues by id with POST /issues/batchRetrieval, or export issues to a CSV or JSONL file with the asynchronous POST /issues/export and follow its progress with GET /operations/{operationId}.

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"

Action

When the action was performed, and details about the user who did it

Properties

Name	Type	Description	Restrictions
dateTime	string(date-time)	When the action was performed	read-only
user	User¦null	A user referenced by their unique identifier. Resolve the user’s profile details through the appropriate Workiva identity API.

Example

{
  "dateTime": "2019-10-30T15:03:27Z",
  "user": {
    "id": "V0ZVc2VyHzU1MDg3OTc0MDE4MDg4OTY"
  }
}

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

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

Issue

A remediation issue — a finding, deficiency, or action item tracked through resolution. Issues link to controls, processes, and risks via point-in-time snapshots that record the state of those entities when the issue was created; the snapshot data is returned as lightweight digests using the live entity identifiers where available.

Properties

Name	Type	Description	Restrictions
auditTeamOwner	User	The audit team member who owns this issue.
businessOwner	User	The business owner responsible for remediating this issue.
collaborators	[User]	The users who collaborate on this issue. An issue has at most 10.	required, Maximum items: 10
controls	[Control]	The controls this issue is about, as lightweight digests. Derived from point-in-time snapshots; the id references the live control when it still exists.	Maximum items: 5
created	Action	When the issue was created, and by whom.	read-only, required
customFields	[CustomField]	User-defined custom fields configured for issues in this workspace. A workspace has at most 100.	required, Maximum items: 100
description	string	A description of the issue.
id	string	The unique system identifier of the issue.	required
isOverdue	boolean	Whether the issue is past its target remediation date.	required
modified	Action	When the issue last changed, and by whom. Deleting a linked control, process or risk does not yet change it.	read-only, required
name	string	The name of the issue.	required
processes	[Process]	The processes this issue is about, as lightweight digests. Derived from point-in-time snapshots; the id references the live process when it still exists.	Maximum items: 5
reportedDate	string(date)	The date the issue was reported.	required
resolutionDate	string(date-time)	When the issue was resolved.
resolutionNote	string	A note explaining the resolution.
resolutionType	IssueResolutionType	How the issue was resolved. Known values: remediated, riskAccepted, noActionRequired, duplicate, invalidCancelled, other. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.
resolvedBy	User	The user who resolved this issue.
risks	[Risk]	The risks this issue is about, as lightweight digests. Derived from point-in-time snapshots; the id references the live risk when it still exists.	Maximum items: 5
rootCause	string	The root cause of the issue.
severity	IssueSeverity	The severity of the issue. Known values, from lowest to highest: minor, moderate, high. unassigned means no severity has been set. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.	required
soxDeficiency	SoxDeficiency	The SOX deficiency classification. Known values: notSet, deficiency, materialWeakness, significantDeficiency. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.
status	IssueStatus	The status of the issue. Known values: draft, open, inRemediation, pendingVerification, resolved, dismissed. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.	required
supplementalInformation	string	Additional information about the issue.
targetRemediationDate	string(date)	The target date for remediation.
type	IssueType	The type of the issue. Known values: auditFinding, controlIssue, generalIssue. general is a deprecated legacy value carried over from issues created before typed issues existed and is not a documented value clients should plan around, though it may still appear on old data. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.	required

Example

{
  "auditTeamOwner": {
    "id": "u_4cc9f9128a684f45a7a37b08b70b54c1"
  },
  "businessOwner": {
    "id": "u_9f8e7d6c5b4a43210f1e2d3c4b5a6978"
  },
  "collaborators": [
    {
      "id": "u_4cc9f9128a684f45a7a37b08b70b54c1"
    }
  ],
  "controls": [
    {
      "controlId": "BEN.001",
      "id": "d9c09501-214c-432e-85c9-8cd1009b9660",
      "name": "General Ledger Reconciliation"
    }
  ],
  "created": {
    "dateTime": "2026-03-15T14:30:00Z",
    "user": {
      "id": "u_4cc9f9128a684f45a7a37b08b70b54c1"
    }
  },
  "customFields": [
    {
      "enumValue": "High",
      "id": "8f3c1a2b-4d5e-4f6a-8b7c-9d0e1f2a3b4c",
      "name": "Risk Rating",
      "type": "singleSelectEnum"
    }
  ],
  "description": "The same individual can both create and approve purchase orders in the AP system without a secondary review.",
  "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "isOverdue": false,
  "modified": {
    "dateTime": "2026-03-20T09:00:00Z",
    "user": {
      "id": "u_4cc9f9128a684f45a7a37b08b70b54c1"
    }
  },
  "name": "Segregation of duties violation in AP processing",
  "processes": [
    {
      "id": "2b1e5a7c-3d4f-4a1b-9c2d-6e7f8a9b0c1d",
      "name": "Financial Reporting"
    }
  ],
  "reportedDate": "2026-03-15",
  "resolutionDate": "2026-05-20T10:00:00Z",
  "resolutionNote": "Access controls reconfigured to require dual approval.",
  "resolutionType": "remediated",
  "resolvedBy": {
    "id": "u_4cc9f9128a684f45a7a37b08b70b54c1"
  },
  "risks": [
    {
      "id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "name": "Misstated account balances",
      "riskId": "R.001"
    }
  ],
  "rootCause": "Access controls not configured for dual-approval workflow.",
  "severity": "high",
  "soxDeficiency": "notSet",
  "status": "open",
  "supplementalInformation": "Identified during Q3 walkthrough testing.",
  "targetRemediationDate": "2026-06-30",
  "type": "auditFinding"
}

IssueBatchResult

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

Properties

Name	Type	Description	Restrictions
data	[Issue]	The requested issues, in the order of the requested ids.	required, Maximum items: 50

Example

{
  "data": [
    {
      "collaborators": [
        {
          "id": "u_4cc9f9128a684f45a7a37b08b70b54c1"
        }
      ],
      "created": {
        "dateTime": "2026-03-15T14:30:00Z",
        "user": {
          "id": "u_4cc9f9128a684f45a7a37b08b70b54c1"
        }
      },
      "customFields": [
        {
          "enumValue": "High",
          "id": "8f3c1a2b-4d5e-4f6a-8b7c-9d0e1f2a3b4c",
          "name": "Risk Rating",
          "type": "singleSelectEnum"
        }
      ],
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "isOverdue": false,
      "modified": {
        "dateTime": "2026-03-20T09:00:00Z",
        "user": {
          "id": "u_4cc9f9128a684f45a7a37b08b70b54c1"
        }
      },
      "name": "Segregation of duties violation in AP processing",
      "reportedDate": "2026-03-15",
      "severity": "high",
      "status": "open",
      "type": "auditFinding"
    }
  ]
}

IssueBatchRetrievalRequest

A request to retrieve a set of issues by id.

Properties

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

Example

{
  "data": [
    "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e"
  ]
}

IssueCollection

A collection of issues.

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	[Issue]	The issues in this page.	required

Example

{
  "@nextLink": "https://api.app.wdesk.com/issues?$next=b3BhcXVlLWN1cnNvci10b2tlbi05ZjhlN2Q=",
  "data": [
    {
      "collaborators": [
        {
          "id": "u_4cc9f9128a684f45a7a37b08b70b54c1"
        }
      ],
      "created": {
        "dateTime": "2026-03-15T14:30:00Z",
        "user": {
          "id": "u_4cc9f9128a684f45a7a37b08b70b54c1"
        }
      },
      "customFields": [
        {
          "enumValue": "High",
          "id": "8f3c1a2b-4d5e-4f6a-8b7c-9d0e1f2a3b4c",
          "name": "Risk Rating",
          "type": "singleSelectEnum"
        }
      ],
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "isOverdue": false,
      "modified": {
        "dateTime": "2026-03-20T09:00:00Z",
        "user": {
          "id": "u_4cc9f9128a684f45a7a37b08b70b54c1"
        }
      },
      "name": "Segregation of duties violation in AP processing",
      "reportedDate": "2026-03-15",
      "severity": "high",
      "status": "open",
      "type": "auditFinding"
    }
  ]
}

IssueExportAccepted

The body of the 202 response to an export request. The operation to poll is named in the Location header.

Properties

Name	Type	Description	Restrictions
updatedAt	IssueExportEffectiveWindow	The effective half-open [from, to) window the export honors, computed once when the request was received and persisted on the job.	required

Example

{
  "updatedAt": {
    "from": "2025-10-01T00:00:00Z",
    "to": "2026-10-01T00:00:00Z"
  }
}

IssueExportEffectiveWindow

The effective half-open [from, to) window the export honors, computed once when the request was received and persisted on the job.

Properties

Name	Type	Description	Restrictions
from	string(date-time)	Inclusive start of the effective window.	required
to	string(date-time)	Exclusive end of the effective window: the earlier of the requested to and 30 seconds before the request. A sync client starts its next window here, not at its own clock.	required

Example

{
  "from": "2025-10-01T00:00:00Z",
  "to": "2026-10-01T00:00:00Z"
}

IssueExportRequest

Request to export issues to a file.

Properties

Name	Type	Description	Restrictions
filter	string	A filter expression using the $filter grammar and fields of GET /issues. An invalid expression returns 400 with code invalidFilter and target /filter.
format	string	The file format. jsonl, recommended for sync and import: one JSON object per line, each exactly the public Issue object, custom fields included, with no escaping. csv: fixed columns (see the operation description) plus one column per non-archived custom field headed by its display name; id lists and multi-select values are ;-joined, and text cells starting with =, +, -, @, tab or carriage return are prefixed with ' (OWASP CSV injection list). CSV values may therefore carry an escape prefix, so sync clients should use jsonl. An unsupported value returns 400 (invalidRequest, target /format).	required
updatedAt	IssueExportUpdatedAtWindow	A half-open [from, to) window in UTC over issue updatedAt, so it covers issues created or changed in the window. The default window is 365 days (P365D) and the maximum 366 days (P366D); a longer window returns 400 (invalidRequest, target /updatedAt). With neither bound the last 365 days apply. The effective upper bound is the earlier of to and 30 seconds before now.

Enumerated Values

Property	Value
format	csv
format	jsonl

Example

{
  "filter": "status eq 'open'",
  "format": "jsonl",
  "updatedAt": {
    "from": "2025-10-01T00:00:00Z",
    "to": "2026-10-01T00:00:00Z"
  }
}

IssueExportUpdatedAtWindow

A half-open [from, to) window in UTC over issue updatedAt, so it covers issues created or changed in the window. The default window is 365 days (P365D) and the maximum 366 days (P366D); a longer window returns 400 (invalidRequest, target /updatedAt). With neither bound the last 365 days apply. The effective upper bound is the earlier of to and 30 seconds before now.

Properties

Name	Type	Description	Restrictions
from	string(date-time)	Inclusive start of the window. Defaults to 365 days before to. A from within the last 30 seconds with no to returns 400.
to	string(date-time)	Exclusive end of the window. Defaults to the earlier of now and 365 days after from; the effective value is the earlier of this and 30 seconds before now.

Example

{
  "from": "2025-10-01T00:00:00Z",
  "to": "2026-10-01T00:00:00Z"
}

IssueResolutionType

How the issue was resolved. Known values: remediated, riskAccepted, noActionRequired, duplicate, invalidCancelled, other. 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 the issue was resolved. Known values: remediated, riskAccepted, noActionRequired, duplicate, invalidCancelled, other. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.

Example

"remediated"

IssueSeverity

The severity of the issue. Known values, from lowest to highest: minor, moderate, high. unassigned means no severity has been set. 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 severity of the issue. Known values, from lowest to highest: minor, moderate, high. unassigned means no severity has been set. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.

Example

"high"

IssueStatus

The status of the issue. Known values: draft, open, inRemediation, pendingVerification, resolved, dismissed. 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 status of the issue. Known values: draft, open, inRemediation, pendingVerification, resolved, dismissed. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.

Example

"open"

IssueType

The type of the issue. Known values: auditFinding, controlIssue, generalIssue. general is a deprecated legacy value carried over from issues created before typed issues existed and is not a documented value clients should plan around, though it may still appear on old data. 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 type of the issue. Known values: auditFinding, controlIssue, generalIssue. general is a deprecated legacy value carried over from issues created before typed issues existed and is not a documented value clients should plan around, though it may still appear on old data. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.

Example

"auditFinding"

JSONPatchDocument

A JSON Patch document (RFC 6902): an ordered list of operations to apply to the resource. Each endpoint that accepts one lists the paths and value types it supports, and the most operations a document may carry, in its description.

Properties

Name	Type	Description	Restrictions
anonymous	[JSONPatchOperation]	A JSON Patch document (RFC 6902): an ordered list of operations to apply to the resource. Each endpoint that accepts one lists the paths and value types it supports, and the most operations a document may carry, in its description.	Minimum items: 1, Maximum items: 100

Example

[
  {
    "op": "replace",
    "path": "/name",
    "value": "Updated name"
  }
]

JSONPatchOperation

A single JSON Patch operation (RFC 6902). This API supports replace.

Properties

Name	Type	Description	Restrictions
op	string	The operation to perform. Only replace is supported.	required
path	string	A JSON Pointer (RFC 6901) to the field to change. See the endpoint’s description for the supported paths.	required
value	any	The new value for the target field. The type depends on the field being patched (string, array, object, or null where the field is clearable); see the endpoint’s description.	required

Enumerated Values

Property	Value
op	replace

Example

{
  "op": "replace",
  "path": "/name",
  "value": "Updated name"
}

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"

SoxDeficiency

The SOX deficiency classification. Known values: notSet, deficiency, materialWeakness, significantDeficiency. 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 SOX deficiency classification. Known values: notSet, deficiency, materialWeakness, significantDeficiency. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.

Example

"notSet"

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