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 One of the following:

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

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 One of the standard second sales tax rates Decimal
manual_sales_tax_amount Amount of sales tax for the transaction Decimal
manual_second_sales_tax_amount Amount of second sales tax for the transaction Decimal
description Description 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 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
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
asset_life_years Number of years over which the asset should be depreciated: 2, 3, 4, 5, or 7 Integer
? disposed_asset

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

Required for capital asset disposal
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": "2010-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",
    "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">2010-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>
      <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":"2010-05-01",
    "description":"harness end-to-end e-business",
    "entry_type":"Business Entertaining",
    "gross_value":"-730.0",
    "project": "https://api.freeagent.com/v2/projects/1",
    "rebill_type": "markup",
    "rebill_factor": "0.25",
    "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">2010-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>
    <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":"2010-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",
    "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">2010-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>
    <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":"2010-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",
  }
}
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">2010-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>
  </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":"2010-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",
    "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">2010-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>
    <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