Forma Reviews API Adds Approver Delegation, More Initiator Controls, and Approval Tracking

Disclosure: parts of this post were produced with the assistance of AI tools, then reviewed and edited by the author

In the previous update, the Forma Reviews API added Update Attributes and more granular Initiator Edit Permissions to Approval Workflows. This release extends both areas further, and adds a way to track who and when a review was finally approved.

With this update, when creating or retrieving an Approval Workflow (POST workflows / GET workflows / GET workflows/:workflowId), you can now:

Grant initiators two new initiatorEditPermissions values in additionalOptions:
- CLOSED_REVIEW_TITLE — allows initiators to rename closed reviews.
- START_OWN_REVIEW — allows initiators to start their own reviews.
Grant approvers edit permissions via a new additionalOptions.approverEditPermissions array. Its only current value, APPROVERS, lets approvers modify the approver candidate list — useful for delegating an approval to someone else on the fly.

And when querying reviews or review versions:

GET reviews and GET reviews/:reviewId now return approvedBy (an object with the final approver’s autodeskId and name) and approvedAt (ISO 8601 timestamp) — both empty/null until the review is final-approved.
GET reviews gains matching filter[approvedBy] (up to 10 comma-separated Autodesk IDs) and filter[approvedAt] (date range) query parameters, so you can pull “everything Jane approved in June” directly from the API instead of filtering client-side.
GET reviews/:reviewId/versions now recognizes largeList as a custom attribute type in reviewContent.customAttributes[].type, alongside the existing string, date, and array types — matching the large drop-down list custom attributes added to the Files API.

⚠️ If your app switches on initiatorEditPermissions, additionalOptions, or the custom attribute typefield, update it to recognize these new values so unrecognized ones don’t fall through silently.

About the Reviews API

The Reviews tool is a module within Autodesk Forma Data Management. It provides a tool to send files for review using the approval workflow feature, which enables project administrators to facilitate, control, and automate the distribution of files to project members. Project members assigned as reviewers can then review and comment on the files, and members selected as approvers can give final approval for the files to be used.

In summary, the Reviews tool enables document managers to distribute project drawings, models, and files for review and approval prior to the commencement of construction. You can find information about the Reviews tool feature in the product help.

Updated Endpoints

WRITE endpoints

POST workflows: Create an approval workflow — now accepts the new initiatorEditPermissions values and approverEditPermissions.

READ endpoints

GET workflows/:workflowId: Retrieves details of a single approval workflow — now returns approverEditPermissions.
GET workflows: A list of approval workflow definitions — now returns approverEditPermissions.
GET reviews: A list of reviews — now returns approvedBy/approvedAt and supports filtering on them.
GET reviews/:reviewId: Retrieves details of a single review — now returns approvedBy/approvedAt.
GET reviews/:reviewId/versions: Retrieves file versions in a review — now recognizes the largeList custom attribute type.

Documentation

Field Guide: Overview of terminology and background information related to Reviews and the Reviews API.
Step-by-step Tutorial – Create Approval Workflows: Instructions on how to create an approval workflow.
Step-by-step Tutorial – Create a Review: Instructions on how to start a review from an approval workflow.
Step-by-step Tutorial – Inspect a Review: Instructions on how to query a review’s resources, including its versions.
Reviews v1 Changelog: See the 2026-07-28 (v1.4.0) entry for full release notes.