Autodesk Construction Cloud Submittals Write API and Updates

8/28/2024 update: As of 8/28/2024, ACC Submittals API added one extra READ endpoint: GET responses.

We are pleased to announce that Autodesk Construction Cloud Submittals API has released some endpoints with WRITE support and some minor updates.

Submittals is one of the modules in Autodesk Build. It provides a tool to easily create and organize submittal items, such as shop drawings and specifications, to submit/notify for review and distribution among stakeholders, and to track progress and report. You can find information about the Submittals feature in the product help.

In this second phase of Submittals API, we have released night (9) new endpoints needed for creating submittals items:

WRTIE endpoints

POST items: Create a Submittal Item.
POST spec: Create a Spec Section.

READ endpoints

GET items:next-custom-identifier: Retrieve a suggested next possible custom number for a new item.
POST items:validate-custom-identifier: Verify if the given custom number has been used.
GET itemTypes: Retrieve Item Types.
GET settings/mappings: Retrieve Submittal manager settings.
GET metadata: Retrieve project metadata for submittal roles, user types, statuses, and custom numbering type (global numbering vs. spec sequence numbering).
GET Users/me: Retrieve submittal permissions for the current user calling the API.
GET responses: Retrieve a list of submittal responses.

Updates

Submittals items-related endpoints have new fields `customIdentifier` & `customIdentifierHumanReadable` for supporting custom numbering for managers to set custom alphanumeric submittal numbers for items.
GET items now have two new filters:
- filter[packageId]: For filtering submittal items by package ID.
- filter[reviewResponseId]: For filtering submittal items by review response ID.

The following Q&A may answer some of your questions:

Q1. What is the difference between `customIdentifier` and `customIdentifierHumanReadable` in Submittals items-related endpoints?

A1. When an ACC build project uses a different custom numbering type in submittals settings, both values of `customIdentifier` and `customIdentifierHumanReadable` will be different as the following:

customIdentifier: Represents the sequential number for the items. The value for an unnumbered item's customIdentifier is null.
customIdentifierHumanReadable:
- When projects use global numbering, the values of `customIdentifierHumanReadable` and `customIdentifier` will be the same.
- When projects use spec section numbering, the value of `customIdentifierHumanReadable` will be in the `<spec ID>-<sequential number>` format. For example, a spec's ID is `033100` and sequential number of an item under this spec is `01`, then this item's `customIdentifierHumanReadable` will be `033100-01`.

Q2. The documentation of GET items:next-custom-identifier shows that this endpoint reuses deleted or cleared numbers, but why does this endpoint still not return the cleared number in `nextCustomIdentifier` after clearing the number from an existing item?

A2. The GET items:next-custom-identifier will only suggest `higher` numbers in the `nextCustomIdentifier` field. Let's take some examples to illustrate what this means below:

➡️ For example:

You created items using `customIdentifier`=`1`, `customIdentifier`=`2`, and then another one using `customIdentifier`=`3`.
You deleted the item with `customIdentifier`=`2` or cleared this item's `customIdentifier` value from ACC Web UI.

In this case:

GET items:next-custom-identifier will suggest `4` for `nextCustomIdentifier`. But if you call POST items:validate-custom-identifier with `customIdentifier`=`2`, then you will receive a response with status code 204, which means `customIdentifier`=`2` can be used for creating a new item or assigning it to an existing item.

So, this matches what we mentioned that "GET items:next-custom-identifier will only suggest `higher` numbers for `nextCustomIdentifier`".

➡️ Another example:

You created an item with `customIdentifier`=`2`
You updated the same item with `customIdentifier`=`4`

Here, GET items:next-custom-identifier will suggest `nextCustomIdentifier`=`3`, not `5`.

Why does this happen? This is because:

➡️ Only numbers (custom identifiers) set upon item creation will directly affect the value of nextCustomIdentifier suggested by GET items:next-custom-identifier.

➡️ Exception:

However, there is an exception case, for example:

You created an item using `customIdentifier`=`2`
And then updated this item's `customIdentifier` to `3`

In this exception case:

Next time, you call GET items:next-custom-identifier, it will suggest nextCustomIdentifier=`4`, because customIdentifier=`3` is already taken for another item.

Documentation

Field Guide: This page describes the terminology and background information about Submittals and Submittals API. It also includes information about the scope of the current release and its limitations.
Step-by-step Tutorial - Create a Submittal Item: This newly added page provides instructions on how to create submittal items.
Reference Guide: This section lists a set of endpoints for creating and retrieving submittal items and spec sections, as well as retrieving user permissions, submittal managers, packages, item types, responses, and attachments.