List bank transactions

Returns a list of bank transactions for the specified business.

GET /v1/businesses/{businessId}/bank-transactions

List bank transactions

cURL

curl --request GET \
  --url https://sandbox.layerfi.com/v1/businesses/{businessId}/bank-transactions \
  --header 'Authorization: Bearer <token>'

200

[
  {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "business_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "source": "UNIT",
    "source_transaction_id": "g4DlKyjXqGH3Kp5XlaWMtwLRrE4Z9AiE8B4Ko",
    "source_account_id": "Aaoy8G7VXZHVeqNoL1GvcmkPdqpLRWi9NArdG",
    "imported_at": "2023-11-07T05:31:56Z",
    "date": "2023-11-07T05:31:56Z",
    "direction": "CREDIT",
    "amount": 123,
    "counterparty_name": "WeWork",
    "description": "WeWork monthly rent payment",
    "account_name": "Plaid Checking",
    "categorizationStatus": "PENDING",
    "category": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "category": "RENT",
      "display_name": "Rent",
      "stable_name": "RENT"
    },
    "categorization_method": "SMS",
    "projected_income_category": "REVENUE",
    "suggested_matches": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "matchType": "TRANSFER",
        "details": {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "amount": 123,
          "date": "2023-11-07T05:31:56Z",
          "description": "Transfer from SavingsAccount to CheckingAccount"
        }
      }
    ],
    "match": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "match_type": "TRANSFER",
      "bank_transaction": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "date": "2023-11-07T05:31:56Z",
        "amount": 123,
        "business_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "source": "UNIT",
        "source_transaction_id": "g4DlKyjXqGH3Kp5XlaWMtwLRrE4Z9AiE8B4Ko",
        "source_account_id": "Aaoy8G7VXZHVeqNoL1GvcmkPdqpLRWi9NArdG",
        "imported_at": "2023-11-07T05:31:56Z",
        "direction": "CREDIT",
        "counterparty_name": "WeWork",
        "description": "WeWork monthly rent payment",
        "account_name": "Plaid Checking",
        "categorizationStatus": "PENDING",
        "memo": "<string>",
        "metadata": {
          "custom_field": "value",
          "any valid json": "below 1kb",
          "nested": {
            "meaning of life": 42,
            "array": []
          }
        },
        "reference_number": "<string>"
      },
      "details": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "amount": 123,
        "date": "2023-11-07T05:31:56Z",
        "description": "Transfer from SavingsAccount to CheckingAccount"
      }
    },
    "transaction_tags": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "key": "ExampleTagKey",
        "value": "ExampleTagValue",
        "dimension_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "definition_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "dimension_display_name": "<string>",
        "value_display_name": "<string>",
        "archived_at": "2023-11-07T05:31:56Z"
      }
    ],
    "memo": "<string>",
    "metadata": {
      "custom_field": "value",
      "any valid json": "below 1kb",
      "nested": {
        "meaning of life": 42,
        "array": []
      }
    },
    "reference_number": "<string>"
  }
]

Transactions can be filtered by:

• Date range (start_date, end_date)
• Direction (direction)
• Categorization status (categorization_status, categorized, is_matched)
• Category (category)
• Amount range (amount_min, amount_max)
• Description (description_filter, description_filter_regex)
• Merchant name (merchant_name_filter, merchant_name_filter_regex)
• Memo (memo, memo_contains)
• Reference number (reference_number, reference_numbers)
• External account (external_account_ids)
• External transaction ID (external_ids)
• Customer (customer_id, customer_external_id)
• Vendor (vendor_id, vendor_external_id)
• Counterparty (counterparty_id, has_counterparty)
• Tag (tag_key, tag_values)
• Free-text search (q)

Filtering by categorization status

Transactions can be categorized in three ways:

• Standard categorization
• Split transactions
• Matched transactions

To filter categorized vs. uncategorized transactions (e.g. get all uncategorized transactions), we recommend you use the categorized query parameter.

To filter categorized based on their categorization status, we recommend you use the categorization_status query parameter.

Sorting

You can use sort_by query parameter to sort transactions by date, amount, counterparty name, or description. This defaults sorting by date in ascending order.

You can use sort_order query parameter to sort transactions in ascending or descending order. This defaults to ascending order.

Pagination

See Pagination for cursor and limit behavior.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Content-Type · string

Content-Type must be set to application/json.

Path Parameters

businessId · string · required

The UUID of the business to fetch bank transactions for.

Query Parameters

reference_number · string

Filter by exact reference number match. Returns only records with this exact reference number.

reference_numbers · string

Comma-separated list of reference numbers to filter transactions. Only transactions with reference numbers matching any value in this list will be returned.

start_date · string<date-time>

The start date of the transaction range to fetch.

end_date · string<date-time>

The end date of the transaction range to fetch.

direction · enum<string>

The direction of the transaction to fetch.

Available options: INFLOW, OUTFLOW

categorization_status · enum<string>

The categorization status of the transaction to fetch. If you wish to see all uncategorized transactions, see categorized=false query parameter.

Available options: PENDING, READY_FOR_INPUT, CATEGORIZED, SPLIT, MATCHED

amount_min · integer<int64>

The minimum amount of the transaction to fetch.

amount_max · integer<int64>

The maximum amount of the transaction to fetch.

description_filter · string

Case-insensitive substring to search for in transaction descriptions (contains match, not exact equality).

description_filter_regex · string

Regex to search for in description transactions. Regex will be parsed exactly as given and an error will be returned if the regex is invalid.

external_account_ids · string

Comma-separated list of external account (e.g. Plaid account) IDs. This will filter for bank transactions within the provided list of accounts.

memo · string

Filter transactions by exact memo match.

memo_contains · string

Filter transactions where memo contains this substring.

customer_id · string<uuid>

UUID of the customer to filter transactions by.

customer_external_id · string

External ID of the customer to filter transactions by.

vendor_id · string<uuid>

UUID of the vendor to filter transactions by.

vendor_external_id · string

External ID of the vendor to filter transactions by.

is_matched · boolean

Filter transactions by whether they are matched (true) or not matched (false).

category · string

Filter transactions by category identifier or stable name.

categorized · boolean

Filter transactions by whether they are categorized (single categorization, split transactions, or matched transactions) or not categorized (pending, under review, ready for input).

merchant_name_filter · string

Substring to search for in merchant name. Only exact matches will be returned.

merchant_name_filter_regex · string

Regex to search for in merchant name. Regex will be parsed exactly as given and an error will be returned if the regex is invalid.

sort_by · enum<string> · default: date

Sort key used for pagination ordering. name corresponds to transaction description text (for Plaid, this is the Plaid transaction name field). Defaults to date.

Available options: date, amount, counterparty_name, name

sort_order · enum<string> · default: ASC

Sort direction for sort_by. Use ASC or DESC. Defaults to ASC.

Available options: ASC, DESC

external_ids · string

Comma-separated list of external transaction IDs (the upstream provider's identifier). Only transactions whose external ID matches one of the supplied values will be returned.

counterparty_id · string<uuid>

UUID of a bank transaction counterparty. Only transactions associated with this counterparty will be returned.

has_counterparty · boolean

If true, only transactions that have a counterparty assigned are returned. If false, only transactions without a counterparty are returned.

q · string

General-purpose search query. The value is matched against transaction descriptions, and is also parsed for an optional signed amount (e.g. +1234 to find inflows of $12.34, -1234 to find outflows) and category names from the chart of accounts.

tag_key · string

Tag key to filter transactions by. Must be supplied together with tag_values. Only transactions tagged with the given key/value pair will be returned.

tag_values · string[]

Tag values to filter transactions by, paired with tag_key. Provide one or more values by repeating the query parameter (e.g. tag_values=foo&tag_values=bar). Required when tag_key is supplied.

Response

200

application/json

id · string<uuid>

Unique identifier of the bank transaction.

business_id · string<uuid>

Unique identifier of the business the bank transaction is associated with.

source · enum<string>

Source of the transaction.

Available options: UNIT, PLAID, API, STRIPE, CUSTOM

source_transaction_id · string

External transaction ID from the source platform (e.g, Plaid transaction ID).

Example:

"g4DlKyjXqGH3Kp5XlaWMtwLRrE4Z9AiE8B4Ko"

source_account_id · string

External account ID from the source platform (e.g, Plaid account ID).

Example:

"Aaoy8G7VXZHVeqNoL1GvcmkPdqpLRWi9NArdG"

imported_at · string<date-time>

Timestamp when the transaction was imported.

date · string<date-time>

Date of the transaction.

direction · enum<string>

Direction of the transaction.

Available options: CREDIT, DEBIT

amount · integer<int64>

Transaction amount in cents.

counterparty_name · string | null

Name of the transaction counterparty.

Example:

"WeWork"

description · string | null

Description of the transaction.

Example:

"WeWork monthly rent payment"

account_name · string | null

Name of the bank account.

Example:

"Plaid Checking"

categorizationStatus · enum<string>

The status of the transaction’s categorization in Layer’s systems.

Available options: PENDING, READY_FOR_INPUT, CATEGORIZED, SPLIT, LAYER_REVIEW, JOURNALING, MATCHED

category · Account · object

The category assigned to the transaction. Only populated for transactions that have a finalized category.

Account

Exclusion

Split

Show child attributes

categorization_method · enum<string>

The method used to classify the transaction.

Available options: SMS, API, LAYER_AUTO, LAYER_MANUAL

projected_income_category · enum<string>

Available options: REVENUE, EXPENSE, EXCLUDE

suggested_matches · object[]

Show child attributes

match · object

Show child attributes

transaction_tags · object[]

Show child attributes

memo · string | null

Memo for any text you would like to associate with the bank transaction (for example, to display to end users).

metadata · object

Arbitrary custom metadata in JSON format with a size limit of 1KB.

Example:

{
  "custom_field": "value",
  "any valid json": "below 1kb",
  "nested": { "meaning of life": 42, "array": [] }
}

reference_number · string | null

Any (typically user-visible) identifier you would like to associate with the bank transaction. Can be used to filter when listing bank transactions.