> This page is for version v2 (default). > For other versions, use one of these documentation indexes: > - v2 (default): https://autodesk-poc.ferndocs.com/v2/llms.txt > - v1: https://autodesk-poc.ferndocs.com/v1/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://autodesk-poc.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://autodesk-poc.ferndocs.com/_mcp/server. # Add References To Issues This tutorial demonstrates how to add references such as Forma photos to Forma issues. The steps include verifying the user’s permissions, finding the ID of the references (in this example, the photo) you want to add to the issue, and using the Relationships API to add it to the issue. ## Before You Begin * [Register an app](https://aps.autodesk.com/myapps) * Acquire a [3-legged OAuth token](https://aps.autodesk.com/en/docs/oauth/v2/tutorials/get-3-legged-token/) with the `data:write` scope. * Verify that you have access to the relevant hub and Forma project. * Find the relevant project ID for the project you want to create an issue in by following the [Retrieve Forma Hub and Project ID](https://aps.autodesk.com/en/docs/acc/v1/tutorials/getting-started/retrieve-account-and-project-id/) tutorial. In this example, assume the project ID is `f6a1e3b5-abaa-4b01-b33a-5d55f36ba047`. Note that we do not currently support document-related (pusphin) issues or linked documents. ## Step 1: Verify the User’s Permissions We recommend that you call [GET users/me](https://aps.autodesk.com/en/docs/acc/v1/reference/http/issues-users-me-GET/) to verify that the user has permissions to add photos to issues. The user can add photos if the `issues.new` object appears in the response. See the [Permissions Table](https://help.autodesk.com/view/BUILD/ENU/?guid=Issues_Permissions) for more information about permissions. ### Request ```bash curl -v 'https://developer.api.autodesk.com/construction/issues/v1/projects/f6a1e3b5-abaa-4b01-b33a-5d55f36ba047/users/me' \ -H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a' ``` ### Response ```json { "id": "BXQXL7646C2R", "isProjectAdmin": true, "canManageTemplates": "", "issues": { "new": { "permittedActions": [ "add_comment" ], "permittedAttributes": [ "title" ], "permittedStatuses": [ "open" ], "permitted_actions": [ "add_comment" ], "permitted_attributes": [ "title" ], "permitted_statuses": [ "open" ] } }, "permissionLevels": [ "read", "write", "create" ] } ``` The user can add photos to issues if the `issues.new` object appears in the response. The user has `manage issues` permissions if `create`, `write`, `read` appears in the `permissionLevels` array. For more details about permission levels, see [Issues Permissions](https://help.autodesk.com/view/BUILD/ENU/?guid=Issues_Permissions). ## Step 2: Find the Issue ID To find the issue ID of the issue you want to add the photo to, call [\`GET issues /en/docs/acc/v1/reference/http/issues-issues-GET/\`\_](https://aps.autodesk.com/en/docs/acc/v1/tutorials/issues/add-references-to-issues/#id7) using the project ID (`f6a1e3b5-abaa-4b01-b33a-5d55f36ba047`). ### Request ```bash curl -v 'https://developer.api.autodesk.com/construction/issues/v1/projects/f6a1e3b5-abaa-4b01-b33a-5d55f36ba047/issues' \ -H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a' ``` ### Response ```json { "pagination": { "limit": 10, "offset": 100, "totalResults": 25 }, "results": [ { "id": "3570f222-6c54-4b01-90e6-e701749f0222", "containerId": "2220f222-6c54-4b01-90e6-d701748f0222", "deleted": false, "displayId": 7, "title": "Door missing a screw", "description": "The door is missing a screw, please fix this", "snapshotUrn": "", "issueTypeId": "8770f222-6c54-4e01-93e6-e701749f0222", "issueSubtypeId": "1370f222-6c54-3a01-93e6-e701749f0222", "status": "open", "assignedTo": "A3RGM375QTZ7", "assignedToType": "user", "dueDate": "2018-07-25", "startDate": "1982-06-01", "locationId": "35de6f24-39f5-4808-ba5f-6cbbe2a858e1", "locationDetails": "issue location details", "linkedDocuments": [ {} ], "links": [ {} ], "ownerId": "", "rootCauseId": "2370f222-6c54-3a01-93e6-f701772f0222", "officialResponse": {}, "issueTemplateId": "", "permittedStatuses": [ "open" ], "permittedAttributes": [ "title" ], "published": true, "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", "watchers": [ "A3RGM375QTZ7" ], "customAttributes": [ { "attributeDefinitionId": "2220f222-6c54-4b01-90e6-d701748f0888", "value": "368", "type": "numeric", "title": "Cost Impact ($)" } ] } ] } ``` Note the ID (`results.[id]`) - (`3570f222-6c54-4b01-90e6-e701749f0222`) of the issue you want to add the photo to. ## Step 3: Find the Reference (Photo) ID To find the ID of the photo you want to add to the issue, call [GET photos](https://aps.autodesk.com/en/docs/acc/v1/reference/http/photos-getfilteredphotos-POST/) using the project ID (`f6a1e3b5-abaa-4b01-b33a-5d55f36ba047`) to get a list of all the photos for the project. Note you cannot currently upload photos to the Forma Photo tool using the Photos API. You can only upload photos via the Photos UI. We will be supporting the photos API upload in the near future. As a workaround you can upload photos to the Forma Files tool using the [Data Management API](https://aps.autodesk.com/en/docs/data/v2/developers_guide/overview/) and add a file reference to the issue. See the [Upload Files](https://aps.autodesk.com/en/docs/acc/v1/tutorials/document-management/upload-document/) tutorial for details. ### Request ```bash curl -v 'https://developer.api.autodesk.com/construction/photos/projects/f6a1e3b5-abaa-4b01-b33a-5d55f36ba047/photos:filter' \ -X 'POST' \ -H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a' \ -H 'Content-Type: application/json' \ ``` ### Response ```json { "pagination": { "limit": 25, "nextPost": { "body": { "cursorState": "eyJsaW1pdCI6MjUsICJ0aXRsZSI6ICJ3YWxsIn0Ks" }, "url": "https://developer.api.autodesk.com/construction/photos/v1/projects/8e52b200-f856-4f17-a57c-c03ba2f6673a/photos:filter" } }, "results": [ { "createdAt": "2021-03-14T10:20:33", "createdBy": "PER8KQPK2JRT", "deletedAt": "2021-03-19T11:50:33", "deletedBy": "PER8KQPK2JRT", "description": "The left side of the office", "id": "5439bfb7-8006-4388-a454-f02560f99566", "isPublic": false, "latitude": 37.757497, "locked": false, "longitude": -122.42115, "mediaType": "NORMAL", "projectId": "f6a1e3b5-abaa-4b01-b33a-5d55f36ba047", "signedUrls": { "fileUrl": "https://s3.amazonaws.com/com.autodesk.oss-persistent/f0/7b/66/4df1b73d0cc643e6179b85eae7d8d529d2/ce8edd30-ef28-467c-8d99-7d7051097ee0?response-content-disposition=attachment%3B%20filename%3D%22c35b8b28-859e-4256-a3bc-41772a673260.jpg%22&response-content-type=image%2Fjpeg&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEKP%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJHMEUCIQCOKZyru7bEOWhRlJOiFZUwLwGSFSWPO5VknX%2BIisldAwIgWN6g5zYxXLOzdiZgR4sYuyY4qr1k1SAQOTOCI7EOmKIqvQMI3P%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARAAGgw5OTM3ODk5OTIwNjMiDK0wr6QcJBV%2BrqLz7iqRA55WGaeF1IZVyH5XzR%2FyR72VqyCRIEwm9D3Pt%2BTOxtaNa519ldQcvjYptWrlwnrgr1T9c3jxtEXxHZveX3XwgaSQq7JyHACBAMVwkKABwczEzPOryCvIJBWjgr2ABoYGr0dDCFdh9IjdoDrOrXDDesn4I5GamK%2BdNzXBR1MJH3ocmoZXxrmaJGigr62ShQ3q7AoqMgIX55XH8DnYMP4k9OlGGJsL7P80OnvOXfNLFl9EVJp5jnp%2BT1eO3FezRxc%2FqkeTG7t6QHh87P4cJKzWV9pW3AQoYvBKyQ5uJn5WA8%2FFg%2BhzYalr5Y%2B4%2FneB0xfn7WS2I%2FvjIo6rOkIqx7K3Ty1p1kuZ6e64%2BlEXx8mYHO2NOYobbSf%2Fx%2B7FU1rhZqvqUGB%2BRoMXFI%2FIkaxe%2B%2Ba6sZYV6Dm6bcim835asw%2B48vkt3XLZ6kBNqOJMdqvIBp%2F7opV9Bc4%2BMkhPc6wT%2BwAoQ0jHGuNZiLh%2BsxcB8EtwziI18v5LFw6WmffTQD3oc8WTb9xUZmoQ8qDq5z%2FY4%2BY2EAq6MNaP7oIGOusBXz4xrUPPH0cr5UO912gp6aysXFnqxu55it8zqPwiGI2Xe0RlaMTAMh1jwDZ4LZD4N2NERk%2F%2BlR1KaRk2Jvo34HIXVnUqNWlYAR3TyV2intl8wwJWlgKQH6DI%2BzwOJ27kDToULG5TQpQk6xAQaToplmERCien7Pi8vlb0JNBCzkoKNh40Z1wPxcS%2BitdU0IkD0n39bvWy5uG0hoUuifHr53vaf7eqFRSdrd%2B%2BYuJ00yT%2FtWS6FLpLKCSgZw8GKoAq3PpfPggmg99bAju7H%2FD8xfVgBPhb91tEGCCdyub4jDtj6euoUFXK%2FiMIVg%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210324T193346Z&X-Amz-SignedHeaders=host&X-Amz-Expires=60&X-Amz-Credential=ASIA6OYT73R75HNE4VUO%2F20210324%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=e694954290d485482c6334b39b591c87e4a16ba2425f05da1dc25faf47afba2d", "thumbnailUrl": "https://s3.amazonaws.com/com.autodesk.oss-opsstaging-persistent/81/b8/3d/e2855b46af2060d595ce31923310079c4b/ce8edd30-ef28-467c-8d99-7d7051097ee0?response-content-disposition=attachment%3B%20filename%3D%22c35b8b28-859e-4256-a3bc-41772a673260_t.jpg%22&response-content-type=image%2Fjpeg&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEKP%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJHMEUCIQCOKZyru7bEOWhRlJOiFZUwLwGSFSWPO5VknX%2BIisldAwIgWN6g5zYxXLOzdiZgR4sYuyY4qr1k1SAQOTOCI7EOmKIqvQMI3P%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARAAGgw5OTM3ODk5OTIwNjMiDK0wr6QcJBV%2BrqLz7iqRA55WGaeF1IZVyH5XzR%2FyR72VqyCRIEwm9D3Pt%2BTOxtaNa519ldQcvjYptWrlwnrgr1T9c3jxtEXxHZveX3XwgaSQq7JyHACBAMVwkKABwczEzPOryCvIJBWjgr2ABoYGr0dDCFdh9IjdoDrOrXDDesn4I5GamK%2BdNzXBR1MJH3ocmoZXxrmaJGigr62ShQ3q7AoqMgIX55XH8DnYMP4k9OlGGJsL7P80OnvOXfNLFl9EVJp5jnp%2BT1eO3FezRxc%2FqkeTG7t6QHh87P4cJKzWV9pW3AQoYvBKyQ5uJn5WA8%2FFg%2BhzYalr5Y%2B4%2FneB0xfn7WS2I%2FvjIo6rOkIqx7K3Ty1p1kuZ6e64%2BlEXx8mYHO2NOYobbSf%2Fx%2B7FU1rhZqvqUGB%2BRoMXFI%2FIkaxe%2B%2Ba6sZYV6Dm6bcim835asw%2B48vkt3XLZ6kBNqOJMdqvIBp%2F7opV9Bc4%2BMkhPc6wT%2BwAoQ0jHGuNZiLh%2BsxcB8EtwziI18v5LFw6WmffTQD3oc8WTb9xUZmoQ8qDq5z%2FY4%2BY2EAq6MNaP7oIGOusBXz4xrUPPH0cr5UO912gp6aysXFnqxu55it8zqPwiGI2Xe0RlaMTAMh1jwDZ4LZD4N2NERk%2F%2BlR1KaRk2Jvo34HIXVnUqNWlYAR3TyV2intl8wwJWlgKQH6DI%2BzwOJ27kDToULG5TQpQk6xAQaToplmERCien7Pi8vlb0JNBCzkoKNh40Z1wPxcS%2BitdU0IkD0n39bvWy5uG0hoUuifHr53vaf7eqFRSdrd%2B%2BYuJ00yT%2FtWS6FLpLKCSgZw8GKoAq3PpfPggmg99bAju7H%2FD8xfVgBPhb91tEGCCdyub4jDtj6euoUFXK%2FiMIVg%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210324T193346Z&X-Amz-SignedHeaders=host&X-Amz-Expires=60&X-Amz-Credential=ASIA6OYT73R75HNE4VUO%2F20210324%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=fac56130302305057c9ae301503860edb2d296c43dcfb5a59ebf3744f5126baa" }, "size": 11359, "takenAt": "2021-03-13T18:15:00", "title": "Office Dry Wall", "type": "FIELD-REPORT", "updatedAt": "2021-03-14T11:20:33", "updatedBy": "PER8KQPK2JRT", "urls": { "fileUrl": "https://developer.api.autodesk.com/construction/photos/assets/ce8edd30-ef28-467c-8d99-7d7051097ee0/c35b8b28-859e-4256-a3bc-41772a673260.jpg\"", "thumbnailUrl": "https://developer.api.autodesk.com/construction/photos/assets/ce8edd30-ef28-467c-8d99-7d7051097ee0/c35b8b28-859e-4256-a3bc-41772a673260_t.jpg\"" }, "userCreatedAt": "2021-03-13T18:20:33" } ] } ``` Note the ID (`results.[id]`) - (`5439bfb7-8006-4388-a454-f02560f99566`) of the photo you want to add to the issue. If you want to add a new photo to the issue, upload the photo to Forma Data Management using the Data Management API. See the [Upload Files](https://aps.autodesk.com/en/docs/acc/v1/tutorials/document-management/upload-document/) tutorial for details. Note the item ID (`included.[id]`) in the response. ## Step 4: Add the Reference (Photo) to the Issue Use the [Relationships API](https://aps.autodesk.com/en/docs/acc/v1/reference/http/relationship-service-v2-add-relationships-PUT/) to add the photo to the issue. Call [PUT relationships](https://aps.autodesk.com/en/docs/acc/v1/reference/http/relationship-service-v2-add-relationships-PUT/) using the project ID (`f6a1e3b5-abaa-4b01-b33a-5d55f36ba047`), the photo ID (`5439bfb7-8006-4388-a454-f02560f99566`), and the issue ID (`3570f222-6c54-4b01-90e6-e701749f0222`). If you uploaded the photo via the Photos UI, use the following types and domains: For the issue: use an `issue` type, and an `autodesk-bim360-issue` domain. For the photo: use a `photo` type, and an `autodesk-contruction-photo` domain. If you uploaded the photo to Forma Files using the Data Management API, use the following types and domains: For the issue: use an `issue` type, and an `autodesk-bim360-issue` domain. (Note that the issues API currently uses the `autodesk-bim360-issue` domain for both for both Forma and BIM 360 relationships.) For the file: use a `documentlineage` type, and an `autodesk-bim360-documentmanagement` domain. Note that container ID in the relationships ID is equivalent to the project ID. ### Request ```bash curl -v 'https://developer.api.autodesk.com/bim360/relationship/v2/containers/f6a1e3b5-abaa-4b01-b33a-5d55f36ba047/relationships' \ -X PUT \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '[ { "entities": [ { "domain": "autodesk-bim360-issue", "type": "issue", "id": "3570f222-6c54-4b01-90e6-e701749f0222", "createdOn": "2021-07-29T11:39:12+01:00" }, { "domain": "autodesk-construction-photo", "type": "photo", "id": "5439bfb7-8006-4388-a454-f02560f99566", "createdOn": "2021-07-29T13:39:12+01:00" } ] } ]' ``` ### Response (200) ```json [ { "id": "74b70bb8-8802-a1fd-f201-890375a60c8f", "createdOn": "2015-10-21T16:32:22Z", "isReadOnly": true, "isService": false, "isDeleted": false, "entities": [ { "domain": "autodesk-bim360-issue", "type": "issue", "id": "3570f222-6c54-4b01-90e6-e701749f0222", "createdOn": "2021-07-29T11:39:12+01:00" }, { "domain": "autodesk-construction-photo", "type": "photo", "id": "5439bfb7-8006-4388-a454-f02560f99566", "createdOn": "2021-07-29T13:39:12+01:00" } ] } ] ``` Congratulations! You have added a photo to a Forma issue. --- *Imported from the Autodesk Platform Services documentation: [https://aps.autodesk.com/en/docs/acc/v1/tutorials/issues/add-references-to-issues](https://aps.autodesk.com/en/docs/acc/v1/tutorials/issues/add-references-to-issues).*