Request

Response

    Issues
    POST

    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.

    1. Find the relevant container ID.
    2. Check you have permissions to add a reference by calling GET users/me using the container ID. Verify that the issues section includes the new object.
    3. Find the issue ID by calling GET issues.
    4. Upload the photo to BIM360 Docs using the Forge Data Management API.
    5. 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
    * Required

    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

    Expand all
    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: assign_all, assign_same_company, assign_creator_or_owner, clear_assignee, add_comment, add_attachment, remove_attachment.

    The following values are not relevant: add_attachment, remove_attachment.

    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
    * Required

    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)

    Expand all
    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: draft, open, work_completed, ready_to_inspect, in_dispute, not_approved, answered, void, closed.

    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: title, description, issueTypeId, issueSubtypeId, status, assignedTo, assignedToType, dueDate, locationId, locationDetails, linkedDocuments, links, ownerId, rootCauseId, officialResponse, customAttributes, clientUpdatedAt, snapshotUrn.

    permittedActions
    object
    The list of actions permitted for the user for this issue in its current state.

    Possible Values: assign_all, assign_same_company, assign_creator_or_owner, clear_assignee, add_comment, add_attachment, remove_attachment.

    The following values are not relevant: add_attachment, remove_attachment.

    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"
              }
            ]
          }'
    
    Show More

    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"
        }
      ]
    }
    
    Show More