containers/{containerId}/issues
Adds an issue to a project.
To verify whether a user can create issues for a specific project, call GET users/me and verify that the issues
section includes the new
object.
You can add attachments to issue, such as photos and documents.
- Find the relevant container ID.
- Check you have permissions to add a reference by calling GET users/me using the container ID. Verify that the
issues
section includes thenew
object. - Find the issue ID by calling GET issues.
- Upload the photo to BIM360 Docs using the Forge Data Management API.
- Use the Relationships API to add the file (photo) to the issue.
Note that this endpoint is ONLY compatible with BIM 360 projects. It is not compatible with Autodesk Construction Cloud (ACC) projects. For more information about compatibility between between BIM 360 and ACC, see the Compatibility section.
Resource Information
Method and URI | POST https://developer.api.autodesk.com/issues/v2/containers/:containerId/issues |
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
containerId string | The ID of the container.
Each project is assigned to a container that stores all the issues for the project. Use the Data Management API to retrieve the container ID. For more information, see the Retrieve Issues Container ID tutorial. |
Request
Body Structure
The payload for creating a new issue
status* enum:string | The unique identifier of the current status of the issue
Possible values: draft , open , work_completed , ready_to_inspect , in_dispute , not_approved , answered , void , closed |
linkedDocuments array: object | The list of files/documents related to this issue with specific details depending on the type of relationship. Currently linkedDocuments can contain only one item at maximum. |
type* enum:string | The type of the relationship
Possible values: TwoDVectorPushpin , TwoDRasterPushpin |
urn* string | The URN of the file/document that a pushpin was placed on for this issue |
createdBy string | The unique identifier of the user who created the pushpin |
createdAt datetime: ISO 8601 | The date and time the pushpin was created, in ISO8601 format |
createdAtVersion* int | The URN version of the file/document when the issue was created |
closedBy string | The unique identifier of the user who closed the pushpin |
closedAt datetime: ISO 8601 | The date and time the pushpin was closed, in ISO8601 format |
closedAtVersion int | The version URN of the file/document when the issue was closed |
details* object | The information about the individual viewable, the pushpin position in the viewable, the ID of the element the pushpin is associated with and the viewer state at creation time |
viewable object | The individual viewable (sheet / 3D view) a pushpin was placed on. Applicable only if URN points to a file (as opposed to a document) |
id string | The unique identifier of the viewable (This field has been depreciated, use guid instead) |
name* string | The name of the viewable
Max length: 1000 |
is3D* boolean | The flag indicates if it’s a 2D or 3D viewable |
guid string | The unique identifier of the viewable (UUID) |
viewableId string | The identifier of the viewable (String) |
position* object | The position of the pushpin in the viewable |
x* number | The x-value of the position in the viewable |
y* number | The y-value of the position in the viewable |
z number | The z-value of the position in the viewable. For a 2D view this value is not set |
objectId int | The unique identifier of the element the pushpin is associated with in the viewable |
externalId string | An external identifier of the element the pushpin is associated with in the viewable |
viewerState object | The viewer state at the time the pushpin was created max length of 2,500,000 charecters. You can get the viewer state object by calling the ViewerState.getState() API. To restore the viewer instance use ViewerState.restoreState(). See Viewer API documentation here https://developer.autodesk.com/en/docs/viewer/v2/reference/javascript/viewerstate/ |
id string: UUID | The unique identifier of the issue. |
title* string | The title of the issue.
Max length: 4200 |
description string | The description and purpose of the issue.
Max length: 10000 |
snapshotUrn string | Not relevant |
issueSubtypeId* string: UUID | The unique identifier of the subtype of the issue. |
assignedTo string | The unique Autodesk ID of the User/Company/Role of the current assignee for this issue. Note that if you select an assignee ID, you also need to select a type (assignedToType ). |
assignedToType enum:string | The type of the current assignee of this issue. Possible values: user , company , role , null . |
dueDate string | The due date of the issue, in ISO8601 format. |
locationId string: UUID | The unique LBS (Location Breakdown Structure) identifier that relates to the issue. |
locationDetails string | The location as plain text that relates to the issue.
Max length: 8300 |
links array: object | A collection of links to checklists. For example, a list of resource URN’s in the Checklist service that this issue is related to.
To filter by links use the filter[qualityUrns]. Hint, currently links can contain only one item at maximum. |
type* enum:string | The type of the entity link Will always be: checklist |
data* object | A custom object describing the entity link data |
** string | |
ownerId string | The unique identifier of the user who owns this issue. Used in case this issue was created on-behalf of another person
Max length: 100 |
rootCauseId string: UUID | The unique identifier of the type of root cause for the issue. |
issueTemplateId string: UUID | Not relevant |
permittedActions object | The list of actions permitted for the user for this issue in its current state.
Possible Values: The following values are not relevant: |
clientCreatedAt datetime: ISO 8601 | Not relevant |
customAttributes array: object | A list of custom attributes of the specific issue. |
attributeDefinitionId* string: UUID | |
value* object | Custom attributes value. in case of a list option, the id of the selected option, otherwise can be string/text/date/boolean |
Response
HTTP Status Code Summary
201 Created | Returns the created issue |
400 Bad Request | The request could not be understood by the server due to malformed syntax or missing request headers. The client SHOULD NOT repeat the request without modifications. The response body may give an indication of what is wrong with the request |
401 Unauthorized | The supplied Authorization header was not valid. Verify Authentication and try again |
403 Forbidden | The request was successfully validated but permission is not granted |
409 Conflict | The request contained a data conflict |
Response
Body Structure (201)
id string: UUID | The unique identifier of the issue. |
containerId string: UUID | The unique identifier of the container issue is part of |
displayId int | The chronological user-friendly identifier of the issue |
title string | The title of the issue.
Max length: 4200 |
description string | The description and purpose of the issue.
Max length: 10000 |
snapshotUrn string | Not relevant |
snapshotWipUrn string | Not relevant |
issueTypeId string: UUID | The unique identifier of the type of the issue. |
issueSubtypeId string: UUID | The unique identifier of the subtype of the issue. |
status enum:string | The unique identifier of the current status of the issue
Possible values: draft , open , work_completed , ready_to_inspect , in_dispute , not_approved , answered , void , closed |
assignedTo string | The unique Autodesk ID of the User/Company/Role of the current assignee for this issue. Note that if you select an assignee ID, you also need to select a type (assignedToType ). |
assignedToType enum:string | The type of the current assignee of this issue. Possible values: user , company , role , null . |
dueDate string | The due date of the issue, in ISO8601 format. |
locationId string: UUID | The unique LBS (Location Breakdown Structure) identifier that relates to the issue. |
locationDetails string | The location as plain text that relates to the issue.
Max length: 8300 |
linkedDocuments array: object | The list of files/documents related to this issue with specific details depending on the type of relationship. Currently linkedDocuments can contain only one item at maximum. |
type enum:string | The type of the relationship
Possible values: TwoDVectorPushpin , TwoDRasterPushpin |
urn string | The URN of the file/document that a pushpin was placed on for this issue |
createdBy string | The unique identifier of the user who created the pushpin |
createdAt datetime: ISO 8601 | The date and time the pushpin was created, in ISO8601 format |
createdAtVersion int | The URN version of the file/document when the issue was created |
closedBy string | The unique identifier of the user who closed the pushpin |
closedAt datetime: ISO 8601 | The date and time the pushpin was closed, in ISO8601 format |
closedAtVersion int | The version URN of the file/document when the issue was closed |
details object | The information about the individual viewable, the pushpin position in the viewable, the ID of the element the pushpin is associated with and the viewer state at creation time |
viewable object | The individual viewable (sheet / 3D view) a pushpin was placed on. Applicable only if URN points to a file (as opposed to a document) |
id string | The unique identifier of the viewable (This field has been depreciated, use guid instead) |
name string | The name of the viewable
Max length: 1000 |
is3D boolean | The flag indicates if it’s a 2D or 3D viewable |
guid string | The unique identifier of the viewable (UUID) |
viewableId string | The identifier of the viewable (String) |
position object | The position of the pushpin in the viewable |
x number | The x-value of the position in the viewable |
y number | The y-value of the position in the viewable |
z number | The z-value of the position in the viewable. For a 2D view this value is not set |
objectId int | The unique identifier of the element the pushpin is associated with in the viewable |
externalId string | An external identifier of the element the pushpin is associated with in the viewable |
viewerState object | The viewer state at the time the pushpin was created max length of 2,500,000 charecters. You can get the viewer state object by calling the ViewerState.getState() API. To restore the viewer instance use ViewerState.restoreState(). See Viewer API documentation here https://developer.autodesk.com/en/docs/viewer/v2/reference/javascript/viewerstate/ |
links array: object | A collection of links to checklists. For example, a list of resource URN’s in the Checklist service that this issue is related to.
To filter by links use the filter[qualityUrns]. Hint, currently links can contain only one item at maximum. |
type enum:string | The type of the entity link Will always be: checklist |
data object | A custom object describing the entity link data |
* string | |
ownerId string | The unique identifier of the user who owns this issue. Used in case this issue was created on-behalf of another person
Max length: 100 |
rootCauseId string: UUID | The unique identifier of the type of root cause for the issue. |
officialResponse object | The official response of the user for the issue |
response string | The suggested response of the user
Max length: 1900 |
respondedAt datetime: ISO 8601 | The date and time the issue was responded, in ISO8601 format |
respondedBy string | The unique identifier of the user that suggested a response for the issue |
issueTemplateId string: UUID | Not relevant |
permittedStatuses array: string | A list of statuses accessible to the current user, this is based on the current status of the issue and the user permissions.
Possible Values: |
permittedAttributes array: string | A list of attributes the current user can manipulate in the current context. issueTypeId , linkedDocument , links , ownerId , officialResponse , rootCauseId , snapshotUrn are not applicable.
Possible Values: |
permittedActions object | The list of actions permitted for the user for this issue in its current state.
Possible Values: The following values are not relevant: |
commentCount int | The number of comments in this issue. |
attachmentCount int | The number of attachments added to this issue |
openedBy string | The unique identifier of the user who opened the issue. |
openedAt datetime: ISO 8601 | The date and time the issue was opened, in ISO8601 format. |
closedBy string | The unique identifier of the user who closed the issue. |
closedAt datetime: ISO 8601 | The date and time the issue was closed, in ISO8601 format. |
createdBy string | The unique identifier of the user who created the issue. |
createdAt datetime: ISO 8601 | The date and time the issue was created, in ISO8601 format. |
updatedBy string | The unique identifier of the user who updated the issue. |
updatedAt datetime: ISO 8601 | The date and time the issue was updated, in ISO8601 format. |
clientCreatedAt datetime: ISO 8601 | Not relevant |
clientUpdatedAt datetime: ISO 8601 | Not relevant |
customAttributes array: object | A list of custom attributes of the specific issue. |
attributeDefinitionId string: UUID | |
value object | Custom attributes value. in case of a list option, the id of the selected option, otherwise can be string/text/date/boolean |
type enum:string | Type of the attribute: value should of the corresponding format
Possible values: numeric , paragraph , list , text |
title object | Free text description of the attribute |
Example
Returns the created issue
Request
curl -v 'https://developer.api.autodesk.com/issues/v2/containers/a5f49f04-59bb-477c-97e6-6833cb50bdac/issues' \
-X 'POST' \
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a' \
-H 'Content-Type: application/json' \
-d '{
"status": "open",
"linkedDocuments": [
{
"type": "TwoDVectorPushpin",
"urn": "urn:adsk.wipprod:dm.lineage:0C9edNQuT2SrfoyKQ1Gv_Q",
"createdBy": "",
"createdAt": "",
"createdAtVersion": 1,
"closedBy": "",
"closedAt": "",
"closedAtVersion": 1,
"details": {
"viewable": {
"id": "",
"name": "",
"is3D": "",
"guid": "",
"viewableId": ""
},
"position": {
"x": "",
"y": "",
"z": ""
},
"objectId": "",
"externalId": "",
"viewerState": {}
}
}
],
"id": "3570f222-6c54-4b01-90e6-e701749f0222",
"title": "Door missing a screw",
"description": "The door is missing a screw, please fix this",
"snapshotUrn": "",
"issueSubtypeId": "1370f222-6c54-3a01-93e6-e701749f0222",
"assignedTo": "A3RGM375QTZ7",
"assignedToType": "user",
"dueDate": "2018-07-25",
"locationId": "35de6f24-39f5-4808-ba5f-6cbbe2a858e1",
"locationDetails": "issue location details",
"links": [
{
"type": "checklist",
"data": {
"urn1": "urn:adsk.checklists.cs.instance:f0aa1265-ecf1-4fe6-b192-dcebf34be020/505",
"urn2": "urn:adsk.checklists.cs.instance:f0aa1265-ecf1-4fe6-b192-dcebf34be021/506"
}
}
],
"ownerId": "owner Id",
"rootCauseId": "2370f222-6c54-3a01-93e6-f701772f0222",
"issueTemplateId": "",
"permittedActions": {},
"clientCreatedAt": "2000-02-04T09:44:58.867Z",
"customAttributes": [
{
"attributeDefinitionId": "2220f222-6c54-4b01-90e6-d701748f0888",
"value": "fast"
}
]
}'
Response
{
"id": "3570f222-6c54-4b01-90e6-e701749f0222",
"containerId": "2220f222-6c54-4b01-90e6-d701748f0222",
"displayId": 7,
"title": "Door missing a screw",
"description": "The door is missing a screw, please fix this",
"snapshotUrn": "",
"snapshotWipUrn": "",
"issueTypeId": "8770f222-6c54-4e01-93e6-e701749f0222",
"issueSubtypeId": "1370f222-6c54-3a01-93e6-e701749f0222",
"status": "open",
"assignedTo": "A3RGM375QTZ7",
"assignedToType": "user",
"dueDate": "2018-07-25",
"locationId": "35de6f24-39f5-4808-ba5f-6cbbe2a858e1",
"locationDetails": "issue location details",
"linkedDocuments": [
{
"type": "TwoDVectorPushpin",
"urn": "urn:adsk.wipprod:dm.lineage:0C9edNQuT2SrfoyKQ1Gv_Q",
"createdBy": "",
"createdAt": "",
"createdAtVersion": 1,
"closedBy": "",
"closedAt": "",
"closedAtVersion": 1,
"details": {
"viewable": {
"id": "",
"name": "",
"is3D": "",
"guid": "",
"viewableId": ""
},
"position": {
"x": "",
"y": "",
"z": ""
},
"objectId": "",
"externalId": "",
"viewerState": {}
}
}
],
"links": [
{
"type": "checklist",
"data": {
"urn1": "urn:adsk.checklists.cs.instance:f0aa1265-ecf1-4fe6-b192-dcebf34be020/505",
"urn2": "urn:adsk.checklists.cs.instance:f0aa1265-ecf1-4fe6-b192-dcebf34be021/506"
}
}
],
"ownerId": "owner Id",
"rootCauseId": "2370f222-6c54-3a01-93e6-f701772f0222",
"officialResponse": {
"response": "",
"respondedAt": "",
"respondedBy": ""
},
"issueTemplateId": "",
"permittedStatuses": [
"open"
],
"permittedAttributes": [
"title"
],
"permittedActions": {},
"commentCount": 3,
"attachmentCount": "",
"openedBy": "A3RGM375QTZ7",
"openedAt": "2018-07-22T15:05:58.033Z",
"closedBy": "A3RGM375QTZ7",
"closedAt": "2018-07-22T15:05:58.033Z",
"createdBy": "A3RGM375QTZ7",
"createdAt": "2018-07-22T15:05:58.033Z",
"updatedBy": "A3RGM375QTZ7",
"updatedAt": "2018-07-22T15:05:58.033Z",
"clientCreatedAt": "2000-02-04T09:44:58.867Z",
"clientUpdatedAt": "2000-02-04T09:44:58.867Z",
"customAttributes": [
{
"attributeDefinitionId": "2220f222-6c54-4b01-90e6-d701748f0888",
"value": "fast",
"type": "numeric",
"title": "Secondary Title"
}
]
}