List transactions

GET

/transactions/

const url = 'https://app.commitly.com/api/transactions/?type=incomes&page_size=100';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://app.commitly.com/api/transactions/?type=incomes&page_size=100' \
  --header 'Authorization: Bearer <token>'

Returns the transactions of all bank accounts of the company. Default order: newest value date first (-value_date,id).

This endpoint returns no sum, whatever the filters. For the sum of all matching transactions, use GET /transactions/extended/ with the same parameters.

predicted_unmapped_transactions is deprecated and will be removed. It is a company-wide flag and does not depend on the filters of the request: it is true if at least one uncategorized transaction with a non-zero amount has a suggested category waiting for review.

Authorizations

commitlyOAuth

Parameters

Query Parameters

account

Array<integer>

Bank account ID. Repeat the parameter for several accounts.

category

Array<integer>

Category ID; includes its subcategories. Repeat the parameter for several categories.

min_date

string format: date

Earliest value date.

max_date

string format: date

Latest value date.

value_date_year

integer

Year of the value date.

value_date_month

integer

>= 1 <= 12

Month of the value date (1 to 12).

fiscal_year

integer

Fiscal year of the company.

min_amount

number

Minimum reporting amount.

max_amount

number

Maximum reporting amount.

type

string

Allowed values: incomes expenses

incomes or expenses.

is_new

boolean

true: transactions still in a default (uncategorized) category.

predicted

boolean

true: uncategorized transactions that have a suggested category.

matched

boolean

true: transactions linked to an invoice.

is_payment

boolean

Filter on the transaction field is_payment.

tags

string

Filter on tags.

empty_tags

boolean

true: transactions without tags.

ids

string

Comma-separated transaction IDs.

min_date_created

string

Earliest creation time (ISO 8601).

max_date_created

string

Latest creation time (ISO 8601).

min_date_updated

string

Earliest time of the last update (ISO 8601).

max_date_updated

string

Latest time of the last update (ISO 8601).

search

string

Full-text search.

ordering

string

Sort order. Allowed fields: value_date, counterpart_name, reporting_amount. Prefix a field with - for descending order. Default: -value_date,id.

page

integer

>= 1

Page number, starting at 1. When paging through results, read this value from the next link and send it to the documented base URL.

page_size

integer

default: 100 >= 1 <= 1000

Number of records per page. Default 100, maximum 1000; larger values are reduced to 1000.

Responses

200

Paginated list of transactions.

application/json

object

count

required

Total number of matching records.

integer

next

required

URL of the next page, or null on the last page. The host name may differ from the documented base URL; read page from it and call the documented base URL.

string | null format: uri

previous

required

URL of the previous page, or null on the first page.

string | null format: uri

predicted_unmapped_transactions

Deprecated, will be removed; do not build on it. Company-wide, independent of the request’s filters: true if at least one uncategorized transaction with a non-zero amount has a suggested category waiting for review.

boolean

results

Array<object>

object

integer

account

Short form of a bank account, embedded in transactions.

object

integer

name

string

alias

string

bank

Bank name. Present in the create-transactions response only.

string

currency

Present in the create-transactions response only.

string

category

One of:

object
null

Short form of a category, embedded in transactions and budgets.

object

integer

name

string

description

string

predicted_category

One of:

object
null

Extended category representation, embedded as predicted_category in transactions.

object

integer

name

string

slug

string

description

string

type

AG aggregating, EX expenses, IN incomes.

string

Allowed values: AG EX IN

order

Display position.

integer

date_created

string format: date-time

is_default

boolean

is_obsolete

boolean

lft

Internal; can be ignored.

integer

rght

Internal; can be ignored.

integer

tree_id

Internal; can be ignored.

integer

level

Internal; can be ignored.

integer

tenant

integer

company

integer

parent

ID of the parent category.

integer | null

source

integer | null

invoice

Invoice linked to the transaction, or null.

parent

One of:

recursive object
null

object recursive

value_date

Value date (YYYY-MM-DD).

string format: date

value_time

Value time (HH:MM:SS), or null. Most banks supply only the date of a transaction, not the time, so expect null in most cases and do not rely on this field for ordering within a day.

string | null

/^\d{2}:\d{2}:\d{2}$/

bank_booking_date

Booking date as reported by the bank (YYYY-MM-DD), or null.

string | null format: date

amount

Negative for outflows, positive for inflows. In the currency of the account.

number

reporting_amount

amount converted to the company currency. Equal to amount for accounts in the company currency.

number

purpose

string

counterpart_name

string

counterpart_iban

string

is_adjusting_entry

boolean

is_payment

boolean

is_leaf_node

boolean

tags

Array<string> | null

comment_count

Present in list responses.

integer

Example

{
  "count": 122,
  "next": "https://app.commitly.com/api/transactions/?category=1003&page=2",
  "previous": null,
  "predicted_unmapped_transactions": false,
  "results": [
    {
      "id": 7002,
      "account": {
        "id": 4002,
        "name": "Checking account",
        "alias": "Main"
      },
      "category": {
        "id": 1003,
        "name": "Rent and leases",
        "description": ""
      },
      "predicted_category": null,
      "invoice": null,
      "parent": null,
      "value_date": "2023-11-15",
      "value_time": null,
      "bank_booking_date": "2023-11-15",
      "amount": -1350,
      "reporting_amount": -1350,
      "purpose": "Office rent November",
      "counterpart_name": "Example Property GmbH",
      "counterpart_iban": "",
      "is_adjusting_entry": false,
      "is_payment": true,
      "is_leaf_node": true,
      "tags": null,
      "comment_count": 0
    },
    {
      "id": 7003,
      "account": {
        "id": 4002,
        "name": "Checking account",
        "alias": "Main"
      },
      "category": {
        "id": 1004,
        "name": "Uncategorized outflows",
        "description": ""
      },
      "predicted_category": {
        "id": 1003,
        "name": "Rent and leases",
        "slug": "",
        "description": "",
        "type": "EX",
        "order": 11,
        "date_created": "2020-10-30T10:04:03.952090Z",
        "is_default": false,
        "is_obsolete": false,
        "lft": 104,
        "rght": 105,
        "tree_id": 156,
        "level": 5,
        "tenant": 19,
        "company": 1423,
        "parent": 1005,
        "source": 129
      },
      "invoice": null,
      "parent": null,
      "value_date": "2023-12-26",
      "value_time": null,
      "bank_booking_date": "2023-12-26",
      "amount": -99.99,
      "reporting_amount": -99.99,
      "purpose": "Invoice 5/12346",
      "counterpart_name": "Example Hosting AG",
      "counterpart_iban": "",
      "is_adjusting_entry": false,
      "is_payment": true,
      "is_leaf_node": true,
      "tags": null,
      "comment_count": 0
    }
  ]
}

401

The access token is invalid or has expired. Request a new token. The message is localized (see Accept-Language).

application/json

object

detail

required

Error message.

string

code

Present only if the company’s edition does not include the function; value billing_plan_permission_denied.

string

Example

{
  "detail": "Invalid token."
}

Headers

WWW-Authenticate

string

Authentication scheme, Bearer.

Example

Bearer

403

No access token was sent, or the credentials are not allowed to call this endpoint. If the company’s COMMITLY edition does not include the requested function, the body additionally contains "code": "billing_plan_permission_denied".

application/json

object

detail

required

Error message.

string

code

Present only if the company’s edition does not include the function; value billing_plan_permission_denied.

string

Example

{
  "detail": "User must be authenticated to access this resource."
}