projects/{projectId}/items/{id}
Retrieve information about a single submittal item that the user has permission to view. 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/:id |
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. |
id string | The ID of the metadata object for the submittal. |
Response
HTTP Status Code Summary
200 OK | Request and response for the successful creation of a submittal item. |
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)
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 |
Example
Request and response for the successful creation of a submittal item.
Request
curl -v 'https://developer.api.autodesk.com/construction/submittals/v2/projects/9eae7d59-1469-4389-bfb2-4114e2ba5545/items/:id' \
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a'
Response
{
"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"
}
]
}
]
}