projects/{projectId}/items/{itemId}
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/:itemId |
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. |
itemId string | The ID of the submittal item. To find the item ID, call GET items. |
Response
HTTP Status Code Summary
200 OK | Successfully retrieved 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 or missing authorization header. Verify the Bearer token 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 submittal item. |
identifier int | The unique ID assigned to the submittal item within the UI. This ID is system-generated and serves as a reference for users interacting with submittal items through the UI. For example, 111 . |
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 submittal item. |
specIdentifier string | The identifier of the spec section that is associated with the submittal item. The identifier is assigned to the spec section in the UI. |
specTitle string | The title of the spec associated with the submittal item. |
subsection string | The sub-spec section associated with the submittal 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:
|
revision int | The revision number of the submittal item, indicating the version of the item in the submittal workflow. For example, 1 for the initial submission or 2 for the first revision. |
stateId enum:string | The current state of the submittal item after the transition.
Possible values:
|
statusId enum:string | The status of the submittal item.
Possible values: To retrieve the full list of possible statuses, call 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: |
manager string | The ID that was assigned to the manager of the submittal item.
To determine the type of the manager (user, role, or company), refer to the manager type (
Note that we do not currently support verifying names of roles. |
managerType enum:string | The type of manager associated with the submittal item.
Possible values: |
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 are automatically assigned as the subcontractor of the submittal item.
In order to get more info about the subcontractor, use:
Note that we do not currently support verifying names of roles. |
subcontractorType enum:string | The type of subcontractor associated with the submittal item.
Possible values: |
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 assigned to the submittal item.
Possible values:
|
dueDate string | The due date for the submittal item, formatted as YYYY-MM-DD in UTC (ISO 8601). For example, 2018-02-15 . |
requiredOnJobDate string | The date when the materials are expected to arrive on the construction site, formatted as YYYY-MM-DD in UTC (ISO 8601). 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 must submit the submittal to the submittal manager, formatted as YYYY-MM-DD in UTC (ISO 8601). For example, 2018-02-15 . |
requiredApprovalDate string | The date by which approval for the submittal is required, formatted as 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, formatted as 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 and time when the submittal was sent to the subcontractor for review, formatted as YYYY-MM-DDTHH:mm:ss.SSSSSSZ (ISO 8601) in UTC. For example, 2018-02-15T12:09:24.198466Z . This corresponds to transition to the sbc-1 state. |
receivedFromSubmitter datetime: ISO 8601 | The date when the submittal was received back from the subcontractor after review, formatted as YYYY-MM-DDTHH:mm:ss.SSSSSSZ (ISO 8601) in UTC. For example, 2018-02-15T12:09:24.198466Z . This corresponds to transition to mgr-1 state Open (Submitted) . |
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 transitioned to the rev state (Open - In review) , formatted as YYYY-MM-DDTHH:mm:ss.SSSSSSZ (ISO 8601) in UTC. For example, 2018-02-15T12:09:24.198466Z . |
sentToReviewBy string | The Autodesk ID of the user who transitioned the item to the rev state (Open - In review) . |
receivedFromReview datetime: ISO 8601 | The date and time when the submittal item transitioned from the rev state (Open - In Review) to the mgr-2 state (Close and distribute) , formatted as YYYY-MM-DD (ISO 8601) in UTC. For example, 2022-03-02T12:09:24Z . |
publishedDate datetime: ISO 8601 | The date when the manager closed and distributed the submittal item, in the following format: YYYY-MM-DD (ISO 8601) in UTC. For example, 2018-02-15 . |
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 date and time when the response was added, formatted as YYYY-MM-DDTHH:mm:ss.SSSSSSZ (ISO 8601) in UTC. For example, 2018-02-15T12:09:24.198466Z . |
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 UI. |
packageTitle string | The title of the package associated with the submittal item. |
packageSpecIdentifier string | The identifier of the submittal spec associated with the package. This value corresponds to the “Spec section” displayed in the UI, such as 1 - Cement . |
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, formatted as YYYY-MM-DDTHH:mm:ss.SSSSSSZ (ISO 8601) in UTC. For example, 2018-02-15T12:09:24.198466Z . |
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, formatted as YYYY-MM-DDTHH:mm:ss.SSSSSSZ (ISO 8601) in UTC. For example, 2018-02-15T12:09:24.198466Z . |
updatedBy string | The Autodesk ID of the user who last updated the submittal item. |
permittedActions array: object | The list of actions 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 list of field names for which values must be provided when performing the action. An empty array indicates no specific set of values. |
mandatoryFields array: string | Lists the fields that are required when updating a submittal item.
The required fields depend on the action being performed, the item’s current state, and the user’s role. For example: To transition the state of a submittal item, |
transitions array: object | The list of possible state transitions for a submittal item within the review workflow. |
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, representing the current position of the submittal item in the workflow. |
id string | The unique ID of the starting state. For example, create , mgr-1 , rev . The rev state indicates that the submittal item is currently under review. |
name string | The name of the starting state. For example, Create , Manager Review , Review . |
stateTo object | The target state of the transition, indicating the next position of the submittal item in the workflow. |
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
Successfully retrieved a submittal item.
Request
curl -v 'https://developer.api.autodesk.com/construction/submittals/v2/projects/9eae7d59-1469-4389-bfb2-4114e2ba5545/items/767b5888-2c6a-413d-8487-613966dd64ce' \
-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": "mgr-1",
"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": "Revisions required before approval.",
"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::update",
"fields": {
"subcontractor": [],
"manager": []
},
"mandatoryFields": [
""
],
"transitions": [
{
"id": "rev::void",
"name": "Send to void",
"stateFrom": {
"id": "rev",
"name": "Review"
},
"stateTo": {
"id": "void",
"name": "Void"
},
"transitionFields": [
"subcontractor",
"subcontractorType",
"watchers",
"responseId"
],
"mandatoryFields": [
"responseId"
],
"actionId": "ITEM_TRANSITION_REV_VOID"
}
]
}
]
}