projects/{projectId}/items/{itemId}/attachments
Adds an attachment to a submittal item within a project. This allows users to include relevant files as part of the submittal process.
There are two ways to attach files:
- Attach a local file – attach a file from your local machine.
- Attach an existing file from the Files tool – link a file already stored in the system.
To verify user permissions and required fields, call GET item/:id.
Note that for local attachments, you must confirm the attachment by calling PATCH attachments to finalize the upload.
For details about attaching local files, see the Attach Local File to Submittals tutorial.
For details about attaching exising files from the Files tool, see the Attach Files From the ACC Files Tool to Submittals tutorial.
For details about submittal attachments, see the Submittal Attachments Help documentation.
Resource Information
| Method and URI | POST https://developer.api.autodesk.com/construction/submittals/v2/projects/:projectId/items/:itemId/attachments |
| Authentication Context | user context required |
| Required OAuth Scopes | data:write |
| Data Format | JSON |
Request
Headers
| Authorization* string | Must be Bearer <token>, where <token> is obtained via a three-legged OAuth flow. |
| Content-Type* string | Must be application/json |
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. |
Request
Body Structure
| taskId string: UUID | The ID of the task within the review step that the attachment is associated with. The task ID identifies the specific task in the review process where the attachment belongs.
This field is only required when the submittal item is in the Review (``rev``) state. To retrieve the task ID, call Get tasks. |
| name* string | The user-defined name for the attachment. This value does not need to match the actual file name. For example, design-review.pdf or Design Review.
|
| isFileUploaded boolean | Specifies whether the attachment upload has been completed. This value controls how the system processes the attachment.
Behavior:
This field cannot be explicitly set to |
| urn string | The unique identifier for the file version in the Files tool. This field is required for referencing a specific file version when attaching a file from the Files tool.
This field is not applicable for local file uploads.
When attaching a file from the Files tool, both urn and urnTypeId must be provided. |
| urnTypeId* enum:string | Specifies the type of URN associated with the attachment.
Possible values: |
| categoryId enum:string | Specifies the workflow state of the submittal item associated with the attachment. If omitted, the system assigns one based on the current state.
Note that you can only set category IDs In some cases, you must manually set 1. Subcontractor Submissions:
When a subcontractor creates an item in the 2. Final Response in Non-Standard Closures:
When closing an item from a state other than Possible values:
To retrieve the list of available category ID values, call GET metadata and refer to the attachment categories list in the response. |
Response
HTTP Status Code Summary
| 201 Created | The attachment was successfully created. |
| 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 (201)
| id string: UUID | The internal, globally unique identifier (UUID) for the attachment. |
| itemId string: UUID | The ID of the submittal item associated with the attachment. |
| taskId string: UUID | The ID of the task within the review step to which the attachment is associated.
- If the attachment was added to a review step, this field contains the task ID that identifies the relevant task.
- If the attachment was not part of a review, this field is null. |
| name string | The user-defined name of the attachment. This value is specified when the attachment is created and may differ from the original file name. |
| isFileUploaded boolean | Indicates whether the attachment upload is complete.
|
| url string | Not relevant |
| asyncState enum:string | Represents the state of the asynchronous process triggered after marking the file upload as complete (isFileUploaded=true). The backend initiates this process to generate the URN for the attachment.
Possible values:
|
| uploadUrn string | The unique identifier for the upload session associated with the attachment applicable only to local file uploads. This value is used to generate a URL for uploading the actual file. |
| urn string | The unique identifier for a specific file version in the Files tool. |
| urnVersion int | The version number of the file in Autodesk Docs. |
| revisionFolderUrn string | Not relevant |
| revision int | Not relevant |
| urnTypeId enum:string | Specifies the type of urn associated with the attachment. This value identifies the storage type for the file reference.
Possible values: |
| categoryId enum:string | The workflow state of the submittal item associated with the attachment.
Possible values:
|
| urnPage string | Not relevant |
| resourceUrns string | Not relevant |
| createdBy string | The Autodesk ID of the user who created the attachment. |
| createdAt datetime: ISO 8601 | The date and time when the attachment created, in ISO 8601 format. For example, 2018-02-01T12:09:24.198466Z. |
| updatedAt datetime: ISO 8601 | The date and time the attachment was last updated, in ISO 8601 format. For example, 2018-02-01T12:09:24.198466Z. |
| updatedBy string | The Autodesk ID of the user who last updated the attachment. |
| duplicatedFrom string: UUID | The UUID of the source file the attachment was duplicated from. This indicates that the attachment was created as a copy of an existing file, preserving its metadata and association with the original file. |
| permittedActions array: object | A list of actions that the user is allowed to perform on the attachment. |
| id string | The ID of the action in the format type_of_object::action. For example, Attachment::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. The required fields depend on the user’s role and the action. |
| transitions array: string | Not relevant |
Example
The attachment was successfully created.
Request
curl -v 'https://developer.api.autodesk.com/construction/submittals/v2/projects/9eae7d59-1469-4389-bfb2-4114e2ba5545/items/767b5888-2c6a-413d-8487-613966dd64ce/attachments' \
-X 'POST' \
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a' \
-H 'Content-Type: application/json' \
-d '{
"taskId": "1ab2ae43-fb33-4868-be85-03f4873915fc",
"name": "attachment-document.pdf",
"isFileUploaded": "true",
"urn": "urn:adsk.wipprod:fs.file:vf.TQW6YsrTTFGrJVJKAaK_ew?version=1",
"urnTypeId": "2",
"categoryId": "1"
}'
Response
{
"id": "1d0a9b65-f411-4eb2-b6bb-69f8ea483207",
"itemId": "2df3b4cf-16f4-496e-8173-7125f31e3dd1",
"taskId": "1ab2ae43-fb33-4868-be85-03f4873915fc",
"name": "attachment-document.pdf",
"isFileUploaded": "true",
"url": null,
"asyncState": "1",
"uploadUrn": "urn:adsk.objects:os.object:wip.dm.prod/1a8148a6-d74e-4a6b-8cf2-38f2074f87d1.pdf",
"urn": "urn:adsk.wipprod:fs.file:vf.TQW6YsrTTFGrJVJKAaK_ew?version=1",
"urnVersion": 1,
"revisionFolderUrn": "urn:adsk.wipprod:fs.folder:co.3is_lyUzTxu6nNXobG2P7Q\"",
"revision": 0,
"urnTypeId": "2",
"categoryId": "1",
"urnPage": null,
"resourceUrns": null,
"createdBy": "WD43ZJGKDFLFH",
"createdAt": "2018-02-01T12:09:24.198466Z",
"updatedAt": "2018-02-01T12:09:24.198466Z",
"updatedBy": "WD43ZJGKDFLFH",
"duplicatedFrom": "f4635373-a5b4-456c-af8d-e0446652967c",
"permittedActions": [
{
"id": "Attachment::update",
"fields": {
"isFileUploaded": []
},
"mandatoryFields": [
"isFileUploaded"
],
"transitions": [
""
]
}
]
}
