Bank Transactions

Minimum access level: Banking, unless stated otherwise.

Attributes

Attribute Description Kind
url The unique identifier for the bank transaction URI
amount Total amount in the company's native currency Decimal
bank_account Transaction's bank account URI
dated_on Date of transaction in YYYY-MM-DD format Date
description Free-text description String
uploaded_at When the transaction was uploaded to FreeAgent Timestamp
unexplained_amount Amount yet to be explained Decimal
is_manual true if transaction was manually added (i.e. not from a statement or bank feed), false otherwise Boolean
bank_transaction_explanations Entries that fully or partially explain this transaction. See Bank Transaction Explanations. Array

List all bank transactions under a certain bank account

GET https://api.freeagent.com/v2/bank_transactions?bank_account=:bank_account

Date Filters

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

View Filters

GET https://api.freeagent.com/v2/bank_transactions?bank_account=:bank_account&view=unexplained
  • all (default)
  • unexplained
  • explained
  • manual
  • imported
  • marked_for_review

Filtering by latest statement upload

Returns only transactions that are part of the last statement that has been uploaded. Note that this may have been uploaded via the API or by a user via the web interface.

GET https://api.freeagent.com/v2/bank_transactions?bank_account=:bank_account&last_uploaded=true

Response

Status: 200 OK
{ "bank_transactions":[
  {
    "url":"https://api.freeagent.com/v2/bank_transactions/8",
    "amount":"-730.0",
    "bank_account":"https://api.freeagent.com/v2/bank_accounts/1",
    "dated_on":"2010-05-01",
    "description":".Reichert, Kautzer and Schultz/.harness end-to-end e-business 665-454-0057 x55609",
    "unexplained_amount":"0.0",
    "is_manual":false
  },
  {
    "url":"https://api.freeagent.com/v2/bank_transactions/15",
    "amount":"-350.0",
    "bank_account":"https://api.freeagent.com/v2/bank_accounts/1",
    "dated_on":"2010-06-14",
    "description":".Ledner Inc/.mesh enterprise platforms (246)942-9558",
    "unexplained_amount":"0.0",
    "is_manual":false
  }
]}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <bank-transactions type="array">
    <bank-transaction>
      <url>https://api.freeagent.com/v2/bank_transactions/8</url>
      <amount type="decimal">-730.0</amount>
      <bank-account>https://api.freeagent.com/v2/bank_accounts/1</bank-account>
      <dated-on type="date">2010-05-01</dated-on>
      <description>.Reichert, Kautzer and Schultz/.harness end-to-end e-business 665-454-0057 x55609</description>
      <unexplained-amount type="decimal">0.0</unexplained-amount>
      <is-manual type="boolean">false</is-manual>
    </bank-transaction>
    <bank-transaction>
      <url>https://api.freeagent.com/v2/bank_transactions/15</url>
      <amount type="decimal">-350.0</amount>
      <bank-account>https://api.freeagent.com/v2/bank_accounts/1</bank-account>
      <dated-on type="date">2010-06-14</dated-on>
      <description>.Ledner Inc/.mesh enterprise platforms (246)942-9558</description>
      <unexplained-amount type="decimal">0.0</unexplained-amount>
      <is-manual type="boolean">false</is-manual>
    </bank-transaction>
  </bank-transactions>
</freeagent>
Show as JSON

Get a single bank transaction

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

Response

Status: 200 OK
{ "bank_transaction":
  {
    "amount":"-730.0",
    "bank_account":"https://api.freeagent.com/v2/bank_accounts/1",
    "dated_on":"2010-05-01",
    "description":".Reichert, Kautzer and Schultz/.harness end-to-end e-business 665-454-0057 x55609",
    "unexplained_amount":"0.0",
    "is_manual":false,
    "bank_transaction_explanations":[
      {
        "url":"https://api.freeagent.com/v2/bank_transaction_explanations/8",
        "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",
      }
    ]
  }
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <bank-transaction>
    <amount type="decimal">-730.0</amount>
    <bank-account>https://api.freeagent.com/v2/bank_accounts/1</bank-account>
    <dated-on type="date">2010-05-01</dated-on>
    <description>.Reichert, Kautzer and Schultz/.harness end-to-end e-business 665-454-0057 x55609</description>
    <unexplained-amount type="decimal">0.0</unexplained-amount>
    <is-manual type="boolean">false</is-manual>
    <bank-transaction-explanations type="array">
      <bank-transaction-explanation>
        <url>https://api.freeagent.com/v2/bank_transaction_explanations/8</url>
        <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>
      </bank-transaction-explanation>
    </bank-transaction-explanations>
  </bank-transaction>
</freeagent>
Show as JSON

Upload a bank statement

POST https://api.freeagent.com/v2/bank_transactions/statement?bank_account=:bank_account

Bank statements can be uploaded as either an array of transactions or as a file.

Note: For all statement imports, transactions are deduplicated against any existing transactions in the bank account on that date with the same amount and description. To avoid any incorrect deduplication, best practice is to include all of a day's transactions in a single statement upload.

Upload a bank statement as an array of transactions

Attributes

  • statement (Required) An array of bank transaction objects, each containing:
    • dated_on (Required) Date of transaction in YYYY-MM-DD format.
    • description Free-text description. Defaults to an empty string
    • amount Total amount in the company's native currency. Defaults to 0

Example cURL Request

curl https://api.freeagent.com/v2/bank_transactions/statement?bank_account=:bank_account \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: */*" \
  -X POST \
  --data
  '{ "statement" :
    [
      {
        "dated_on" : "2019-07-01",
        "amount" : -100,
        "description" : "Local Council"
      },
      {
        "dated_on" : "2019-07-05",
        "amount" : 3560,
        "description" : "Sales"
      }
    ]
  }'
Show as XML
curl https://api.freeagent.com/v2/bank_transactions/statement?bank_account=:bank_account \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/xml" \
  -H "Accept: */*" \
  -X POST \
  --data '<?xml version="1.0" encoding="UTF-8"?>
  <statement type="array">
    <transaction>
      <dated_on>2017-10-01</dated_on>
      <amount>-100</amount>
      <description>Local Council</description>
    </transaction>
    <transaction>
      <dated_on>2017-10-05</dated_on>
      <amount>3560</amount>
      <description>Sales</description>
    </transaction>
  </statement>'
Show as JSON


Upload a bank statement as a file

Attributes

Example cURL Request

curl https://api.freeagent.com/v2/bank_transactions/statement?bank_account=:bank_account \
  -H "Authorization: Bearer TOKEN" \
  -H "Accept: */*" \
  -X POST \
  --form "statement=@your_file.ofx"


Responses

Status: 200 OK

Your data has been uploaded successfully. However, this does not indicate whether or not your statement has been imported correctly - please make another request to list your currently imported transactions, or check in the FreeAgent application itself to see if your import has succeeded.

Status: 400 Bad Request

Your request was poorly formatted and could not be parsed successfully. Please check you have not omitted a required attribute and have formatted your request correctly.

Status: 404 Not Found

You have either made a request to the wrong URL or you have failed to provide a valid bank account to import to.

Status: 406 Not Acceptable

You have omitted the statement value or the statement you have submitted does not contain any data.