Attach images and notes

In this tutorial, you learn how to associate supplemental items such as a receipt image, product photo, or a note to an existing transaction or Item object. In QuickBooks Online, these supplemental items are called attachments.

Attachments are kept in a repository called the attachment list. This list is managed from both the QuickBooks Online user interface (via the Attachments List page) and the QuickBooks Online API (via the Upload and Download resources). Each attachment has metadata associated with it, including information about its relationship to transaction or Item objects. Use the Attachable resource to manage metadata.

There are two types of attachments.

To follow along, you’ll need a sandbox or another QuickBooks company populated with a chart of accounts, customers, and items. The examples in this tutorial use the sandbox company.

Attaching a note to an object

Operation: POST https://QuickBooks.API.intuit.com/v3/company/<realmId>/attachable
Content type: application/json

Request body

Here is a sample request body that adds a note to an Invoice. The value attribute of the EntityRef below is the Id of the Invoice object retrieved from a previous fetch of the Invoice object.

1
2
3
4
5
6
7
8
9
 {
   "AttachableRef": [{
      "EntityRef": {
          "type": "Invoice",
          "value": "95"
      }
   }],
   "Note":"This is a note added to the invoice."
 }

Response body

An Attachable object is returned confirming that the note is now attached to the invoice.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
   "Attachable": {
      "Note": "This is a note added to the invoice.",
      "domain": "QBO",
      "sparse": false,
      "Id": "100000000004191632",
      "SyncToken": "0",
      "MetaData": {
         "CreateTime": "2015-11-16T11:43:06-08:00",
         "LastUpdatedTime": "2015-11-16T11:43:06-08:00"
      },
      "AttachableRef": [{
         "EntityRef": {
            "value": "95",
            "type": "Invoice"
         },
         "IncludeOnSend": false
      }]
   },
   "time": "2015-11-16T11:43:06.064-08:00"
}

Attaching a file to an object

To attach a file to an existing object such as a supporting receipt to an invoice object or a photo to an item object, use the Attachable resource to link it to the object.

Note

Note

  • The attachment/object relationship is established with the Attachable object, only; the object does not include a link back to the attachment.
  • The object must already exist in order to add an attachment to it.

Uploading and linking new attachments

If the attachment is not in the Attachment list already, it’s possible to upload it and link it to the object in one multipart operation.

Operation: POST https://QuickBooks.API.intuit.com/v3/company/<realmId>/upload
Content type: multipart/form-data

Request body

The following sample code shows the multipart request body for uploading a file and its supporting Attachable metatdata object, with the result of it being both added to the Attachment list and added to the object.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
--YOjcLaTlykb6OxfYJx4O07j1MweeMFem
Content-Disposition: form-data; name="file_metadata_01"; filename="attachment.json"
Content-Type: application/json
{
   "AttachableRef": [
   {
      "EntityRef": {
        "type": "Invoice",
        "value": "95"
      }
   }
   ],
   "FileName": "receipt_nov15.jpg",
   "ContentType": "image/jpg"
}
--YOjcLaTlykb6OxfYJx4O07j1MweeMFem
Content-Disposition: form-data; name="file_content_01"; filename="receipt_nov15.jpg"
Content-Type: image/jpeg
<insert base-64 encoded file content here>
--YOjcLaTlykb6OxfYJx4O07j1MweeMFem​--

Response body

An Attachable object is returned confirming that the file is now attached to the invoice.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
   "AttachableResponse": [
      {
         "Attachable": {
            "FileName": "receipt_nov15.jpg",
            "FileAccessUri": "...",
            "TempDownloadUri": "https://...",
            "Size": 1594261,
            "ContentType": "image/jpeg",
            "ThumbnailFileAccessUri": "...",
            "domain": "QBO",
            "sparse": false,
            "Id": "100000000004190865",
            "SyncToken": "0",
            "MetaData": {
             "CreateTime": "2015-11-16T10:59:02-08:00",
             "LastUpdatedTime": "2015-11-16T10:59:02-08:00"
            },
            "AttachableRef": [
             {
                "EntityRef": {
                   "value": "95",
                   "type": "Invoice"
                },
                "IncludeOnSend": false
             }
            ]
         }
      }
   ],
   "time": "2015-11-16T10:58:58.100-08:00"
}

Linking existing attachments

Operation: POST https://QuickBooks.API.intuit.com/v3/company/<realmId>/attachable
Content type: application/json

Request body

The sample request below shows how to link an existing attachment already in the Attachment list to an object, in this case an invoice.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
   "AttachableRef": [
      {
         "EntityRef": {
            "type": "Invoice",
            "value": "95"
      }
      }
   ],
 "FileName": "receipt_june10.pdf"
   }

Response body

The result is the AttachableRef element of the existing Attachable object links a receipt already in the Attachments list to an Invoice object whose internal Id is 754, as shown in this image. Some field values have been abbreviated.

qbo/docs/develop/tutorials/InvoiceAttachment.png

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
   "Attachable": {
     "FileName": "receipt_june10.pdf",
     "FileAccessUri": "...",
     "TempDownloadUri": "...",
     "Size": 1594261,
     "ContentType": "image/pdf",
     "ThumbnailFileAccessUri": "...",
     "ThumbnailTempDownloadUri": "https://...",
     "domain": "QBO",
    "sparse": false,
     "Id": "100000000004062175",
     "SyncToken": "1",
     "MetaData": {
        "CreateTime": "2015-10-29T16:04:05-07:00",
        "LastUpdatedTime": "2015-11-11T13:22:44-08:00"
     },
      "AttachableRef": [
         {
           "EntityRef": {
             "value": "95",
             "type": "Invoice"
           },
           "IncludeOnSend": false
         }
      ]
   },
   "time": "2015-11-11T13:22:44.013-08:00"
}

Listing attachments for a specific object

The relationship between an attachment and a transaction or item object resides in the Attachable metadata object for the attachment. It is possible to query the attachment list for the attachments linked to a particular object.

Issue the query below for all attachments linked to the purchase object whose Id is 611.

Operation: POST https://QuickBooks.API.intuit.com/v3/company/<realmId>/query?query=<selectStmt>
Content type: text/plain

The sample select statement below returns the attachable ids for all attachments linked to the purchase object whose Id is 611. To formulate this statement, you must first know the type of object and its object Id using the query endpoint for that resource.

select Id from attachable where AttachableRef.EntityRef.Type = 'purchase' and AttachableRef.EntityRef.value = '611'

For your own request:

Response body

This response returns two attachable objects corresponding to the two attachments to the target Purchase object. Use these Ids in other Attachable and Download resource operations as needed.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
   "QueryResponse": {
      "Attachable": [
         {
           "sparse": true,
           "Id": "100000000004062174"
         },
         {
           "sparse": true,
           "Id": "100000000004158481"
         }
      ],
     "startPosition": 1,
     "maxResults": 2
   },
   "time": "2015-11-24T10:18:31.289-08:00"
}

Uploading files to the attachment list

Operation: POST https://QuickBooks.API.intuit.com/v3/company/<realmId>/upload
Content type: multipart/form-data

This operation uploads one or more files to the Attachments list.

Of note:

Request body

The following sample code shows the multipart request body for uploading two files: the image, receipt_oct29.jpg, and the PDF file, receipt_june10.pdf.

1
2
3
4
5
6
7
8
9
--B1pD17v6kehNbda7sT7J2JOqssMTGGvw
Content-Disposition: form-data; name="file_content_01"; filename="receipt_oct29.jpg"
Content-Type: image/jpeg
<insert base-64 encoded file content for receipt_oct29.jpg here>
--B1pD17v6kehNbda7sT7J2JOqssMTGGvw
Content-Disposition: form-data; name="file_content_02"; filename="receipt_june10.pdf"
Content-Type: application/pdf
<insert base-64 encoded file content for receipt_june10.pdf here>
--B1pD17v6kehNbda7sT7J2JOqssMTGGvw--

Response body

The image below shows the resulting QuickBooks UI representation of the attachment list and how it relates to the Attachable metadata objects returned in the response payload.

qbo/docs/develop/tutorials/Attachments.png

An array of Attachable objects is returned in response body. Going forward, you can perform other operations on this object, as required. See Attachable in the QuickBooks Online API reference for complete details on supported operations.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
   "AttachableResponse": [
      {
         "Attachable": {
            "FileName": "receipt_oct29.jpg",
            "FileAccessUri": "/v3/company/1029354210/download/100000000004062174",
            "TempDownloadUri": "https://...",
            "Size": 1594261,
            "ContentType": "image/jpeg",
            "ThumbnailFileAccessUri": "/v3/company/1029354210/attachable-thumbnail/100000000004062174",
            "domain": "QBO",
            "sparse": false,
            "Id": "100000000004062174",
            "SyncToken": "0",
            "MetaData": {
             "CreateTime": "2015-10-29T16:04:05-07:00",
             "LastUpdatedTime": "2015-10-29T16:04:05-07:00"
            }
         }
         },
         {
         "Attachable": {
            "FileName": "receipt_june10.pdf",
            "FileAccessUri": "/v3/company/1029354210/download/100000000004062175",
            "TempDownloadUri": "https://...",
            "Size": 7933,
            "ContentType": "application/pdf",
            "domain": "QBO",
            "sparse": false,
            "Id": "100000000004062175",
            "SyncToken": "0",
            "MetaData": {
             "CreateTime": "2015-10-29T16:04:06-07:00",
             "LastUpdatedTime": "2015-10-29T16:04:06-07:00"
            }
         }
      }
   ],
   "time": "2015-10-29T16:04:02.620-07:00"
}

Downloading attachments

This operation retrieves a temporary download URL to the specified attachment. This URL expires after 15 minutes. The application uses this URL to then download the file as a separate step. If this URL expires, the app may obtain another.

Operation:GEThttps://QuickBooks.API.intuit.com/v3/company/<realmId>/download/attachableID
Content type: text/plain

The attachableID is the Id of the Attachable metadata object assigned during the upload operation to the attachment list. This is returned in the Attachable response body in the Id attribute.

The endpoint has the following behavior:

Response body

1
https://intuit-.../attachments/receipt_june10.pdf?Expires=...&AWSAccessKeyId=...&Signature=...

Thumbnails

To retrieve a temporary download URL for the associated thumbnail, use the following endpoint:

https://QuickBooks.API.intuit.com/v3/company/<realmId>/attachable-thumbnail/attachableID

The attachableID is the Id of the Attachable metadata object assigned during the upload operation to the attachment list. This is returned in the Attachable response body in the Id attribute.

Approved file types

The table below lists the approved attachment list file types.

File type Content type
ai application/postscript
csv text/csv
doc application/msword
docx application/vnd.openxmlformats-officedocument.wordprocessingml.document
eps application/postscript
gif image/gif
jpeg image/jpeg
jpg image/jpg
ods application/vnd.oasis.opendocument.spreadsheet
pdf application/pdf
png image/png
rtf text/rtf
tif image/tiff
txt text/plain
xls application/vnd.ms-excel
xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
xml text/xml

You app receives an error message similar to the one below if an attempt is made to upload a file type other than those listed above.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
   "AttachableResponse": [
      {
         "Fault": {
            "Error": [
               {
                  "Message": "Invalid Uploaded File",
                  "Detail": "The uploaded file is invalid. Supplied Content Type: File Content Type:application/zip, File Name: File Name:receipt_nov15.zip",
                  "code": "6041"
               }
            ],
            "type": "ValidationFault"
         }
      }
   ],
   "time": "2017-06-15T11:56:51.711-07:00"
}

Learn more

View the Attachable, Upload, and Download API references here.