Skip to content
Developerhome
Product homepage
Accounting
API Status:

Checking…

Attachments

  Less than to read

To improve the tracking of documents and prevent the need to store receipts, it is possible for a user to attach digital copies of documents and receipts to transactions. For example, you receive an invoice from a supplier and wish to keep a digital copy. When using the web application you can simply click a button and choose from either a pdf, jpg or png file to upload.

This functionality is also available via the API. The API reference for the /attachments endpoint can be found here: https://developer.sage.com/accounting/reference/attachments/

Accounting

Users of Sage Business Cloud Accounting are able to use the attachment functionality for the following transactions:

  • Banking - Other Receipts & Other Payments
  • Journals
  • Purchase Credits
  • Purchase Invoices
Start

For Sage Business Cloud Accounting-Start users the attachment functionality is available for the following transactions:

  • Banking - Money In & Money Out
  • Cashbook
  • Journals

Viewing attachments using the API

A list of all attachments can be obtained via a GET request to the /attachments endpoint. Caution should be applied when setting the ‘itemsPerPage’ pagination value due to the potential data size of attachments. We recommend using the default ‘itemsPerPage’ size of 20 should you need to obtain all attachments.

GET /attachments

{
    "$total": 1,
    "$page": 1,
    "$next": null,
    "$back": null,
    "$itemsPerPage": 20,
    "$items": [
        {
            "id": "8e84a2e9-8269-4f94-9f24-69cc2a3d62f0",
            "displayed_as": null,
            "$path": "/attachments/8e84a2e9-8269-4f94-9f24-69cc2a3d62f0"
        }
    ]
}

More detail can be seen when we send a further GET request, passing in the id of the attachment we are viewing. The attribute linking the attachment to a transaction attachment_context_id returns the transaction_id value and allows a link to be established.

GET /attachments/{id}

{
    "id": "8e84a2e9-8269-4f94-9f24-69cc2a3d62f0",
    "displayed_as": null,
    "$path": "/attachments/8e84a2e9-8269-4f94-9f24-69cc2a3d62f0",
    "mime_type": "image/png",
    "description": null,
    "file_extension": ".png",
    "transaction": {
        "id": "5d56637f7f7045a2bdf9a594e72c047a",
        "displayed_as": "",
        "$path": "/transactions/5d56637f7f7045a2bdf9a594e72c047a"
    },
    "file_size": 4645,
    "file_name": "TEST.png",
    "$file_path": "/attachments/8e84a2e9-8269-4f94-9f24-69cc2a3d62f0/file",
    "attachment_context_type": {
        "id": "PURCHASE_INVOICE",
        "displayed_as": "Purchase Invoice",
        "$path": "/attachment_context_types/PURCHASE_INVOICE"
    },
    "attachment_context": {
        "id": "9435b1b11678401b9246c7ef7be11fd7",
        "displayed_as": "27/01/2019 - 12.00",
        "$path": "/purchase_invoices/9435b1b11678401b9246c7ef7be11fd7"
    },
    "created_at": "2019-01-27T21:46:14Z",
    "updated_at": "2019-01-27T21:46:14Z"
}

It is then possible to retrieve the attachment binary file. Make sure to always add Accept: application/octet-stream to the request headers when retrieving attachment binary files.

GET /attachments/{id}/file

Accept: application/octet-stream

Locating an attachment from a transaction

The most probable reason for viewing an attachment is its association with a transaction. Locating attachments belonging to a transaction is achieved by passing two query parameters in a GET request to the attachments endpoint.

GET /attachments?attachment_context_id=fc145a21fc6d42ddaf6f089b964d28e5&attachment_context_type_id=OTHER_PAYMENT

The attachment_context_type_id is the transaction type the attachment belongs to and can be one of the following types:

Attachment Context Type ID Description
BANK_TRANSFER Used for Bank Transfers
JOURNAL Used for Journals
OTHER_PAYMENT Used for both Payments and Receipts
OTHER_INCOME_PAYMENT Used for Other Receipts
PURCHASE_CORRECTIVE_INVOICE Used for Spanish Corrective Purchase Invoices
PURCHASE_CREDIT_NOTE Used for Purchase Credit Notes
PURCHASE_INVOICE Used for Purchase Invoices
SALES_INVOICE Used for Sales Invoices

The attachment_context_id value is the origin_id of the associated transaction and should not be confused with the transaction_id. The number_of_attachments associated with the transaction is returned as an attribute of a GET request transactions response and can be used to ensure all associated attachments are available to the user.

{
  "id": "fd4b0e1970f84c3c999423fbea92aaf7",
  "displayed_as": "test attachment",
  "$path": "/transactions/fd4b0e1970f84c3c999423fbea92aaf7",
  "created_at": "2019-05-16T18:38:55Z",
  "updated_at": "2019-05-16T18:38:55Z",
  "date": "2019-05-16",
  "deleted": false,
  "reference": "test attachment",
  "total": "10.0",
  "total_in_transaction_currency": "10.0",
  "contact": null,
  "transaction_type": {
    "id": "OTHER_RECEIPT",
    "displayed_as": "Other Receipt",
    "$path": "/transaction_types/OTHER_RECEIPT"
  },
  "origin": {
    "id": "fc145a21fc6d42ddaf6f089b964d28e5",
    "displayed_as": "test attachment",
    "$path": "/other_payments/fc145a21fc6d42ddaf6f089b964d28e5",
    "links": [
      {
        "href": null,
        "rel": "alternate",
        "type": "text/html"
      }
    ]
  },
  "audit_trail_id": 2230,
  "number_of_attachments": 1
}

Attachment Query Parameters

In addition to locating attachments via the transaction origin_id it is possible to use alternative query parameters.

If you are maintaining a localised representation of the Sage Accounting data which includes attachments you will probably want to to pass the updated_or_created_since parameter with a datetime value (2019-11-01T09:38:16Z) to find new or modified attachments created since the last synch. In a similar light, the deleted_since query parameter allows deleted attachments to be recognised by passing in a datetime value.

Creating an attachment

At present attachments support the following file types:

  • PDF
  • GIF
  • JPEG
  • JPG
  • PNG
  • TIF
  • TIFF

An attachment is created by making a POST request to the /attachments endpoint.

When adding an attachment, it is a requirement to associate it with an attachment context. For example, attaching an image of a paper invoice to a purchase invoice. Due to this you must ensure you retrieve the purchase invoice id of the associated transaction prior to being able to POST the attachment.

This can be done by making a GET request to the appropriate endpoint, /purchase_invoices in the above example.

In addition to the attachment_context_id, you need to provide an attachment context type, for example PURCHASE_INVOICE. A list of all available attachment context types can be obtained by requesting:

GET /attachment_context_types

Once the origin_id of the purchase invoice is known, the attachment is prepared for the POST request by encoding it to Base64. In the POST request the resulting string will be passed in the file field:

POST /attachments
Content-Type: application/json

{
  "attachment": {
    "file": "iVBORw0KGgoAAAANSUhEUgAAA0MAAAJxCAIAAAAPZ/6...",
    "file_name": "test2.png",
    "mime_type": "image/png",
    "description": "Test of an upload via the API",
    "file_extension": ".png",
    "attachment_context_id": "PURCHASE_INVOICE",
    "attachment_context_type_id": "9435b1b11678401b9246c7ef7be11fd7"
  }
}

A successful POST will return a status of “201 Created” and a response body similar to the following:

{
  "id": "fa461320-bd2c-4798-a16e-487d29a2eb2b",
  "displayed_as": "Test of an upload via the API",
  "$path": "/attachments/fa461320-bd2c-4798-a16e-487d29a2eb2b",
  "mime_type": "image/png",
  "description": "Test of an upload via the API",
  "file_extension": ".png",
  "transaction": {
    "id": "5d56637f7f7045a2bdf9a594e72c047a",
    "displayed_as": "",
    "$path": "/transactions/5d56637f7f7045a2bdf9a594e72c047a"
  },
  "file_size": 4071,
  "file_name": "test2.png",
  "$file_path": "/attachments/fa461320-bd2c-4798-a16e-487d29a2eb2b/file",
  "attachment_context_type": {
    "id": "PURCHASE_INVOICE",
    "displayed_as": "Purchase Invoice",
    "$path": "/attachment_context_types/PURCHASE_INVOICE"
  },
  "attachment_context": {
    "id": "9435b1b11678401b9246c7ef7be11fd7",
    "displayed_as": "27/01/2019 - 12.00",
    "$path": "/purchase_invoices/9435b1b11678401b9246c7ef7be11fd7"
  },
  "created_at": "2019-01-30T16:02:54Z",
  "updated_at": "2019-01-30T16:02:54Z"
}

Editing an attachment

Existing attachments can be edited via a PUT request which allows the file name or description of the attachment to be changed.

PUT /attachments/{id}

It is sufficient to pass only the required changes in the body of the PUT request.

PUT /attachments/{id}
Content-Type: application/json

{
  "attachment": {
    "file_name": "Invoice No. 1423 copy.png",
    "description": "Attachment created for Invoice Number 1423."
  }
}

A status of “200 OK” will be returned along with a response:

{
  "id": "fa461320-bd2c-4798-a16e-487d29a2eb2b",
  "displayed_as": "Attachment created for Invoice Number 1423.",
  "$path": "/attachments/fa461320-bd2c-4798-a16e-487d29a2eb2b",
  "mime_type": "image/png",
  "description": "Attachment created for Invoice Number 1423.",
  "file_extension": ".png",
  "transaction": {
    "id": "5d56637f7f7045a2bdf9a594e72c047a",
    "displayed_as": "",
    "$path": "/transactions/5d56637f7f7045a2bdf9a594e72c047a"
  },
  "file_size": 4071,
  "file_name": "Invoice No. 1423 copy.png",
  "$file_path": "/attachments/fa461320-bd2c-4798-a16e-487d29a2eb2b/file",
  "attachment_context_type": {
    "id": "PURCHASE_INVOICE",
    "displayed_as": "Purchase Invoice",
    "$path": "/attachment_context_types/PURCHASE_INVOICE"
  },
  "attachment_context": {
    "id": "9435b1b11678401b9246c7ef7be11fd7",
    "displayed_as": "27/01/2019 - 12.00",
    "$path": "/purchase_invoices/9435b1b11678401b9246c7ef7be11fd7"
  },
  "created_at": "2019-01-31T16:02:54Z",
  "updated_at": "2019-01-31T16:41:36Z"
}

Deleting an attachment

It is also possible to delete an attachment. Attachments are deleted via a DELETE request to the attachments endpoint which passes the id of the attachment as a parameter:

DELETE /attachments/{id}

On successful deletion you will receive a status of “204 No Content” with a blank response.