Bank Transaction Explanations

Minimum access level: Banking, unless stated otherwise.

Attributes

Required Attribute Description Kind
url The unique identifier for the explanation URI
? bank_account

Bank account in which the explained transaction will be created

Required if bank_transaction is not specified
URI
? bank_transaction

Transaction that is being explained

Required if bank_account is not specified
URI
type Read-only explanation type, e.g. Payment, Invoice Receipt String
ec_status Transaction's VAT status for reporting purposes. One of the following:

  • UK/Non-EC
  • EC Goods
  • EC Services
  • Reverse Charge
  • EC VAT MOSS

Please note that EC Goods and EC Services are no longer valid options if the transaction is dated 1/1/2021 or later and the company is based in Great Britain (but not Northern Ireland), following the UK's withdrawal from the EU.

Reverse Charge is only a valid status if the transaction is dated 1/1/2021 or later.

String
? place_of_supply Place of supply when ec_status is EC VAT MOSS String
dated_on Date of the explanation Date
gross_value Value of the explanation in the company's native currency Decimal
? sales_tax_rate

One of the standard sales tax rates or an EC VAT MOSS rate.

Required for EC VAT MOSS explanation
Decimal
second_sales_tax_rate [Universal accounts only] One of the standard second sales tax rates Decimal
sales_tax_value Value of sales tax for the transaction Decimal
second_sales_tax_value [Universal accounts only] Value of second sales tax for the transaction Decimal
sales_tax_status Indicates whether the item is TAXABLE, EXEMPT or OUT_OF_SCOPE for sales tax String
second_sales_tax_status [Universal accounts only] Similar to sales_tax_status, returned only if the relevant sales tax period defines a second sales tax String
? description

Description

Not required for transfers or invoice receipts
String
category Accounting category of the explanation URI
cheque_number Cheque number String
attachment

Explanation attachment (max 5MB), in the following format:

  • data (binary data of the file being attached encoded as base64)
  • file_name
  • description
  • content_type can be one of the following:
    • image/png
    • image/x-png
    • image/jpeg
    • image/jpg
    • image/gif
    • application/x-pdf
Object
marked_for_review true if the explanation has been guessed and awaiting approval, false otherwise Boolean
is_money_in true if money in, false otherwise Boolean
is_money_out true if money out, false otherwise Boolean
is_money_paid_to_user true if money is paid to or received from user, false otherwise Boolean
is_locked true when the explanation cannot be changed, false otherwise Boolean
locked_attributes List of attributes that cannot be modified Array
locked_reason The reason for the explanation being locked String
is_deletable true when the explanation can be deleted, false otherwise Boolean
Additional attributes for Payment / Refund
project The project being linked or rebilled URI
rebill_type One of the following:

  • cost
  • markup
  • price

String
? rebill_factor

How much to rebill for

Required when rebill_type is markup or price
Decimal
receipt_reference Receipt reference String
Additional attributes for Invoice Receipt / Credit Note Refund
paid_invoice Invoice that has been paid, or credit note that has been refunded URI
foreign_currency_value Equivalent of gross_value in the foreign currency, if explaning a foreign currency invoice Decimal
Additional attributes for Bill Payment / Bill Refund
paid_bill Bill that was paid or refunded URI
Additional attributes for Money Paid to User / Money Received from User
paid_user User to which money was paid or from which money was received URI
Additional attributes for Transfer to Another Account / Transfer from Another Account
transfer_bank_account Bank account transfered to / from URI
Additional attributes for Purchase of Stock / Sale of Stock
stock_item Stock item purchased or sold URI
stock_altering_quantity How much stock has been purchased or sold Integer
Additional attributes for Purchase of Capital Asset / Disposal of Capital Asset
capital_asset A link to the asset purchased with this transaction. Read-only. See depreciation profiles for more details on what to include in this field for create/update requests. URI
asset_life_years

Note! This field is deprecated. Fetch the capital asset using the link in the capital_asset field of the response to view full details of its depreciation profile.

Number of years over which the asset should be depreciated for straight line depreciation, otherwise 0 for backwards compatibility while the field is deprecated.

Only relevant for capital asset purchase.
String
? disposed_asset

Asset which is disposed of. No need to specify category in this case.

Required for capital asset disposal
URI
Additional attributes for UK Unincorporated Landlord companies (profit and loss categories only)
? property

The property linked to the explanation

URI

List all bank transaction explanations

Requires the bank account to be specified.

GET https://api.freeagent.com/v2/bank_transaction_explanations?bank_account=https://api.freeagent.com/v2/bank_accounts/:id

Date Filters

GET https://api.freeagent.com/v2/bank_transaction_explanations?bank_account=https://api.freeagent.com/v2/bank_accounts/:id&from_date=2012-01-01&to_date=2012-03-31
GET https://api.freeagent.com/v2/bank_transaction_explanations?bank_account=https://api.freeagent.com/v2/bank_accounts/:id&updated_since=2017-05-22T09:00:00.000Z
  • from_date
  • to_date
  • updated_since

Response

Status: 200 OK
{ "bank_transaction_explanations": [
  {
    "url": "https://api.freeagent.com/v2/bank_transaction_explanations/20",
    "bank_transaction": "https://api.freeagent.com/v2/bank_transactions/20",
    "bank_account": "https://api.freeagent.com/v2/bank_accounts/1",
    "category": "https://api.freeagent.com/v2/categories/366",
    "dated_on": "2019-12-01",
    "description": "transform plug-and-play convergence",
    "gross_value": "-90.0",
    "project": "https://api.freeagent.com/v2/projects/1",
    "rebill_type": "markup",
    "rebill_factor": "0.25",
    "updated_at": "2020-02-06T11:08:28.000Z",
    "sales_tax_status": "TAXABLE",
    "sales_tax_rate": "0.0",
    "sales_tax_value": "0.0",
    "is_deletable": true,
    "attachment":
      {
        "url":"https://api.freeagent.com/v2/attachments/3",
        "content_src":"https://s3.amazonaws.com/freeagent-dev/attachments/2/original.pdf?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&Expires=1316186571&Signature=tA4V5%2BJEE%2Fc3JTg5AiIO494m0cA%3D",
        "content_type":"application/pdf",
        "file_name":"About Stacks.pdf",
        "file_size":466028
      }
  }]
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <bank-transaction-explanations type="array">
    <bank-transaction-explanation>
      <url>https://api.freeagent.com/v2/bank_transaction_explanations/20</url>
      <bank-transaction>https://api.freeagent.com/v2/bank_transactions/20</bank-transaction>
      <bank-account>https://api.freeagent.com/v2/bank_accounts/1</bank-account>
      <category>https://api.freeagent.com/v2/categories/366</category>
      <dated-on type="date">2019-12-01</dated-on>
      <description>transform plug-and-play convergence</description>
      <gross-value type="decimal">-90.0</gross-value>
      <project>https://api.freeagent.com/v2/projects/1</project>
      <rebill-type>markup</rebill-type>
      <rebill-factor type="decimal">0.25</rebill-factor>
      <updated-at type="datetime">2020-02-06T11:08:28.000Z</updated-at>
      <sales-tax-status>TAXABLE</sales-tax-status>
      <sales-tax-rate type="decimal">0.0</sales-tax-rate>
      <sales-tax-value type="decimal">0.0</sales-tax-value>
      <is-deletable type="boolean">true</is-deletable>
      <attachment>
        <url>https://api.freeagent.com/v2/attachments/3</url>
        <content-src>https://s3.amazonaws.com/freeagent-dev/attachments/2/original.pdf?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&amp;Expires=1316186508&amp;Signature=R0jkClXSS5TYvvmFlOP%2F6UIRuBY%3D</content-src>
        <content-type>application/pdf</content-type>
        <file-name>About Stacks.pdf</file-name>
        <file-size type="integer">466028</file-size>
      </attachment>
    </bank-transaction-explanation>
  </bank-transaction-explanations>
</freeagent>
Show as JSON

Get a single bank transaction explanation

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

Response

Status: 200 OK
{ "bank_transaction_explanation":
  {
    "bank_transaction":"https://api.freeagent.com/v2/bank_transactions/8",
    "bank_account":"https://api.freeagent.com/v2/bank_accounts/1",
    "dated_on":"2019-05-01",
    "description":"harness end-to-end e-business",
    "gross_value":"-730.0",
    "project": "https://api.freeagent.com/v2/projects/1",
    "rebill_type": "markup",
    "rebill_factor": "0.25",
    "updated_at": "2020-02-06T11:08:28.000Z",
    "sales_tax_status": "TAXABLE",
    "sales_tax_rate": "20.0",
    "sales_tax_value": "-121.67",
    "is_deletable": true,
    "attachment":
      {
        "url":"https://api.freeagent.com/v2/attachments/3",
        "content_src":"https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&Expires=1314281186&Signature=GFAKDo%2Bi%2FsUMTYEgg6ZWGysB4k4%3D",
        "content_type":"image/png",
        "file_name":"barcode.png",
        "file_size":7673
      }
  }
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <bank-transaction-explanation>
    <bank-transaction>https://api.freeagent.com/v2/bank_transactions/8</bank-transaction>
    <bank-account>https://api.freeagent.com/v2/bank_accounts/1</bank-account>
    <dated-on type="date">2019-05-01</dated-on>
    <description>harness end-to-end e-business</description>
    <entry-type>Business Entertaining</entry-type>
    <gross-value type="decimal">-730.0</gross-value>
    <project>https://api.freeagent.com/v2/projects/1</project>
    <rebill-type>markup</rebill-type>
    <rebill-factor type="decimal">0.25</rebill-factor>
    <updated-at type="datetime">2020-02-06T11:08:28.000Z</updated-at>
    <sales-tax-status>TAXABLE</sales-tax-status>
    <sales-tax-rate type="decimal">20.0</sales-tax-rate>
    <sales-tax-value type="decimal">-121.67</sales-tax-value>
    <is-deletable type="boolean">true</is-deletable>
    <attachment>
      <url>https://api.freeagent.com/v2/attachments/3</url>
      <content-src>https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&amp;Expires=1314281298&amp;Signature=jhGeAgqdnDwyFKHJoPI6AKU%2Fb2s%3D</content-src>
      <content-type>image/png</content-type>
      <file-name>barcode.png</file-name>
      <file-size type="integer">7673</file-size>
    </attachment>
  </bank-transaction-explanation>
</freeagent>
Show as JSON

Create a bank transaction explanation

Payload should have a root bank_transaction_explanation element, containing elements listed under Attributes.

Bank transaction explanations can be created for all of the explanation types supported in FreeAgent. Set the bank_transaction attribute to explain an existing bank transaction or set the bank_account attribute to create a matching bank transaction along with the bank transaction explanation.

In general the explanation type is chosen by setting the category attribute. However, for paying an invoice, bill or transferring funds between bank accounts, the category is not required. To make a Smart User Payment, set the paid_user attribute, but omit the category attribute. To create explanations for other kinds of user payments set both the paid_user attribute and the relevant category attribute.

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

Response

Status: 201 Created
Location: https://api.freeagent.com/v2/bank_transaction_explanations/12
{ "bank_transaction_explanation":
  {
    "bank_transaction":"https://api.freeagent.com/v2/bank_transactions/8",
    "bank_account":"https://api.freeagent.com/v2/bank_accounts/1",
    "dated_on":"2019-05-01",
    "description":"harness end-to-end e-business",
    "category":"https://api.freeagent.com/v2/categories/285",
    "gross_value":"-730.0",
    "project": "https://api.freeagent.com/v2/projects/1",
    "rebill_type": "markup",
    "rebill_factor": "0.25",
    "updated_at": "2020-02-06T11:08:28.000Z",
    "sales_tax_status": "TAXABLE",
    "sales_tax_rate": "20.0",
    "sales_tax_value": "-121.67",
    "is_deletable": true,
    "attachment":
      {
        "url":"https://api.freeagent.com/v2/attachments/3",
        "content_src":"https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&Expires=1314281186&Signature=GFAKDo%2Bi%2FsUMTYEgg6ZWGysB4k4%3D",
        "content_type":"image/png",
        "file_name":"barcode.png",
        "file_size":7673
      }
  }
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <bank-transaction-explanation>
    <bank-transaction>https://api.freeagent.com/v2/bank_transactions/8</bank-transaction>
    <bank-account>https://api.freeagent.com/v2/bank_accounts/1</bank-account>
    <dated-on type="date">2019-05-01</dated-on>
    <description>harness end-to-end e-business</description>
    <category>https://api.freeagent.com/v2/categories/285</category>
    <gross-value type="decimal">-730.0</gross-value>
    <project>https://api.freeagent.com/v2/projects/1</project>
    <rebill-type>markup</rebill-type>
    <rebill-factor type="decimal">0.25</rebill-factor>
    <updated-at type="datetime">2020-02-06T11:08:28.000Z</updated-at>
    <sales-tax-status>TAXABLE</sales-tax-status>
    <sales-tax-rate type="decimal">20.0</sales-tax-rate>
    <sales-tax-value type="decimal">-121.67</sales-tax-value>
    <is-deletable type="boolean">true</is-deletable>
    <attachment>
      <url>https://api.freeagent.com/v2/attachments/3</url>
      <content-src>https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&amp;Expires=1314281298&amp;Signature=jhGeAgqdnDwyFKHJoPI6AKU%2Fb2s%3D</content-src>
      <content-type>image/png</content-type>
      <file-name>barcode.png</file-name>
      <file-size type="integer">7673</file-size>
    </attachment>
  </bank-transaction-explanation>
</freeagent>
Show as JSON

Transferring money between bank accounts

Explanations which explain money transfers will have a linked explanation and bank account which explain the other side of the transfer.

Response

{ "bank_transaction_explanation":
  {
    "bank_transaction":"https://api.freeagent.com/v2/bank_transactions/8",
    "bank_account":"https://api.freeagent.com/v2/bank_accounts/1",
    "dated_on":"2019-05-01",
    "description":"Transfer from Bank Account One to Bank Account Two",
    "linked_transfer_explanation":"https://api.freeagent.com/v2/bank_transaction_explanation/125",
    "linked_transfer_account":"https://api.freeagent.com/v2/bank_accounts/2",
    "gross_value":"-170.0",
    "is_deletable": true,
    "updated_at": "2020-02-06T11:08:28.000Z"
  }
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <bank-transaction-explanation>
    <bank-transaction>https://api.freeagent.com/v2/bank_transactions/8</bank-transaction>
    <bank-account>https://api.freeagent.com/v2/bank_accounts/1</bank-account>
    <dated-on type="date">2019-05-01</dated-on>
    <description>Transfer from Bank Account One to Bank Account Two</description>
    <linked-transfer-explanation>https://api.freeagent.com/v2/bank_transaction_explanation/125</linked-transfer-explanation>
    <linked-transfer-account>https://api.freeagent.com/v2/bank_accounts/2</linked-transfer-account>
    <gross-value type="decimal">-730.0</gross-value>
    <is-deletable type="boolean">true</is-deletable>
    <updated-at type="datetime">2020-02-06T11:08:28.000Z</updated-at>
  </bank-transaction-explanation>
</freeagent>
Show as JSON

Update a bank transaction explanation

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

Payload should have a root bank_transaction_explanation element, containing elements listed under Attributes that should be updated.

Response

Status: 200 OK
{ "bank_transaction_explanation":
  {
    "bank_transaction":"https://api.freeagent.com/v2/bank_transactions/8",
    "bank_account":"https://api.freeagent.com/v2/bank_accounts/1",
    "dated_on":"2019-05-01",
    "description":"harness end-to-end e-business",
    "category":"https://api.freeagent.com/v2/categories/285",
    "gross_value":"-730.0",
    "project": "https://api.freeagent.com/v2/projects/1",
    "rebill_type": "price",
    "rebill_factor": "800",
    "updated_at": "2020-02-06T11:08:28.000Z",
    "sales_tax_status": "TAXABLE",
    "sales_tax_rate": "20.0",
    "sales_tax_value": "-28.33",
    "is_deletable": true,
    "attachment":
      {
        "url":"https://api.freeagent.com/v2/attachments/3",
        "content_src":"https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&Expires=1314281186&Signature=GFAKDo%2Bi%2FsUMTYEgg6ZWGysB4k4%3D",
        "content_type":"image/png",
        "file_name":"barcode.png",
        "file_size":7673
      }
  }
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <bank-transaction-explanation>
    <bank-transaction>https://api.freeagent.com/v2/bank_transactions/8</bank-transaction>
    <bank-account>https://api.freeagent.com/v2/bank_accounts/1</bank-account>
    <dated-on type="date">2019-05-01</dated-on>
    <description>harness end-to-end e-business</description>
    <category>>https://api.freeagent.com/v2/categories/285</category>
    <gross-value type="decimal">-730.0</gross-value>
    <project>https://api.freeagent.com/v2/projects/1</project>
    <rebill-type>price</rebill-type>
    <rebill-factor type="decimal">800</rebill-factor>
    <updated-at type="datetime">2020-02-06T11:08:28.000Z</updated-at>
    <sales-tax-status>TAXABLE</sales-tax-status>
    <sales-tax-rate type="decimal">20.0</sales-tax-rate>
    <sales-tax-value type="decimal">-121.67</sales-tax-value>
    <is-deletable type="boolean">true</is-deletable>
    <attachment>
      <url>https://api.freeagent.com/v2/attachments/3</url>
      <content-src>https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&amp;Expires=1314281298&amp;Signature=jhGeAgqdnDwyFKHJoPI6AKU%2Fb2s%3D</content-src>
      <content-type>image/png</content-type>
      <file-name>barcode.png</file-name>
      <file-size type="integer">7673</file-size>
    </attachment>

  </bank-transaction-explanation>
</freeagent>
Show as JSON

Delete a bank transaction explanation

DELETE https://api.freeagent.com/v2/bank_transaction_explanations/:id

Response

Status: 200 OK