Assurance Projects

Read assurance projects, and update the scope documentation (the scopingRationale and attached Workiva files) on Independent Controls Testing projects via PATCH /assuranceProjects/{id}. Projects cannot be created, renamed, or deleted through this API.

AssuranceProject

An assurance project. Only fields common to every project type are returned, so the shape is stable as new project types are added.

Properties

Name	Type	Description	Restrictions
budgetedHours	integer(int32)	The number of hours budgeted for the project.
contributors	[User]	The users who contribute to the project.
endDate	string(date)	The project end date.	required
id	string	The unique system identifier of the project.	required
managers	[User]	The users who manage the project.
name	string	The name of the project.	required
objective	string	The project’s objective.
scopingFiles	[ScopingFile]	Workiva files attached to the project as scoping documentation. Read-only here; set the attached set with PATCH /assuranceProjects/{id} (scopingFiles). Returned only when a single project is fetched by id.
scopingRationale	string¦null	The project-level scoping rationale: a single free-text narrative explaining how the engagement’s overall scope was determined. This is distinct from a scoped control’s own scopeRationale, which documents why one specific control was removed from scope. Applies to project types that scope controls (such as Independent Controls Testing); null for other types. Update it with PATCH /assuranceProjects/{id}.
startDate	string(date)	The project start date.	required
status	AssuranceProjectStatus	The status of an assurance project. Known values: notStarted, inProgress, completed, cancelled. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.	required
type	AssuranceProjectType	The type of assurance project. Known values: independentControlsTesting. This field is a string, not a fixed enum — additional project types will be introduced over time, so clients should tolerate unrecognized values.	required
year	integer(int32)	The fiscal year the project covers.	required

Example

{
  "budgetedHours": 1200,
  "contributors": [
    {
      "id": "u_9f8e7d6c5b4a43210f1e2d3c4b5a6978"
    }
  ],
  "endDate": "2026-12-31",
  "id": "019f14d1-7c8a-7f81-bd63-0677ee3fa6f8",
  "managers": [
    {
      "id": "u_4cc9f9128a684f45a7a37b08b70b54c1"
    }
  ],
  "name": "FY26 Controls Testing",
  "objective": "Test the operating effectiveness of key financial controls.",
  "scopingFiles": [
    {
      "id": "019f2b7c-8d9e-7a01-b2c3-4d5e6f7a8b9c",
      "workivaFile": {
        "id": "019f2a3b-4c5d-7e6f-8a9b-0c1d2e3f4a5b",
        "name": "FY26 Materiality Analysis",
        "type": "document"
      }
    }
  ],
  "scopingRationale": "FY26 scope limited to key controls over financial reporting per materiality analysis.",
  "startDate": "2026-01-01",
  "status": "notStarted",
  "type": "independentControlsTesting",
  "year": 2026
}

AssuranceProjectCollection

A collection of assurance projects.

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	[AssuranceProject]	The assurance projects in this page.	required

Example

{
  "@nextLink": "https://api.app.wdesk.com/assuranceProjects?$next=b3BhcXVlLWN1cnNvci10b2tlbi05ZjhlN2Q=",
  "data": [
    {
      "endDate": "2026-12-31",
      "id": "019f14d1-7c8a-7f81-bd63-0677ee3fa6f8",
      "name": "FY26 Controls Testing",
      "startDate": "2026-01-01",
      "status": "notStarted",
      "type": "independentControlsTesting",
      "year": 2026
    }
  ]
}

AssuranceProjectStatus

The status of an assurance project. Known values: notStarted, inProgress, completed, cancelled. 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 an assurance project. Known values: notStarted, inProgress, completed, cancelled. This field is a string, not a fixed enum — additional values may be introduced over time, so clients should tolerate unrecognized values.

Example

"notStarted"

AssuranceProjectType

The type of assurance project. Known values: independentControlsTesting. This field is a string, not a fixed enum — additional project types will be introduced over time, so clients should tolerate unrecognized values.

Properties

Name	Type	Description	Restrictions
anonymous	string	The type of assurance project. Known values: independentControlsTesting. This field is a string, not a fixed enum — additional project types will be introduced over time, so clients should tolerate unrecognized values.

Example

"independentControlsTesting"

JSONPatchDocument

A JSON Patch document (RFC 6902): an ordered list of operations to apply to the resource. On an assurance project, the supported operations are replace on /scopingRationale and replace on /scopingFiles.

Properties

Name	Type	Description	Restrictions
anonymous	[JSONPatchOperation]	A JSON Patch document (RFC 6902): an ordered list of operations to apply to the resource. On an assurance project, the supported operations are replace on /scopingRationale and replace on /scopingFiles.	Maximum items: 2

Example

[
  {
    "op": "replace",
    "path": "/scopingRationale",
    "value": "FY26 scope limited to key controls over financial reporting per materiality analysis."
  },
  {
    "op": "replace",
    "path": "/scopingFiles",
    "value": [
      {
        "id": "019f2a3b-4c5d-7e6f-8a9b-0c1d2e3f4a5b"
      }
    ]
  }
]

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 to the field to change. Supported values are /scopingRationale and /scopingFiles.	required
value	any	The new value for the target field. A string for /scopingRationale; for /scopingFiles, the complete set of attached Workiva files as an array of { id } objects (replace-set; [] detaches all).	required

Enumerated Values

Property	Value
op	replace

Example

{
  "op": "replace",
  "path": "/scopingRationale",
  "value": "FY26 scope limited to key controls over financial reporting per materiality analysis."
}

ScopingFile

A Workiva file attached to a project as scoping documentation.

Properties

Name	Type	Description	Restrictions
id	string	The unique id of this attachment. Distinct from the file’s own id.	required
workivaFile	WorkivaFile	A Workiva file (document, spreadsheet, or presentation).	required

Example

{
  "id": "019f2b7c-8d9e-7a01-b2c3-4d5e6f7a8b9c",
  "workivaFile": {
    "id": "019f2a3b-4c5d-7e6f-8a9b-0c1d2e3f4a5b",
    "name": "FY26 Materiality Analysis",
    "type": "document"
  }
}

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

WorkivaFile

A Workiva file (document, spreadsheet, or presentation).

Properties

Name	Type	Description	Restrictions
id	string	The unique id of the Workiva file.	required
name	string	The file’s display name.
type	string	The kind of Workiva file. Known values are document, spreadsheet, and presentation; treat this as an open string and tolerate values beyond those listed.

Example

{
  "id": "019f2a3b-4c5d-7e6f-8a9b-0c1d2e3f4a5b",
  "name": "FY26 Materiality Analysis",
  "type": "document"
}