Skip to main content
POST
/
v1
/
businesses
/
{businessId}
/
bank-transactions
/
bulk-match-or-categorize
Bulk match or categorize
curl --request POST \
  --url https://sandbox.layerfi.com/v1/businesses/{businessId}/bank-transactions/bulk-match-or-categorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "transactions": {
    "7c77e464-2a55-4e48-8d71-4f8d2a30c205": {
      "type": "match",
      "suggested_match_id": "8a6fb574-915d-459a-9f5d-2e0a5cf4d3e0"
    },
    "2fe323fc-2f0a-41bf-8f67-768ec955dc59": {
      "type": "categorize",
      "categorization": {
        "type": "Category",
        "category": {
          "type": "StableName",
          "stable_name": "MEALS"
        }
      }
    }
  },
  "categorization_source": "<string>"
}
'
[
  {
    "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>",
    "update_categorization_rules_suggestion": {
      "type": "Create_Categorization_Rule_For_Counterparty",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "created_at": "2023-11-07T05:31:56Z",
      "new_rule": {
        "name": "<string>",
        "category": {
          "type": "AccountId",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        },
        "suggestion_1": {
          "type": "AccountId",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        },
        "suggestion_2": {
          "type": "AccountId",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        },
        "suggestion_3": {
          "type": "AccountId",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        },
        "apply_retroactively": false,
        "external_id": "<string>",
        "created_by_suggestion_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "merchant_type_filter": "<string>",
        "transaction_description_filter": "<string>",
        "counterparty_filter": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "bank_transaction_type_filter": "REVENUE",
        "bank_direction_filter": "MONEY_IN",
        "amount_min_filter": 123,
        "amount_max_filter": 123
      },
      "suggestion_prompt": "<string>",
      "transactions_that_will_be_affected": [
        {
          "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",
          "memo": "<string>",
          "metadata": {
            "custom_field": "value",
            "any valid json": "below 1kb",
            "nested": {
              "meaning of life": 42,
              "array": []
            }
          },
          "reference_number": "<string>"
        }
      ],
      "status": "PENDING",
      "business_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "business_name": "<string>",
      "counterparty": {},
      "accepted_at": "2023-11-07T05:31:56Z",
      "dismissed_at": "2023-11-07T05:31:56Z"
    }
  }
]

Documentation Index

Fetch the complete documentation index at: https://docs.layerfi.com/llms.txt

Use this file to discover all available pages before exploring further.

A single request can apply match actions, categorize actions, or both. You specify the action type per transaction in the transactions object.

ā€‹
Request Body

Each key in transactions is a transaction id, and each value is either a Match or a Categorize action.

ā€‹
Match

Use suggested_match_id to confirm a suggested match for that transaction. 
{
    "transactions": {
        "transaction_uuid": {
            "type": "match",
            "suggested_match_id": "suggested_match_uuid"
        },
        "next_transaction_uuid": {
            "type": "match",
            "suggested_match_id": "suggested_match_uuid"
        },
        // ...
    }
}

ā€‹
Categorize

Use categorization to categorize that transaction (single category or split). 
{
    "transactions": {
        "transaction_uuid": {
            "type": "categorize",
            "categorization": {
                "type": "Category",
                "category": {
                    "type": "StableName",
                    "stable_name": "MEALS"
                }
            }
        },
        "next_transaction_uuid": {
            // ...
        },
        // ...
    }
}
For more variations for categorization payloads, see Category payload.

ā€‹
Response

Returns the updated Bank Transactions for all processed transactions with the additional fields for rules suggestions.

ā€‹
Rule Suggestions

Transactions that have been categorized (i.e. taken a category payload) may include update_categorization_rules_suggestion. Transactions processed with a match action do not return rule suggestions. For full behavior and integration guidance, see Categorization Rule Suggestions.

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<uuid>
required

The UUID of the business.

Body

application/json
ā€‹
transactions
object
required

Map of transaction IDs to either a match action or a categorize action.

Example:
{
  "7c77e464-2a55-4e48-8d71-4f8d2a30c205": {
    "type": "match",
    "suggested_match_id": "8a6fb574-915d-459a-9f5d-2e0a5cf4d3e0"
  },
  "2fe323fc-2f0a-41bf-8f67-768ec955dc59": {
    "type": "categorize",
    "categorization": {
      "type": "Category",
      "category": {
        "type": "StableName",
        "stable_name": "MEALS"
      }
    }
  }
}
ā€‹
categorization_source
string

Optional source to attribute the request to. Accepted values for this endpoint are API_DIRECT, API_FROM_COMPONENT, LAYER_BOOKKEEPING, API_CONFIRM_MATCH_DIRECT, API_CONFIRM_MATCH_FROM_COMPONENT, and LAYER_BOOKKEEPING_CONFIRM_MATCH.

Response

Matched and categorized transactions.

ā€‹
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.

ā€‹
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[]
ā€‹
match
object
ā€‹
transaction_tags
object[]
ā€‹
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.

ā€‹
update_categorization_rules_suggestion
object

Rule suggestion returned after categorization when Layer recommends creating a reusable categorization rule.