Steps
GET
projects/{projectId}/items/{itemId}/steps/{stepId}
Retrieves information about a single review step associated with a submittal item.
A review step is a stage in the submittal review process that may include one or more tasks, each assigning responsibility to a reviewer (represented in the UI as a Member, Role, or Company) for completing specific actions.
For a detailed overview of the submittal workflow, see the Manage Submittal Item Transitions tutorial.
For more information about submittals and their lifecycle, see the Help documentation.
Resource Information
| Method and URI | GET https://developer.api.autodesk.com/construction/submittals/v2/projects/:projectId/items/:itemId/steps/:stepId |
| 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. |
* Required
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. |
| stepId string | The ID of the review step associated with the submittal item. To find the step ID, call GET steps. |
Response
HTTP Status Code Summary
| 200 OK | Submittal item step successfully retrieved. |
| 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)
Expand all
| id string: UUID | The internal, globally unique identifier (UUID) for the step. |
| itemId string: UUID | The ID of the item associated with the step. |
| status enum:string | The current status of the step. Possible values: not-started, in-progress, completed. |
| stepNumber number | The number representing the order of the steps, where 1 is the first step. |
| daysToRespond number | Specifies a dynamic due date. When the step starts, the due date is calculated based on this field. |
| dueDate string | The due date of the step in the format YYYY-MM-DD (ISO 8601) in UTC. For example, 2018-02-15. |
| tasks array: object | The list of tasks associated with the step. |
| id string: UUID | The internal, globally unique identifier (UUID) for the task. |
| stepId string: UUID | The ID of the review step associated with the task. |
| status enum:string | The current status of the task. Possible values: not-started, in-progress, completed. |
| assignedTo string | The Autodesk ID or member group ID of the user, company, or role assigned to the task. |
| assignedToType enum:string | Specifies whether the task is assigned to a user, company, or role.
Possible values: 1 (user), 2 (company), 3 (role). |
| isRequired boolean | true: the task is required to complete the step.
|
| stepDueDate string | The due date of the related step, formatted as YYYY-MM-DD (ISO 8601) in UTC. For example, 2025-01-20. |
| responseId string: UUID | The ID of the response associated with the task, linking to the specific feedback or action taken. |
| responseComment string | The content of the response comment, providing feedback or instructions related to the task. |
| 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, 2025-01-20T12:00:00.198466Z. |
| respondedBy string | The Autodesk ID of the user who provided the response to the task. |
| createdAt datetime: ISO 8601 | The date and time when the task was originally created, formatted as YYYY-MM-DDTHH:mm:ss.SSSSSSZ (ISO 8601) in UTC. For example, 2025-01-20T12:00:00.198466Z. |
| createdBy string | The Autodesk ID of the user who created the task. |
| updatedAt datetime: ISO 8601 | The date and time when the task was last updated, formatted as YYYY-MM-DDTHH:mm:ss.SSSSSSZ (ISO 8601) in UTC. For example, 2025-01-20T12:00:00.198466Z. |
| updatedBy string | The Autodesk ID of the user who last updated the task. |
| startedAt datetime: ISO 8601 | The date and time when the related step was marked as started (In Progress), formatted as YYYY-MM-DDTHH:mm:ss.SSSSSSZ (ISO 8601) in UTC. For example, 2025-01-20T12:00:00.198466Z. |
| completedAt datetime: ISO 8601 | The date and time when the task was completed, formatted as YYYY-MM-DDTHH:mm:ss.SSSSSSZ (ISO 8601) in UTC. For example, 2025-01-20T12:00:00.198466Z. |
| completedBy string | The Autodesk ID of the user who completed the task. |
| permittedActions array: object | A list of actions that the user is allowed to perform on the task within the submittal workflow. |
| id string | The ID of the action in the format type_of_object::action. For example, partial_update. |
| 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 closing a task. The required fields depend on the user’s role and the action. |
| transitions array: string | Not relevant |
| createdAt datetime: ISO 8601 | The date and time when the step was created, formatted as YYYY-MM-DDTHH:mm:ss.SSSSSSZ (ISO 8601) in UTC. For example, 2025-01-20T12:00:00.198466Z. |
| createdBy string | The Autodesk ID of the user that created the step. |
| updatedAt datetime: ISO 8601 | The date and time when the step was last updated, formatted as YYYY-MM-DDTHH:mm:ss.SSSSSSZ (ISO 8601) in UTC. For example, 2025-01-20T12:00:00.198466Z. |
| updatedBy string | The Autodesk ID of the user that updated the step. |
| startedAt datetime: ISO 8601 | The date and time when the step transitioned to In Progress in the backend. This corresponds to the step being marked as Started in the UI, formatted as YYYY-MM-DDTHH:mm:ss.SSSSSSZ (ISO 8601) in UTC. For example, 2025-01-20T12:00:00.198466Z. |
| completedAt datetime: ISO 8601 | The date and time when the step was completed, formatted as YYYY-MM-DDTHH:mm:ss.SSSSSSZ (ISO 8601) in UTC. For example, 2025-01-20T12:00:00.198466Z. |
| permittedActions array: object | A list of actions that the user is allowed to perform on the step. |
| id string | The ID of the action in the format type_of_object::action. For example, Step::partial_update. |
| fields object | A mapping of field names to lists of possible values for each field. If a field does not require a specific value, it will be returned as an empty array. |
| mandatoryFields array: string | A list of fields required to perform specific actions on a step, such as tasks for the Step::partial_update action. The required fields depend on the user’s role and the action. |
| transitions array: string | Not relevant |
Example
Submittal item step successfully retrieved.
Request
curl -v 'https://developer.api.autodesk.com/construction/submittals/v2/projects/9eae7d59-1469-4389-bfb2-4114e2ba5545/items/767b5888-2c6a-413d-8487-613966dd64ce/steps/b79059cc-611b-4769-80b7-f8db9a2dfcdf' \
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a'
Response
{
"id": "84eb33cd-4a42-42b7-95dd-3900035c3407",
"itemId": "2df3b4cf-16f4-496e-8173-7125f31e3dd1",
"status": "in-progress",
"stepNumber": 1,
"daysToRespond": 10,
"dueDate": "2024-02-15",
"tasks": [
{
"id": "4d539b8f-c522-4f1c-9743-d7fdfa9e9c9e",
"stepId": "d6635799-e973-4c9c-80d8-fb4b3591ef6b",
"status": "completed",
"assignedTo": "WD43ZJGKDFLFH",
"assignedToType": "1",
"isRequired": true,
"stepDueDate": "2024-02-15",
"responseId": "2d46d30b-7dc1-4a65-991d-d739a1381eb8",
"responseComment": "Approved without changes.",
"respondedAt": "2024-02-03T12:09:24.198466Z",
"respondedBy": "WD43ZJGKDFLFH",
"createdAt": "2024-03-21T23:04:49.406Z",
"createdBy": "WD43ZJGKDFLFH",
"updatedAt": "2024-03-24T23:04:49.406674Z",
"updatedBy": "WD43ZJGKDFLFH",
"startedAt": "2024-03-21T23:15:49.406894Z",
"completedAt": "2024-03-24T23:04:49.4066344Z",
"completedBy": "WD43ZJGKDFLFH",
"permittedActions": [
{
"id": "Task::partial_update",
"fields": {
"responseComment": [],
"responseId": []
},
"mandatoryFields": [
"responseId"
],
"transitions": [
""
]
}
]
}
],
"createdAt": "2024-03-21T23:04:49.406Z",
"createdBy": "WD43ZJGKDFLFH",
"updatedAt": "2024-03-24T23:04:49.406Z",
"updatedBy": "WD43ZJGKDFLFH",
"startedAt": "2024-03-21T23:15:49.406Z",
"completedAt": "2024-03-24T23:04:49.406Z",
"permittedActions": [
{
"id": "Step::overwrite_step",
"fields": {
"tasks": []
},
"mandatoryFields": [
"tasks"
],
"transitions": [
""
]
}
]
}
Show More
