Bank Transaction Explanation Attachments

Minimum access level: Banking, unless stated otherwise.

Minimum API version: 2026-09-01.

Upcoming breaking change: support for multiple file attachments

From 1st December 2026, the default API behaviour will be changed to allow up to 50 file attachments to be attached to a Bank Transaction Explanation.

As part of this change:

The Bank Transaction and Bank Transaction Explanations API endpoints will return an array of attachments and the singular attachment attribute will no longer be returned.
Bank Transaction Explanation file attachments must be added, updated or removed via the new Bank Transaction Explanation Attachments API endpoint.

We encourage you to use this new functionality now by setting the X-Api-Version header to 2026-09-01.

Attributes

Attribute	Description	Kind
attachments	An array of up to 50 `attachment` objects	Array

Attachment object attributes

Attribute	Description	Kind
url	The unique identifier for the attachment	URI
content_src	URL to the original full-size file	URI
content_src_medium	URL to a medium-size thumbnail (if a thumbnail exists)	URI
content_src_small	URL to a small-size thumbnail (if a thumbnail exists)	URI
expires_at	When the `content_src` URLs expire. New URLs should be fetched from the API once this timestamp passes.	Timestamp
content_type	MIME-type	String
file_name	Original name of the file	String
file_size	Size of original file in bytes	Integer
description	Free-text description	String

List all file attachments for a Bank Transaction Explanation

GET https://api.freeagent.com/v2/bank_transaction_explanations/:id/attachments

Response

Status: 200 OK

{
  "attachments": [
    {
      "url": "https://api.freeagent.com/v2/attachments/3",
      "content_src": "https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=...&Expires=...&Signature=...",
      "content_src_medium": "https://5tak8uqfvj.execute-api.eu-west-1.amazonaws.com/thumbnail/freeagent-production-attachments/...",
      "content_src_small": "https://5tak8uqfvj.execute-api.eu-west-1.amazonaws.com/thumbnail/freeagent-production-attachments/...",
      "expires_at": "2020-12-03T10:27:52.000Z",
      "content_type": "image/png",
      "file_name": "receipt1.png",
      "file_size": 7673,
      "description": "Receipt for printer"
    },
    {
      "url": "https://api.freeagent.com/v2/attachments/9",
      "content_src": "https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=...&Expires=...&Signature=...",
      "content_src_medium": "https://5tak8uqfvj.execute-api.eu-west-1.amazonaws.com/thumbnail/freeagent-production-attachments/...",
      "content_src_small": "https://5tak8uqfvj.execute-api.eu-west-1.amazonaws.com/thumbnail/freeagent-production-attachments/...",
      "expires_at": "2020-12-03T10:27:52.000Z",
      "content_type": "image/png",
      "file_name": "receipt2.png",
      "file_size": 5409,
      "description": "Receipt for paper"
    }
  ]
}

Show as XML

<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <attachments type="array">
    <attachment>
      <url>https://api.freeagent.com/v2/attachments/3</url>
      <content_src>https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=...&Expires=...&Signature=...</content_src>
      <content_src_medium>https://5tak8uqfvj.execute-api.eu-west-1.amazonaws.com/thumbnail/freeagent-production-attachments/...<content_src_medium>
      <content_src_small>https://5tak8uqfvj.execute-api.eu-west-1.amazonaws.com/thumbnail/freeagent-production-attachments/...</content_src_small>
      <expires_at type="dateTime">2020-12-03T10:27:52.000Z</expires_at>
      <content_type>image/png</content_type>
      <file_name>receipt1.png</file_name>
      <file_size>7673</file_size>
      <description>Receipt for printer</description>
    </attachment>
    <attachment>
      <url>https://api.freeagent.com/v2/attachments/9</url>
      <content_src>https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=...&Expires=...&Signature=...</content_src>
      <content_src_medium>https://5tak8uqfvj.execute-api.eu-west-1.amazonaws.com/thumbnail/freeagent-production-attachments/...<content_src_medium>
      <content_src_small>https://5tak8uqfvj.execute-api.eu-west-1.amazonaws.com/thumbnail/freeagent-production-attachments/...</content_src_small>
      <expires_at type="dateTime">2020-12-03T10:27:52.000Z</expires_at>
      <content_type>image/png</content_type>
      <file_name>receipt2.png</file_name>
      <file_size>5409</file_size>
      <description>Receipt for paper</description>
    </attachment>
  </attachments>
</freeagent>

Show as JSON

Attach a file attachments to a Bank Transaction Explanation

Note: You can attach up to 10 file attachments per API call, up to a total of 50 file attachments per Bank Transaction Explanation.

POST https://api.freeagent.com/v2/bank_transaction_explanations/:id/attachments

{
  "attachments": [
    {
      "data": "-- Base 64 encoded file data here --",
      "file_name": "receipt3.png",
      "content_type": "image/png",
      "description": "Receipt for ink"
    }
  ]
}

Show as XML

<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <attachments type="array">
    <attachment>
      <data>-- Base 64 encoded file data here --</data>
      <file_name>receipt3.png</file_name>
      <content_type>image/png</content_type>
      <description>Receipt for ink</description>
    </attachment>
  </attachments>
</freeagent>

Show as JSON

Response

Status: 201 Created

All file attachments, including the newly created one(s), are returned. See List all file attachments for a Bank Transaction Explanation for the response payload structure.

Update an existing file attachment associated with a Bank Transaction Explanation

PUT https://api.freeagent.com/v2/bank_transaction_explanations/:id/attachments

{
  "attachments": [
    {
      "url": "https://api.freeagent.com/v2/attachments/3",
      "data": "-- New Base 64 encoded file data here --",
      "file_name": "receipt3.png",
      "content_type": "image/png",
      "description": "Updated receipt for printer"
    }
  ]
}

Show as XML

<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <attachments type="array">
    <attachment>
      <url>https://api.freeagent.com/v2/attachments/3</url>
      <data>-- New Base 64 encoded file data here --</data>
      <file_name>receipt3.png</file_name>
      <content_type>image/png</content_type>
      <description>Updated receipt for printer</description>
    </attachment>
  </attachments>
</freeagent>

Show as JSON

Response

Status: 200 OK

All file attachments, including the recently updated one(s), are returned. See List all file attachments for a Bank Transaction Explanation for the response payload structure.

Delete an existing file attachment associated with a Bank Transaction Explanation

PUT https://api.freeagent.com/v2/bank_transaction_explanations/:id/attachments

{
  "attachments": [
    {
      "url": "https://api.freeagent.com/v2/attachments/3",
      "_destroy": "true"
    }
  ]
}

Show as XML

<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <attachments type="array">
    <attachment>
      <url>https://api.freeagent.com/v2/attachments/3</url>
      <_destroy>true</_destroy>
    </attachment>
  </attachments>
</freeagent>

Show as JSON

Response

Status: 200 OK

All file attachments, excluding the recently deleted one(s), are returned. See List all file attachments for a Bank Transaction Explanation for the response payload structure.

Combined operations

Note: You can attach, update or delete file attachments using a single PUT call. You can attach up to 10 file attachments per API call, up to a total of 50 file attachments per Bank Transaction Explanation.

PUT https://api.freeagent.com/v2/bank_transaction_explanations/:id/attachments

{
  "attachments": [
    {
      "data": "-- Base 64 encoded file data here --",
      "file_name": "receipt2.png",
      "content_type": "image/png",
      "description": "Receipt for pens"
    }
    {
      "url": "https://api.freeagent.com/v2/attachments/3",
      "data": "-- New Base 64 encoded file data here --",
      "file_name": "receipt3.png",
      "content_type": "image/png",
      "description": "Updated receipt for office supplies"
    },
    {
      "url": "https://api.freeagent.com/v2/attachments/4",
      "_destroy": "true"
    }
  ]
}

Show as XML

<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <attachments type="array">
    <attachment>
      <data>-- Base 64 encoded file data here --</data>
      <file_name>receipt2.png</file_name>
      <content_type>image/png</content_type>
      <description>Receipt for pens</description>
    </attachment>
    <attachment>
      <url>https://api.freeagent.com/v2/attachments/3</url>
      <data>-- New Base 64 encoded file data here --</data>
      <file_name>receipt3.png</file_name>
      <content_type>image/png</content_type>
      <description>Updated receipt for office supplies</description>
    </attachment>
    <attachment>
      <url>https://api.freeagent.com/v2/attachments/4</url>
      <_destroy>true</_destroy>
    </attachment>
  </attachments>
</freeagent>

Show as JSON

Response

Status: 200 OK

All file attachments, excluding any that were deleted, are returned. See List all file attachments for a Bank Transaction Explanation for the response payload structure.