Top

Bank Transactions

Get transactions list
GET /banktransactions
Get all the transaction details involved in an account.
Get transaction
GET /banktransactions/:transaction_id
Fetch the details of a transaction by specifying the transaction_id.
Create a transaction for an account
POST /banktransactions
Create a bank transaction based on the allowed transaction types.
Update a transaction
PUT /banktransactions/:bank_transaction_id
Make changes in the applicable fields of a transaction and update it.
Delete a transaction
DELETE /banktransactions/:transaction_id
Delete a transaction from an account by specifying the transaction_id.
Get matching transactions
GET /banktransactions/uncategorized/:transaction_id/match
Provide criteria to search for matching uncategorised transactions. The list of transactions can also include invoices/bills/credit-notes which will not be matched directly. Instead, a new (payment/refund) transaction is recorded and matched.
Match a transaction
POST /banktransactions/uncategorized/:transaction_id/match
Match an uncategorized transaction with an existing transaction in the account.
Unmatch a matched transaction
POST /banktransactions/:transaction_id/unmatch
Unmatch a transaction that was previously matched and make it uncategorized.
Get associated transactions
GET /banktransactions/:transaction_id/associated
Get a list of all the associated transactions that were matched or categorized to the given imported transaction.
Exclude a transaction
POST /banktransactions/uncategorized/:transaction_id/exclude
Exclude a transaction from your bank or credit card account.
Restore a transaction
POST /banktransactions/uncategorized/:transaction_id/restore
Restore an excluded transaction in your account.

Get transactions list

GET  /banktransactions

Get all the transaction details involved in an account.

Parameters

account_id* string Mandatory Account id for which transactions are to be listed.
filter_by string Filters the transactions based on the allowed types.
Allowed Values: Status.All, Status.Uncategorized, Status.Categorized, Status.ManuallyAdded, Status.Excluded and Status.Matched
transaction_type string Transaction type to group the list view
date string Start and end date, to provide a range within which the transaction date exist.
Variants: date_start and date_end
amount double Start and end amount, to provide a range within which the transaction amount exist.
Variants: amount_start and amount_end
status string Transaction status wise list view - All, uncategorized, manually_added, matched, excluded, categorized
reference_number string Reference Number of the transaction
sort_column string Sorts the transactions based on the allowed sort types.
Allowed Values: date

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "banktransactions": [
    {
      "transaction_id": "460000000048017",
      "date": "2013-10-01",
      "amount": 2000.00,
      "transaction_type": "deposit",
      "status": "manually_added",
      "source": "manually_added",
      "account_id": "460000000048001",
      "customer_id": "46000000000111",
      "payee": "Trendz",
      "currency_id": "460000000000097",
      "currency_code": "USD",
      "debit_or_credit": "debit",
      "offset_account_name": "Petty Cash",
      "reference_number": "Ref-121",
      "imported_transaction_id": ""
    },
    {
      "transaction_id": "460000000048019",
      "date": "2012-01-14",
      "amount": 7500.00,
      "transaction_type": "expense",
      "status": "manually_added",
      "source": "manually_added",
      "account_id": "460000000048001",
      "customer_id": "46000000005055",
      "payee": "",
      "currency_id": "460000000000097",
      "currency_code": "USD",
      "debit_or_credit": "credit",
      "offset_account_name": "Advertising And Marketing",
      "reference_number": "",
      "imported_transaction_id": ""
    },
    {
      "transaction_id": "460000000051001",
      "date": "2012-01-19",
      "amount": 4000.00,
      "transaction_type": "card_payment",
      "status": "categorized",
      "source": "csv",
      "account_id": "460000000048001",
      "customer_id": "",
      "payee": "",
      "currency_id": "460000000000097",
      "currency_code": "USD",
      "debit_or_credit": "credit",
      "offset_account_name": "Corp Card Account",
      "reference_number": "Ref-9872",
      "imported_transaction_id": "460000000050019"
    },
    {
      "transaction_id": "460000000050023",
      "date": "2012-01-12",
      "amount": 5000.00,
      "transaction_type": "deposit",
      "status": "matched",
      "source": "csv",
      "account_id": "460000000048001",
      "customer_id": "",
      "payee": "",
      "currency_id": "460000000000097",
      "currency_code": "USD",
      "debit_or_credit": "debit",
      "offset_account_name": "Petty Cash",
      "reference_number": "Ref-1900",
      "imported_transaction_id": "460000000050015"
    }
  ],
  "page_context": {
    "page": 1,
    "per_page": 200,
    "has_more_page": false,
    "report_name": "Transactions",
    "applied_filter": "Status.All",
    "sort_column": "date",
    "sort_order": "D"
  }
}

Get transaction

GET  /banktransactions/:transaction_id

Fetch the details of a transaction by specifying the transaction_id.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "banktransaction": {
    "transaction_id": "460000000048017",
    "from_account_id": "460000000000361",
    "from_account_name": "Petty Cash",
    "to_account_id": "460000000048001",
    "to_account_name": "Corporate Account",
    "transaction_type": "deposit",
    "currency_id": "460000000000097",
    "currency_code": "USD",
    "amount": 2000.00,
    "payment_mode": "Bank Transfer",
    "exchange_rate": 1.00,
    "date": "2013-10-01",
    "customer_id": "46000000000111",
    "customer_name": "Trendz",
    "reference_number": "Ref-121",
    "description": "Deposit to Corporate Account"
  }
}

Create a transaction for an account

POST  /banktransactions

Create a bank transaction based on the allowed transaction types.

Request attributes

from_account_id string The account ID from which money will be transferred(Mandatory for specific type of transactions). These accounts differ with respect to transaction_type.
Ex: To a bank account, from-account can be:
bank , card, income, refund.
To a card account, from account can be:
bank, card, refund.
to_account_id string ID of the account to which the money gets transferred(Mandatory for specific type of transactions).
Ex: From a bank account, to-account can be:
bank, card, drawings, expense,credit notes.
From a card account, to-account can be:
card, bank, expense.
transaction_type* string Allowed transaction types for bank:
Money Inflow:
deposit, transfer_fund, sales_without_invoices, owner_contribution, other_income, interest_income, expense_refund.
Money Outflow:
transfer_fund, owner_drawings, card_payment.
Allowed transaction types for card :
Money Inflow :
refund, expense_refund, card_payment.
Money Outflow:
card_payment
Allowed Values: deposit, refund, transfer_fund, card_payment, sales_without_invoices, expense_refund, owner_contribution, interest_income, other_income and owner_drawings
payment_mode string
[100]
Mode of payment for the transaction.
(not applicable for transfer_fund, card_payment, owner_drawings)

Ex:cash, cheque, etc.,
exchange_rate double The foreign currency exchange rate value.
date string
[yyyy-MM-dd]
Transaction date.
customer_id string ID of the customer or vendor.
vat_treatment
(UK Edition only)
string VAT treatment for the bank transaction. VAT treatment denotes the location of the customer or vendor. If the customer or vendor resides in the UK then the VAT treatment is uk. If the customer or vendor is in an EU country and if he has VAT registered, then his VAT treatment is eu_vat_registered. If he resides in EU and if he is not VAT registered, then his VAT treatment is eu_vat_not_registered. And, if he resides outside the EU then his VAT treatment is non_eu.
reference_number string
[100]
Reference Number of the transaction.
description string
[500]
A brief description about the transaction.
currency_id string The currency ID involved in the transaction.
tax_id
(Not applicable for the US Edition)
string ID of the tax or tax group applied to the line item.
product_type
(UK Edition only)
string Type of the transaction. This denotes whether the transaction line item is to be treated as goods or as a service.
Allowed Values: goods and service.
acquisition_vat_id
(UK Edition only)
string (Optional) This is the ID of the tax applied in case this is an EU - goods purchase or expense and acquisition VAT needs to be reported.
reverse_charge_vat_id
(UK Edition only)
string (Optional) This is the ID of the tax applied in case this is a non UK - service purchase or expense and reverse charge VAT needs to be reported.

Sample Request

{
      "from_account_id": "460000000000361",
      "to_account_id": "460000000048001",
      "transaction_type": "deposit",
      "amount": 2000.00,
      "payment_mode": "Bank Transfer",
      "date": "2013-10-01",
      "reference_number": "Ref-121",
    "description": "Deposit to Corporate Account",
    "customer_id":"46000000000111"
    }

Sample Response

Status: 201 Created
Content Type: application/json;charset=UTF-8
{
      "code": 0,
      "message": "The bank transaction has been recorded.",
        "banktransaction": {
        "transaction_id": "460000000048017",
        "from_account_id": "460000000000361",
        "from_account_name": "Petty Cash",
        "to_account_id": "460000000048001",
        "to_account_name": "Corporate Account",
        "transaction_type": "deposit",
        "currency_id": "460000000000097",
        "currency_code": "USD",
        "amount": 2000.00,
        "payment_mode": "Bank Transfer",
        "exchange_rate": 1.00,
        "date": "2013-10-01",
        "customer_id": "46000000000111",
        "customer_name": "Trendz",
        "reference_number": "Ref-121",
        "description": "Deposit to Corporate Account"
      }
    }

Update a transaction

PUT  /banktransactions/:bank_transaction_id

Make changes in the applicable fields of a transaction and update it.

Request attributes

from_account_id string The account ID from which money will be transferred(Mandatory for specific type of transactions). These accounts differ with respect to transaction_type.
Ex: To a bank account, from-account can be:
bank , card, income, refund.
To a card account, from account can be:
bank, card, refund.
to_account_id string ID of the account to which the money gets transferred(Mandatory for specific transaction types).
Ex: From a bank account, to-account can be:
bank, card, drawings, expense,credit notes.
From a card account, to-account can be:
card, bank, expense.
transaction_type* string Allowed transaction types for bank:
Money Inflow:
deposit, transfer_fund, sales_without_invoices, owner_contribution, other_income, interest_income, expense_refund.
Money Outflow:
transfer_fund, owner_drawings, card_payment.
Allowed transaction types for card :
Money Inflow :
refund, expense_refund, card_payment.
Money Outflow:
card_payment
Allowed Values: deposit, refund, transfer_fund, card_payment, sales_without_invoices, expense_refund, owner_contribution, interest_income, other_income and owner_drawings
payment_mode string
[100]
Mode of payment for the transaction.
(not applicable for transfer_fund, card_payment, owner_drawings)

Ex:cash, cheque, etc.,
exchange_rate double The foreign currency exchange rate value.
date string
[yyyy-MM-dd]
Transaction date.
customer_id string ID of the customer or vendor.
vat_treatment
(UK Edition only)
string VAT treatment for the bank transaction. VAT treatment denotes the location of the customer or vendor. If the customer or vendor resides in the UK then the VAT treatment is uk. If the customer or vendor is in an EU country and if he has VAT registered, then his VAT treatment is eu_vat_registered. If he resides in EU and if he is not VAT registered, then his VAT treatment is eu_vat_not_registered. And, if he resides outside the EU then his VAT treatment is non_eu.
reference_number string
[100]
Reference Number of the transaction.
description string
[500]
A brief description about the transaction.
currency_id string The currency ID involved in the transaction.
product_type
(UK Edition only)
string Type of the transaction. This denotes whether the transaction line item is to be treated as goods or as a service.
Allowed Values: goods and service.
acquisition_vat_id
(UK Edition only)
string (Optional) This is the ID of the tax applied in case this is an EU - goods purchase or expense and acquisition VAT needs to be reported.
reverse_charge_vat_id
(UK Edition only)
string (Optional) This is the ID of the tax applied in case this is a non UK - service purchase or expense and reverse charge VAT needs to be reported.

Sample Request

{
      "from_account_id": 460000000000361,
      "to_account_id": 460000000048001,
      "transaction_type": "deposit",
      "amount": 3000.00,
      "payment_mode": "Bank Transfer",
      "exchange_rate": 1.00,
      "date": "2013-10-01",
      "customer_id": "46000000000111",
      "reference_number": "Ref-121",
      "description": "Deposit to Corporate Account",
      "currency_id": 460000000000097
    }

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
      "code": 0,
      "message": "The bank transaction details has been updated.",
       "banktransaction": {
        "transaction_id": "460000000048017",
        "from_account_id": "460000000000361",
        "from_account_name": "Petty Cash",
        "to_account_id": "460000000048001",
        "to_account_name": "Corporate Account",
        "transaction_type": "deposit",
        "currency_id": "460000000000097",
        "currency_code": "USD",
        "amount": 3000.00,
        "payment_mode": "Bank Transfer",
        "exchange_rate": 1.00,
        "date": "2013-10-01",
        "customer_id": "46000000000111",
        "customer_name": "Trendz",
        "reference_number": "Ref-121",
        "description": "Deposit to Corporate Account"
      }
    }

Delete a transaction

DELETE  /banktransactions/:transaction_id

Delete a transaction from an account by specifying the transaction_id.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "The transaction has been deleted."
}

Get matching transactions

GET  /banktransactions/uncategorized/:transaction_id/match

Provide criteria to search for matching uncategorised transactions. The list of transactions can also include invoices/bills/credit-notes which will not be matched directly. Instead, a new (payment/refund) transaction is recorded and matched.

Parameters

transaction_type string The type of transaction.
Allowed Values: expense, deposit, refund, transfer_fund, card_payment, sales_without_invoices, expense_refund, owner_contribution, interest_income, other_income, owner_drawings, invoice, bill, credit_notes, creditnote_refund, vendor_credit, vendor_credit_refund, customer_payment and vendor_payment
date string
[yyyy-MM-dd]
Start and end date, to provide a range within which the transaction date exist.
Variants: date_start and date_end
amount double Initial and final amount range within which the search amount exists.
Variants: amount_start and amount_end
contact string
[100]
Contact person name, involved in the transaction.
reference_number string
[100]
Reference Number of the transaction.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "matching_transactions": [
    {
      "transaction_id": "3000000098029",
      "date": "2011-10-10",
      "date_formatted": "10 Oct 2011",
      "transaction_type": "expense",
      "transaction_type_formatted": "Expense",
      "reference_number": "",
      "amount": 7500.00,
      "amount_formatted": "Rs.7500.00",
      "debit_or_credit": "credit"
    }
  ],
  "page_context": {
    "page": 1,
    "per_page": 200,
    "has_more_page": false,
    "sort_column": "amount",
    "sort_order": "D",
    "search_criteria": [
      {
        "columnname": "amount",
        "search_text": "7500.00",
        "comparator": "range"
      },
      {
        "columnname": "date",
        "search_text": "2012-04-13",
        "comparator": "range"
      }
    ]
  },
  "instrumentation": {
    "query_execution_time": 3,
    "request_handling_time": 18,
    "response_write_time": 1,
    "page_context_write_time": 1
  }
}

Match a transaction

POST  /banktransactions/uncategorized/:transaction_id/match

Match an uncategorized transaction with an existing transaction in the account.

Parameters

account_id string ID of the account in which the transactions that has to be matched, exist.

Request attributes

transaction_id* string ID of the transaction that has to be matched with the imported transaction.
transaction_type* string One of the allowed types for the transaction that has to be matched.
Allowed Values: expense, deposit, refund, transfer_fund, card_payment, sales_without_invoices, expense_refund, owner_contribution, interest_income, other_income, owner_drawings, invoice, bill, credit_notes, creditnote_refund, vendor_credit, vendor_credit_refund, customer_payment and vendor_payment

Sample Request

{
      "transactions_to_be_matched": [
        {
          "transaction_id": "460000000050015",
          "transaction_type": "deposit"
        }
      ]
    }

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
      "code": 0,
      "message": "The Uncategorized transaction is linked to the selected transaction(s) in Zoho Books."
    }

Unmatch a matched transaction

POST  /banktransactions/:transaction_id/unmatch

Unmatch a transaction that was previously matched and make it uncategorized.

Parameters

account_id string ID of the account in which the transaction that has to be unmatched exist.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "The transaction has been unmatched."
}

Get associated transactions

GET  /banktransactions/:transaction_id/associated

Get a list of all the associated transactions that were matched or categorized to the given imported transaction.

Parameters

sort_column string
[100]
Param Description.
Allowed Values: statement_date

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "transaction": {
    "imported_transaction_id": "460000000050015",
    "date": "2012-01-12",
    "amount": 5000.00,
    "payee": "John Roberts",
    "reference_number": "Ref-1900",
    "description": "Cheque deposit",
    "status": "matched",
    "status_formatted": "Matched",
    "associated_transactions": [
      {
        "transaction_id": "460000000050023",
        "date": "2012-01-12",
        "debit_or_credit": "debit",
        "transaction_type": "deposit",
        "amount": 5000.00,
        "customer_id": "",
        "customer_name": ""
      }
    ]
  },
  "page_context": {
    "page": 1,
    "per_page": 200,
    "has_more_page": false,
    "sort_column": "date",
    "sort_order": "A"
  },
  "instrumentation": {
    "query_execution_time": 1,
    "request_handling_time": 4,
    "response_write_time": 3,
    "page_context_write_time": 0
  }
}

Exclude a transaction

POST  /banktransactions/uncategorized/:transaction_id/exclude

Exclude a transaction from your bank or credit card account.

Parameters

account_id string ID of the account in which the transaction that as to be excluded exist.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "The transaction has been excluded."
}

Restore a transaction

POST  /banktransactions/uncategorized/:transaction_id/restore

Restore an excluded transaction in your account.

Parameters

account_id string ID of the account in which the transaction that has to be restored exist.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "The excluded transaction has been restored."
}