projects/{projectId}/items
Retrieves information about all the submittal items in a project that the user has permission to view.
Note that only managers can access submittals items in draft
state.
Note also that submittal items in void
state are excluded by default.
For information about submittal items, see the Help documentation.
Resource Information
Method and URI | GET https://developer.api.autodesk.com/construction/submittals/v2/projects/:projectId/items |
Authentication Context | user context required |
Required OAuth Scopes | data:read |
Data Format | JSON |
Request
Headers
Authorization* string | Must be Bearer <token> , where <token> is obtained via a three-legged OAuth flow. |
Request
URI Parameters
projectId string: UUID | The ID of the project.
Use the Data Management API to retrieve the project ID. For more information, see the Retrieve a Project ID tutorial. You need to convert the project ID into a project ID for the ACC API by removing the “b." prefix. For example, a project ID of b.a4be0c34a-4ab7 translates to a project ID of a4be0c34a-4ab7. |
Request
Query String Parameters
limit int | The number of results to return per page in the response payload. Possible values: 1 - 50 . Default value: 20 . For example, to limit the response to two results per page, use limit=2 . |
offset int | The page number from which you want to begin results; for example, offset=20 . For more details, see the JSON API Paging documentation. |
sort string | Sort items by specified fields. Separate multiple values with commas. To sort in descending or ascending order, add desc or asc after the sort criteria. For example, statusId asc .
Possible values: |
search string | Search for items by querying a specified string within specific fields (identifier , title , specIdentifier , ballInCourt ), and retrieve the associated items that match the search criteria. This includes items where the string matches part of a field. For example, search=1 . |
filter[title] string | Filter items with the specified title. You can specify multiple values. Separate multiple values with commas. For example, filter[title]="Shop Drawings" . |
filter[statusId] string | Filter items with the specified status ID. You can specify multiple values. Separate multiple values with commas. For example, filter[statusId]=1 |
filter[specId] string | Filter items with the specified spec ID. You can specify multiple values. Separate multiple values with commas. For example, filter[specId]=b4aa3864-5706-4a7b-b06c-a792e8b2df23 |
filter[ballInCourtUsers] string | Filter items associated with the specified ball-in-court user ID. You can specify multiple users. Separate multiple values with commas. For example, filter[ballInCourtUsers]=HNRCQ6JTWAED . |
filter[ballInCourtCompanies] string | Filter items associated with the specified ball-in-court company ID. You can specify multiple companies. Separate multiple values with commas. For example, filter[ballInCourtCompanies]=WD43ZJGKDFLFH . |
filter[ballInCourtRoles] string | Filter items associated with the specified ball-in-court role ID. You can specify multiple roles. Separate multiple values with commas. For example, filter[ballInCourtRoles]=WD43ZJGKDFLFH . |
filter[responseId] string | Filter items with the specified final response ID. You can specify multiple IDs. You can specify multiple values. Separate multiple values with commas. For example, filter[responseId]=1w66d30b-7dc1-4a65-991d-d739a1381rf4 . |
filter[reviewResponseId] string | Filter items with the specified review response ID. You can specify multiple IDs. You can specify multiple values. Separate multiple values with commas. For example, filter[reviewResponseId]=1w66d30b-7dc1-4a65-991d-d739a1381rf4 . |
filter[typeId] string | Filter items with the specified type ID. You can specify multiple values. Separate multiple values with commas. For example, filter[typeId]=06fa0c1b-6462-459d-8a38-0aff11bfe868 . |
filter[packageId] string | Filter items with the specified package ID. You can specify multiple values. Separate multiple values with commas.
For example, filter[packageId]=06fa0c1b-6462-459d-8a38-0aff11bfe868 .
In order to filter items with no package, use ‘noPackage’ value. |
filter[stateId] string | Filter items with the specified state ID. You can specify multiple values. Separate multiple values with commas. For example, filter[stateId]=rev . |
filter[identifier] string | Filter items with the specified submittal item ID (the submittal item ID in the UI). You can specify multiple values. Separate multiple values with commas. For example, filter[identifier]=2 . |
filter[leadTime] string | Filter items with the specified lead time. You can specify multiple values. Separate multiple values with commas. For example, filter[leadTime]=100 . |
filter[revision] string | Filter items with the specified revision number. You can specify multiple values. Separate multiple values with commas. For example, filter[revision]=1 . |
filter[manager] string | Filter items with the specified manager Autodesk ID. You can specify multiple values. Separate multiple values with commas. For example, filter[manager]=WD43ZJGKDFLFH . |
filter[managerType] string | Filter items with the specified manager type. You can specify multiple values. Separate multiple values with commas. For example, filter[managerType]=1 . |
filter[subcontractor] string | Filter items with the specified subcontractor Autodesk ID. You can specify multiple values. Separate multiple values with commas. For example, filter[subcontractor]=WD43ZJGKDFLFH . |
filter[subcontractorType] string | Filter items with the specified subcontractor type. You can specify multiple values. Separate multiple values with commas. For example, filter[subcontractorType]=1 . |
filter[createdBy] string | Filter items that were created by the specified user by specifying the user’s Autodesk ID. For example, filter[createdBy]=PER8KQPK2JRT . To find the ID call GET users. |
filter[watchers] string | Filter items that are associated with the specified watcher, by specifying the watcher’s Autodesk ID. For example, filter[watchers]=PER8KQPK2JRT . You can specify more than one watcher. Separate multiple values with commas. To find the ID call GET users. |
filter[dueDate] string | Filter items with the specified due date, using the following URL-encoded format YYYY-MM-DD. We support the following filtering options:
For more details, see JSON API Filtering. |
filter[submitterDueDate] string | Filter items with the specified submitter’s due date, using the following URL-encoded format YYYY-MM-DD. We support the following filtering options:
For more details, see JSON API Filtering. |
filter[managerDueDate] string | Filter items with the specified manager’s due date, using the following URL-encoded format YYYY-MM-DD. We support the following filtering options:
For more details, see JSON API Filtering. |
filter[createdAt] string | Filter items with the specified creation date, using the following URL-encoded format YYYY-MM-DD. We support the following filtering options:
For more details, see JSON API Filtering. |
filter[sentToSubmitter] string | Filter items based on the date they were sent to the submitter. Use the following URL-encoded format: YYYY-MM-DD. We support the following filtering options:
For more details, see JSON API Filtering. |
filter[receivedFromSubmitter] string | Filter items based on the date they were received from the submitter. Use the following URL-encoded format: YYYY-MM-DD. We support the following filtering options:
For more details, see JSON API Filtering. |
filter[sentToReview] string | Filter items based on the date they were sent for review, in the URL-encoded format: YYYY-MM-DD. We support the following filtering options:
For more details, see JSON API Filtering. |
filter[receivedFromReview] string | Filter items based on the date they were moved forward by the reviewer using the URL-encoded format: YYYY-MM-DD. We support the following filtering options:
For more details, see JSON API Filtering. |
filter[publishedDate] string | Filter items based on their published date using the following URL-encoded format: YYYY-MM-DD. We support the following filtering options:
For more details, see JSON API Filtering. |
filter[requiredDate] string | Filter items based on the date the responsible contractor needs to submit the submittal to the submittal manager, using the following URL-encoded format: YYYY-MM-DD. We support the following filtering options:
For more details, see JSON API Filtering. |
filter[requiredApprovalDate] string | Filter items based on their required approval date using the following URL-encoded format: YYYY-MM-DD. We support the following filtering options:
For more details, see JSON API Filtering. |
filter[requiredOnJobDate] string | Filter items based on their required on-job (jobsite) date using the following URL-encoded format: YYYY-MM-DD. We support the following filtering options:
For more details, see JSON API Filtering. |
filter[updatedAt] string | Filter items by their last updated date using the following URL-encoded format: YYYY-MM-DD. We support the following filtering options:
For more details, see JSON API Filtering. |
filter[id] string | Filter submittal items by their unique internal submittal item ID (UUID). You can specify multiple values. Separate multiple values with commas. For example filter[id]=b8cc9324-6759-4f07-8ce3-725d5afd4f11 . |
Response
HTTP Status Code Summary
200 OK | A list of items. |
400 Bad Request | The request could not be understood by the server due to malformed syntax or missing request headers. |
401 Unauthorized | Invalid Authorization header. Verify and try again. |
403 Forbidden | The user is not authorized to perform this action. |
404 Not Found | The specified resource was not found. |
500 Internal Server Error | An unexpected error occurred on the server while processing the request. |
Response
Body Structure (200)
results array: object | The list of submittal items. |
id string: UUID | The internal, globally unique identifier (UUID) for the item. |
identifier int | The unique ID assigned to the submittal item within the user interface (UI). |
customIdentifier string | customIdentifier and customIdentifierHumanReadable relate to the Number column in the UI. Submittal managers assign custom numbers to items (manually or automatically). Custom numbers are configured either in global numbering format: <global number>, or in spec section numbering format: <spec ID>-<sequential number>.
For projects with a global numbering format, both For projects with a spec section numbering format (<spec ID>-<sequential number>), Note that for unnumbered items For more information on custom numbering, see the Help documentation. |
customIdentifierHumanReadable string | customIdentifierHumanReadable and customIdentifier relate to the Number column in the UI. Submittal managers assign custom numbers to items (manually or automatically). Custom numbers are configured either in global numbering format: <global number>, or in spec section numbering format: <spec ID>-<sequential number>.
For projects with a global numbering format, both For projects with a spec section numbering format (<spec ID>-<sequential number>), Note that for unnumbered items For more information on custom numbering, see the Help documentation. |
typeId string | The ID representing the type of submittal item. |
specId string: UUID | The unique identifier (UUID) of the spec assigned to the item. |
specIdentifier string | The identifier of the spec section that is associated with the submittal item. The identifier is assigned to the spec spection in the user interface (UI). |
specTitle string | The title of the spec associated with the submittal item. |
subsection string | The sub-spec section associated with the item, providing additional categorization within the main spec. |
title string | The title of the submittal item. |
description string | The description of the submittal item. |
priority enum:string | The priority of the submittal item.
Possible values: Low , Normal , High |
revision int | The revision number of the submittal item. |
stateId enum:string | The current state of the submittal item, indicating its position in the workflow after creation or update.
Possible values:
|
statusId enum:string | The status of the submittal item. Possible values: 1 - (Required), 2 - (Open), 3 - (Closed), 4 - (Void), 5 - (Empty), 6 - (Draft).
You can find the list of possible statuses by calling GET metadata. |
ballInCourtUsers array: string | The Autodesk IDs of users who are currently assigned to the submittal item at this stage of the workflow. |
ballInCourtCompanies array: string | The member group IDs of the companies currently assigned to the submittal item at this stage of the workflow. |
ballInCourtRoles array: string | The member group IDs of user roles that are currently assigned to the submittal item at this stage of the workflow. |
ballInCourtType enum:string | The type of submittal role assigned to the user currently assigned to the submittal item. Possible values: reviewer , manager , subcontractor . |
manager string | The ID that was assigned to the manager of the submittal item. If the creator of the submittal item held a manager role, they were automatically set as the manager .
To determine the type of the manager (i.e., user, role, or company), refer to the manager type ( |
managerType enum:string | The type of manager.
Possible values: 1 (user), 2 (company), 3 (role). |
subcontractor string | The ID that was assigned to the subcontractor for the submittal item. If a non-manager user created the submittal item and chose a manager, they were automatically assigned as the subcontractor of the submittal item. |
subcontractorType enum:string | The type of subcontractor.
Possible values: 1 (user), 2 (company), 3 (role). |
watchers array: object | A list of project watchers, who can be individual users, roles, or companies. |
id string | The Autodesk ID of the watcher. The watcher can be a user (autodeskId ), role (memberGroupId ), or company (memberGroupId ).
To find details about users, call GET users, to find details about companies, call GET companies. Note that we do not currently support finding details about roles for a project. |
userType object | The type of watcher. Possible values: 1 (user), 2 (company), 3 (role). |
dueDate string | The due date for the submittal item, in the following format: YYYY-MM-DD (ISO 8601) in UTC. For example, 2018-02-15 . |
requiredOnJobDate string | The date when the materials are expected to arrive on the construction site, in the following format: YYYY-MM-DD (ISO 8601) in UTC. For example, 2018-02-15 . |
leadTime int | The duration in days from the approval of the submittal to delivery of materials or products to the construction site. |
requiredDate string | The date by which the responsible contractor needs to submit the submittal to the submittal manager, in the following format: YYYY-MM-DD (ISO 8601) in UTC. For example, 2018-02-15 . |
requiredApprovalDate string | The date by which approval for the submittal is required, in the following format: YYYY-MM-DD in UTC (ISO 8601). For example, 2018-02-15 . |
submitterDueDate string | The date by which the subcontractor is expected to submit the submittal to the manager, in the following format: YYYY-MM-DD in UTC (ISO 8601). For example, 2018-02-15 . This corresponds to the sbc-1 state Waiting for submission . |
sentToSubmitter datetime: ISO 8601 | The date when the submittal was sent to the subcontrator for review. |
receivedFromSubmitter datetime: ISO 8601 | The date when the submittal was received back from the subcontractor after review. |
submittedBy string | The Autodesk ID of the user who submitted the submittal item. This is the user who transitioned the item to the manager. |
managerDueDate string | The date by which the manager is expected to prepare the submittal item for review, formatted as YYYY-MM-DD in UTC (ISO 8601). For example, 2018-02-15 . This corresponds to the mgr-1 state Open (Submitted) . |
sentToReview datetime: ISO 8601 | The date and time when the submittal item was transitioned to the rev state (Open - In review) , formatted as ISO 8601. |
sentToReviewBy string | The Autodesk ID of the user who transitioned the item to the rev state (Open - In review) . |
receivedFromReview datetime: ISO 8601 | The timestamp marking when the item transitioned from the rev state (Open - In Review) to the mgr-2 state Open (Reviewed) . |
publishedDate datetime: ISO 8601 | The date when the manager closed and distributed the submittal item. |
publishedBy string | The Autodesk ID of the user who published the submittal item. |
responseId string | The ID of the response associated with the submittal item, linking to the specific feedback or action taken. |
responseComment string | The body of the response comment, containing feedback or instructions related to the submittal item. |
respondedAt datetime: ISO 8601 | The time and date when the response was added. |
respondedBy string | The Autodesk ID of the user that gave the response to the submittal item. |
packageId string: UUID | The ID of the package associated with the submittal item. |
packageIdentifier string | The package identifier as displayed in the user interface (UI). |
packageTitle string | The title of the package associated with the submittal item. |
packageSpecIdentifier string | The identifier of the spec associated with the package. |
folderUrn string | The URN of the folder that contains the attachments associated with the submittal items. |
revisionsFoldersUrns object | An object containing URNs that represent folders associated with the revisions of the submittal item. These URNs can be used to access and identify specific folders related to submittal item revisions within the system. |
createdAt datetime: ISO 8601 | The date and time when the submittal item was originally created. |
createdBy string | The Autodesk ID of the user who created the submittal item. |
updatedAt datetime: ISO 8601 | The time and date when the submittal item was last updated. |
updatedBy string | The Autodesk ID of the user who last updated the submittal item. |
permittedActions array: object | A list of actions that the user is allowed to perform on the submittal item. |
id string | The ID of the action in the format type_of_object::action . For example, Item::retrieve . |
fields object | A mapping of field names to lists of possible values for each field. Note that an empty array indicates that there is no specific set of values for those fields. |
mandatoryFields array: string | Fields required to perform specific actions, such as creating or transitioning a submittal item. The required fields depend on the user’s role and the action.
For example, creating a submittal item in the |
transitions array: object | Possible state transitions for a submittal item.
A submittal item can be in one of the following states:
|
id string | The ID of the transition in the format from-state::to-state . For example, create::mgr-1 , mgr-1::mgr-2 , rev::void . |
name string | The descriptive name of the transition. For example, Create , Send to Manager , Send to void . |
stateFrom object | The starting state of the transition. |
id string | The unique ID of the starting state. For example, create , mgr-1 , rev . A rev (review ), refers to the state where a submittal item is undergoing revisions or is being reviewed. |
name string | The name of the starting state. For example, Create , Manager Review , Review . |
stateTo object | The target state of the transition. |
id string | The unique ID of the target state. For example, mgr-1 , mgr-2 , void . |
name string | The name of the target state. For example, Manager Review , Manager Final Review , Void . |
transitionFields array: string | Fields that are used in the transition. For example, [subcontractor , subcontractorType , watchers , responseId ]. |
mandatoryFields array: string | A list of required fields for the transition. For example, [responseId ]. |
actionId string | Not relevant |
pagination object | Pagination information. |
limit int | The maximum number of results to be displayed on each page. |
offset int | The number of results to skip before starting to display results on a page. |
totalResults int | The overall count of results available across all pages. |
previousUrl string | The URL to retrieve the preceding page of results, if applicable. Not returned on the first page of results. |
nextUrl string | The URL to retrieve the subsequent page of results, if available. If not included, this is the last page of data. |
Example
A list of items.
Request
curl -v 'https://developer.api.autodesk.com/construction/submittals/v2/projects/9eae7d59-1469-4389-bfb2-4114e2ba5545/items' \
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a'
Response
{
"results": [
{
"id": "b8cc9324-6759-4f07-8ce3-725d5afd4f11",
"identifier": 1111,
"customIdentifier": "A-111",
"customIdentifierHumanReadable": "0001-A-111",
"typeId": "06fa0c1b-6462-459d-8a38-0aff11bfe868",
"specId": "62d6f245-b470-4af4-802b-4cb94b5dead1",
"specIdentifier": "09-5300",
"specTitle": "Acoustical Ceilings",
"subsection": "1.05-B",
"title": "Shop Drawings",
"description": "Detailed plans by subcontractor, showing project dimensions.",
"priority": "Low",
"revision": 0,
"stateId": "rev",
"statusId": "1",
"ballInCourtUsers": [
"WD43ZJGKDFLFH"
],
"ballInCourtCompanies": [
"WD43ZJGKDFLFH"
],
"ballInCourtRoles": [
"WD43ZJGKDFLFH"
],
"ballInCourtType": "reviewer",
"manager": "WD43ZJGKDFLFH",
"managerType": "1",
"subcontractor": "WD43ZJGKDFLFH",
"subcontractorType": "1",
"watchers": [
{
"id": "224356",
"userType": "2"
},
{
"id": "3522614",
"userType": "3"
}
],
"dueDate": "2018-02-15",
"requiredOnJobDate": "2018-02-15",
"leadTime": 100,
"requiredDate": "2018-02-15",
"requiredApprovalDate": "2018-02-15",
"submitterDueDate": "2018-02-15",
"sentToSubmitter": "2018-02-01T12:09:24.198466Z",
"receivedFromSubmitter": "2018-02-01T12:09:24.198466Z",
"submittedBy": "WD43ZJGKDFLFH",
"managerDueDate": "2018-02-15",
"sentToReview": "2018-02-01T12:09:24.198466Z",
"sentToReviewBy": "WD43ZJGKDFLFH",
"receivedFromReview": "2018-02-01T12:09:24.198466Z",
"publishedDate": "2018-02-01T12:09:24.198466Z",
"publishedBy": "WD43ZJGKDFLFH",
"responseId": "2d46d30b-7dc1-4a65-991d-d739a1381eb8",
"responseComment": "",
"respondedAt": "2018-02-01T12:09:24.198466Z",
"respondedBy": "WD43ZJGKDFLFH",
"packageId": "e8302552-fc5a-42ac-ba4b-e9de9760c356",
"packageIdentifier": "222",
"packageTitle": "my package1",
"packageSpecIdentifier": "A-500",
"folderUrn": "urn:adsk.wipprod:fs.file:vf.hvNfeldTPm_aDqRNZgKjD",
"revisionsFoldersUrns": {
"0": {
"folderUrnCreatedAt": "2018-01-28 09:26:36.371607",
"revision": 0,
"folderUrn": "urn:adsk.wipprod:fs.folder:co.r04fl5B7QCa1731EeH5dYDQ"
}
},
"createdAt": "2018-02-01T12:09:24.198466Z",
"createdBy": "WD43ZJGKDFLFH",
"updatedAt": "2018-04-04T12:09:24.198466Z",
"updatedBy": "WD43ZJGKDFLFH",
"permittedActions": [
{
"id": "Item::retrieve",
"fields": {},
"mandatoryFields": [
""
],
"transitions": [
{
"id": "rev::void",
"name": "Send to void",
"stateFrom": {
"id": "rev",
"name": "REV"
},
"stateTo": {
"id": "rev",
"name": "REV"
},
"transitionFields": [
"subcontractor",
"subcontractorType",
"watchers",
"responseId"
],
"mandatoryFields": [
"responseId"
],
"actionId": "ITEM_TRANSITION_REV_VOID"
}
]
}
]
}
],
"pagination": {
"limit": 10,
"offset": 100,
"totalResults": 25,
"previousUrl": "https://developer.api.autodesk.com/construction/submittals/v2/projects/9eae7d59-1469-4389-bfb2-4114e2ba5545/settings/mappings?offset=10&limit=100",
"nextUrl": null
}
}