Categorize bank transaction

curl -X PUT https://sandbox.layerfi.com/v1/businesses/863ed926-e30d-40f4-8e7e-b0d5387ce4fb/bank-transactions/67cee0d8-3b8e-4b4b-a857-78ce3bb1d895/categorize \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "Category",
        "category": {
          "type": "StableName",
          "stable_name": "MEALS"
        }
      }'

curl -X PUT https://sandbox.layerfi.com/v1/businesses/863ed926-e30d-40f4-8e7e-b0d5387ce4fb/bank-transactions/67cee0d8-3b8e-4b4b-a857-78ce3bb1d895/categorize \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "Category",
        "category": {
          "type": "AccountId",
          "id": "5b83ccb3-bdb3-42ab-8e88-c2222bfa97df"
        }
      }'

curl -X PUT https://sandbox.layerfi.com/v1/businesses/863ed926-e30d-40f4-8e7e-b0d5387ce4fb/bank-transactions/67cee0d8-3b8e-4b4b-a857-78ce3bb1d895/categorize \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Split",
    "entries": [
        {
            "category": {
                "type": "StableName",
                "stable_name": "MEALS"
            },
            "amount": 4250
        },
        {
            "category": {
                "type": "StableName",
                "stable_name": "BUSINESS_TRAVEL"
            },
            "amount": 6000
        }
    ]
  }'

{
  "data":{
    "id":"c63a7a21-d6d7-4d3a-b8f3-e419161a9516",
    "type":"Bank_Transaction",
    "transaction_type":"Book",
    "business_id":"cfee5365-dcc3-425e-b403-cc9568f7121e",
    "source":"API",
    "source_transaction_id":"11111114",
    "source_account_id":"111113",
    "imported_at":"2023-06-07T00:48:25.784724Z",
    "date":"2023-05-10T14:13:07Z",
    "direction":"DEBIT",
    "amount":5670,
    "counterparty_name":"Home Depot",
    "description":"HOMEDEPOT MI59",
    "categorization_status":"CATEGORIZED",
    "category":{
      "category":"SUPPLIES",
      "display_name":"Supplies"
    },
    "categorization_method":"LAYER_AUTO",
    "categorization_flow":{
      "type":"ASK_FROM_SUGGESTIONS",
      "categories":[
        {
          "category":"SUPPLIES",
          "display_name":"Supplies"
        },
        {
          "category":"EQUIPMENT",
          "display_name":"Business equipment"
        },
        {
          "category":"MARKETING",
          "display_name":"Marketing expenses"
        }
      ]
    }
  },
  "meta":{

  }
}

{
  "data": {
    "type": "Bank_Transaction",
    "id": "56759ace-1b5a-47ca-9271-94bf4b2c1005",
    "business_id": "96d483a3-fa80-46a1-a6cb-41d8120f7874",
    "source": "PLAID",
    "source_transaction_id": "test-id-1",
    "source_account_id": "account-1",
    "imported_at": "2024-07-15T20:02:03.167163Z",
    "date": "2024-07-15T20:02:02.965531Z",
    "direction": "DEBIT",
    "amount": 10250,
    "counterparty_name": "Test counterparty",
    "description": null,
    "account_name": "Default Test Client Banking",
    "categorization_status": "SPLIT",
    "category": {
      "type": "Split_Categorization",
      "entries": [
        {
          "amount": 4250,
          "category": {
            "id": "fa30634d-9ebe-42bf-a99f-0fff97f8b8e9",
            "stable_name": "MEALS",
            "category": "fa30634d-9ebe-42bf-a99f-0fff97f8b8e9",
            "display_name": "Meals"
          }
        },
        {
          "amount": 6000,
          "category": {
            "id": "4bcf9027-532e-4c9e-b030-b5cc3264fdf8",
            "stable_name": "BUSINESS_TRAVEL",
            "category": "4bcf9027-532e-4c9e-b030-b5cc3264fdf8",
            "display_name": "Business travel"
          }
        }
      ]
    },
    "categorization_method": "API",
    "categorization_flow": null,
    "projected_income_category": "EXPENSE",
    "suggested_matches": [],
    "match": null,
    "transaction_tags": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "key": "department",
        "value": "sales",
        "dimension_display_name": "Department",
        "value_display_name": "Sales Team",
        "dimension_id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
        "definition_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
        "created_at": "2024-02-27T02:16:40.389772Z",
        "updated_at": "2024-02-27T02:16:40.389772Z",
        "deleted_at": null,
        "archived_at": null
      }
    ]
  }
}

{
  "data": {
    "type": "Bank_Transaction",
    "id": "67cee0d8-3b8e-4b4b-a857-78ce3bb1d895",
    "business_id": "cfee5365-dcc3-425e-b403-cc9568f7121e",
    "source": "API",
    "source_transaction_id": "11111113",
    "source_account_id": "111113",
    "imported_at": "2023-06-07T00:42:08.664543Z",
    "date": "2023-05-15T14:13:07Z",
    "direction": "DEBIT",
    "amount": 8026,
    "counterparty_name": "SUNOCO",
    "description": null,
    "categorization_status": "CATEGORIZED",
    "category": {
      "category": "FUEL",
      "display_name": "Fuel"
    },
    "update_categorization_rules_suggestion": {
      "type": "Create_Categorization_Rule_For_Counterparty",
      "id": "b3488b6a-c7b4-4d2a-a8c7-7d15f9942ed4",
      "created_at": "2025-02-14T17:22:01Z",
      "status": "PENDING",
      "counterparty": {
        "id": "f1664961-43d8-42f1-9a6d-c6c32a9f0adf",
        "name": "SUNOCO"
      },
      "suggestion_prompt": "Would you like to create a rule for outbound SUNOCO transactions?",
      "new_rule": {
        "apply_retroactively": true,
        "created_by_suggestion_id": "b3488b6a-c7b4-4d2a-a8c7-7d15f9942ed4",
        "counterparty_filter": "f1664961-43d8-42f1-9a6d-c6c32a9f0adf",
        "category": {
          "type": "StableName",
          "stable_name": "FUEL"
        },
        "bank_direction_filter": "DEBIT"
      },
      "transactions_that_will_be_affected": []
    }
  }
}

PUT

businesses

{businessId}

bank-transactions

{transactionId}

categorize

curl -X PUT https://sandbox.layerfi.com/v1/businesses/863ed926-e30d-40f4-8e7e-b0d5387ce4fb/bank-transactions/67cee0d8-3b8e-4b4b-a857-78ce3bb1d895/categorize \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "Category",
        "category": {
          "type": "StableName",
          "stable_name": "MEALS"
        }
      }'

curl -X PUT https://sandbox.layerfi.com/v1/businesses/863ed926-e30d-40f4-8e7e-b0d5387ce4fb/bank-transactions/67cee0d8-3b8e-4b4b-a857-78ce3bb1d895/categorize \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "Category",
        "category": {
          "type": "AccountId",
          "id": "5b83ccb3-bdb3-42ab-8e88-c2222bfa97df"
        }
      }'

curl -X PUT https://sandbox.layerfi.com/v1/businesses/863ed926-e30d-40f4-8e7e-b0d5387ce4fb/bank-transactions/67cee0d8-3b8e-4b4b-a857-78ce3bb1d895/categorize \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Split",
    "entries": [
        {
            "category": {
                "type": "StableName",
                "stable_name": "MEALS"
            },
            "amount": 4250
        },
        {
            "category": {
                "type": "StableName",
                "stable_name": "BUSINESS_TRAVEL"
            },
            "amount": 6000
        }
    ]
  }'

{
  "data":{
    "id":"c63a7a21-d6d7-4d3a-b8f3-e419161a9516",
    "type":"Bank_Transaction",
    "transaction_type":"Book",
    "business_id":"cfee5365-dcc3-425e-b403-cc9568f7121e",
    "source":"API",
    "source_transaction_id":"11111114",
    "source_account_id":"111113",
    "imported_at":"2023-06-07T00:48:25.784724Z",
    "date":"2023-05-10T14:13:07Z",
    "direction":"DEBIT",
    "amount":5670,
    "counterparty_name":"Home Depot",
    "description":"HOMEDEPOT MI59",
    "categorization_status":"CATEGORIZED",
    "category":{
      "category":"SUPPLIES",
      "display_name":"Supplies"
    },
    "categorization_method":"LAYER_AUTO",
    "categorization_flow":{
      "type":"ASK_FROM_SUGGESTIONS",
      "categories":[
        {
          "category":"SUPPLIES",
          "display_name":"Supplies"
        },
        {
          "category":"EQUIPMENT",
          "display_name":"Business equipment"
        },
        {
          "category":"MARKETING",
          "display_name":"Marketing expenses"
        }
      ]
    }
  },
  "meta":{

  }
}

{
  "data": {
    "type": "Bank_Transaction",
    "id": "56759ace-1b5a-47ca-9271-94bf4b2c1005",
    "business_id": "96d483a3-fa80-46a1-a6cb-41d8120f7874",
    "source": "PLAID",
    "source_transaction_id": "test-id-1",
    "source_account_id": "account-1",
    "imported_at": "2024-07-15T20:02:03.167163Z",
    "date": "2024-07-15T20:02:02.965531Z",
    "direction": "DEBIT",
    "amount": 10250,
    "counterparty_name": "Test counterparty",
    "description": null,
    "account_name": "Default Test Client Banking",
    "categorization_status": "SPLIT",
    "category": {
      "type": "Split_Categorization",
      "entries": [
        {
          "amount": 4250,
          "category": {
            "id": "fa30634d-9ebe-42bf-a99f-0fff97f8b8e9",
            "stable_name": "MEALS",
            "category": "fa30634d-9ebe-42bf-a99f-0fff97f8b8e9",
            "display_name": "Meals"
          }
        },
        {
          "amount": 6000,
          "category": {
            "id": "4bcf9027-532e-4c9e-b030-b5cc3264fdf8",
            "stable_name": "BUSINESS_TRAVEL",
            "category": "4bcf9027-532e-4c9e-b030-b5cc3264fdf8",
            "display_name": "Business travel"
          }
        }
      ]
    },
    "categorization_method": "API",
    "categorization_flow": null,
    "projected_income_category": "EXPENSE",
    "suggested_matches": [],
    "match": null,
    "transaction_tags": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "key": "department",
        "value": "sales",
        "dimension_display_name": "Department",
        "value_display_name": "Sales Team",
        "dimension_id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
        "definition_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
        "created_at": "2024-02-27T02:16:40.389772Z",
        "updated_at": "2024-02-27T02:16:40.389772Z",
        "deleted_at": null,
        "archived_at": null
      }
    ]
  }
}

{
  "data": {
    "type": "Bank_Transaction",
    "id": "67cee0d8-3b8e-4b4b-a857-78ce3bb1d895",
    "business_id": "cfee5365-dcc3-425e-b403-cc9568f7121e",
    "source": "API",
    "source_transaction_id": "11111113",
    "source_account_id": "111113",
    "imported_at": "2023-06-07T00:42:08.664543Z",
    "date": "2023-05-15T14:13:07Z",
    "direction": "DEBIT",
    "amount": 8026,
    "counterparty_name": "SUNOCO",
    "description": null,
    "categorization_status": "CATEGORIZED",
    "category": {
      "category": "FUEL",
      "display_name": "Fuel"
    },
    "update_categorization_rules_suggestion": {
      "type": "Create_Categorization_Rule_For_Counterparty",
      "id": "b3488b6a-c7b4-4d2a-a8c7-7d15f9942ed4",
      "created_at": "2025-02-14T17:22:01Z",
      "status": "PENDING",
      "counterparty": {
        "id": "f1664961-43d8-42f1-9a6d-c6c32a9f0adf",
        "name": "SUNOCO"
      },
      "suggestion_prompt": "Would you like to create a rule for outbound SUNOCO transactions?",
      "new_rule": {
        "apply_retroactively": true,
        "created_by_suggestion_id": "b3488b6a-c7b4-4d2a-a8c7-7d15f9942ed4",
        "counterparty_filter": "f1664961-43d8-42f1-9a6d-c6c32a9f0adf",
        "category": {
          "type": "StableName",
          "stable_name": "FUEL"
        },
        "bank_direction_filter": "DEBIT"
      },
      "transactions_that_will_be_affected": []
    }
  }
}

A single transaction can be categorized to a single account or split across multiple accounts. You specify the type of categorization based on the request body.

Request Body: Single Category or Split

All categorizations are either a single Category or a Split.

Category is used to categorize the transaction as a single (non-split) category. This will be the case the vast majority of the time.
Split is used when the transaction’s value should be allocated across multiple categories. This is most commonly the case when multiple items are purchased and those items should be categorized separately.

In the diagram above, Category and Exclusion are both single-category request bodies: they assign the entire transaction to one account identifier. Split is a separate request body type that allocates the transaction’s value across multiple categories.

Split Categorizations

Splits are specified with an array of categorizations, as above, with an amount tied to each category. The total amount must exactly equal the amount of the transaction. Amounts are always specified in positive cents.

Split Payload

enum

required

Set to Split when categorizing the transaction as a single (non-split) category.

array

required

Array of entries consisting of a category and an amount.

Show properties

object

required

The category payload is the same as for non-split categorizations: an AccountId, StableName, or Exclusion payload (see Options 1–3 above).

Show properties (when type = AccountId)

enum

required

AccountId

string

required

The account id.

Show properties (when type = StableName)

enum

required

StableName

string

required

The stable name string.

Show properties (when type = Exclusion)

enum

required

Exclusion

enum

required

Available options are PERSONAL_EXPENSES, PERSONAL_INFLOWS, DUPLICATE_TRANSACTION, or OTHER_EXCLUSION.

int

required

Amount, in cents, to categorize to this portion of the split.

string

Tax code for this split entry. See Tax Code below.

Tax Code

tax_code is an optional field, available on both the Category and Split entry payloads, that assigns a Canada Revenue Agency tax code (e.g. GST, PST, HST, QST) to a categorization.

tax_code is currently only supported for businesses incorporated in Canada (country is CA on the Business object). Providing a tax_code for any other business country will return a 400 error.

string

A tax code value. Must be one of the code values returned in tax_options on the Bank Transaction object for the codes valid on that transaction’s date. Cannot be used together with an Exclusion category.

Category with Tax Code

curl -X PUT https://sandbox.layerfi.com/v1/businesses/863ed926-e30d-40f4-8e7e-b0d5387ce4fb/bank-transactions/67cee0d8-3b8e-4b4b-a857-78ce3bb1d895/categorize \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "Category",
        "category": {
          "type": "StableName",
          "stable_name": "MEALS"
        },
        "tax_code": "GST_PST_BC"
      }'

Rules Suggestion

Responses may include update_categorization_rules_suggestion when Layer recommends creating a reusable categorization rule. For more details, see Categorization Rule Suggestions.

curl -X PUT https://sandbox.layerfi.com/v1/businesses/863ed926-e30d-40f4-8e7e-b0d5387ce4fb/bank-transactions/67cee0d8-3b8e-4b4b-a857-78ce3bb1d895/categorize \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "Category",
        "category": {
          "type": "StableName",
          "stable_name": "MEALS"
        }
      }'

curl -X PUT https://sandbox.layerfi.com/v1/businesses/863ed926-e30d-40f4-8e7e-b0d5387ce4fb/bank-transactions/67cee0d8-3b8e-4b4b-a857-78ce3bb1d895/categorize \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "Category",
        "category": {
          "type": "AccountId",
          "id": "5b83ccb3-bdb3-42ab-8e88-c2222bfa97df"
        }
      }'

curl -X PUT https://sandbox.layerfi.com/v1/businesses/863ed926-e30d-40f4-8e7e-b0d5387ce4fb/bank-transactions/67cee0d8-3b8e-4b4b-a857-78ce3bb1d895/categorize \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Split",
    "entries": [
        {
            "category": {
                "type": "StableName",
                "stable_name": "MEALS"
            },
            "amount": 4250
        },
        {
            "category": {
                "type": "StableName",
                "stable_name": "BUSINESS_TRAVEL"
            },
            "amount": 6000
        }
    ]
  }'

{
  "data":{
    "id":"c63a7a21-d6d7-4d3a-b8f3-e419161a9516",
    "type":"Bank_Transaction",
    "transaction_type":"Book",
    "business_id":"cfee5365-dcc3-425e-b403-cc9568f7121e",
    "source":"API",
    "source_transaction_id":"11111114",
    "source_account_id":"111113",
    "imported_at":"2023-06-07T00:48:25.784724Z",
    "date":"2023-05-10T14:13:07Z",
    "direction":"DEBIT",
    "amount":5670,
    "counterparty_name":"Home Depot",
    "description":"HOMEDEPOT MI59",
    "categorization_status":"CATEGORIZED",
    "category":{
      "category":"SUPPLIES",
      "display_name":"Supplies"
    },
    "categorization_method":"LAYER_AUTO",
    "categorization_flow":{
      "type":"ASK_FROM_SUGGESTIONS",
      "categories":[
        {
          "category":"SUPPLIES",
          "display_name":"Supplies"
        },
        {
          "category":"EQUIPMENT",
          "display_name":"Business equipment"
        },
        {
          "category":"MARKETING",
          "display_name":"Marketing expenses"
        }
      ]
    }
  },
  "meta":{

  }
}

{
  "data": {
    "type": "Bank_Transaction",
    "id": "56759ace-1b5a-47ca-9271-94bf4b2c1005",
    "business_id": "96d483a3-fa80-46a1-a6cb-41d8120f7874",
    "source": "PLAID",
    "source_transaction_id": "test-id-1",
    "source_account_id": "account-1",
    "imported_at": "2024-07-15T20:02:03.167163Z",
    "date": "2024-07-15T20:02:02.965531Z",
    "direction": "DEBIT",
    "amount": 10250,
    "counterparty_name": "Test counterparty",
    "description": null,
    "account_name": "Default Test Client Banking",
    "categorization_status": "SPLIT",
    "category": {
      "type": "Split_Categorization",
      "entries": [
        {
          "amount": 4250,
          "category": {
            "id": "fa30634d-9ebe-42bf-a99f-0fff97f8b8e9",
            "stable_name": "MEALS",
            "category": "fa30634d-9ebe-42bf-a99f-0fff97f8b8e9",
            "display_name": "Meals"
          }
        },
        {
          "amount": 6000,
          "category": {
            "id": "4bcf9027-532e-4c9e-b030-b5cc3264fdf8",
            "stable_name": "BUSINESS_TRAVEL",
            "category": "4bcf9027-532e-4c9e-b030-b5cc3264fdf8",
            "display_name": "Business travel"
          }
        }
      ]
    },
    "categorization_method": "API",
    "categorization_flow": null,
    "projected_income_category": "EXPENSE",
    "suggested_matches": [],
    "match": null,
    "transaction_tags": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "key": "department",
        "value": "sales",
        "dimension_display_name": "Department",
        "value_display_name": "Sales Team",
        "dimension_id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
        "definition_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
        "created_at": "2024-02-27T02:16:40.389772Z",
        "updated_at": "2024-02-27T02:16:40.389772Z",
        "deleted_at": null,
        "archived_at": null
      }
    ]
  }
}

{
  "data": {
    "type": "Bank_Transaction",
    "id": "67cee0d8-3b8e-4b4b-a857-78ce3bb1d895",
    "business_id": "cfee5365-dcc3-425e-b403-cc9568f7121e",
    "source": "API",
    "source_transaction_id": "11111113",
    "source_account_id": "111113",
    "imported_at": "2023-06-07T00:42:08.664543Z",
    "date": "2023-05-15T14:13:07Z",
    "direction": "DEBIT",
    "amount": 8026,
    "counterparty_name": "SUNOCO",
    "description": null,
    "categorization_status": "CATEGORIZED",
    "category": {
      "category": "FUEL",
      "display_name": "Fuel"
    },
    "update_categorization_rules_suggestion": {
      "type": "Create_Categorization_Rule_For_Counterparty",
      "id": "b3488b6a-c7b4-4d2a-a8c7-7d15f9942ed4",
      "created_at": "2025-02-14T17:22:01Z",
      "status": "PENDING",
      "counterparty": {
        "id": "f1664961-43d8-42f1-9a6d-c6c32a9f0adf",
        "name": "SUNOCO"
      },
      "suggestion_prompt": "Would you like to create a rule for outbound SUNOCO transactions?",
      "new_rule": {
        "apply_retroactively": true,
        "created_by_suggestion_id": "b3488b6a-c7b4-4d2a-a8c7-7d15f9942ed4",
        "counterparty_filter": "f1664961-43d8-42f1-9a6d-c6c32a9f0adf",
        "category": {
          "type": "StableName",
          "stable_name": "FUEL"
        },
        "bank_direction_filter": "DEBIT"
      },
      "transactions_that_will_be_affected": []
    }
  }
}

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 that the transaction to categorize belongs to.

transactionId

string

required

The UUID of the bank transaction to categorize.

Body

application/json

Provide either a Category payload (single categorization) or a Split payload (array of entries with category + amount).

Category
Split

Categorization payload for a bank transaction. Use Category for one category, or Split for multiple category entries that sum to the transaction amount.

type

enum<string>

required

Discriminator for a single-category payload.

Available options:

Category

Response

data

object

required

Show child attributes

⌘I

Businesses

Financial Activity

Accounting Reports

Platform Configuration

Activity Metrics

Integrations

Categorize bank transaction

Request Body: Single Category or Split

Category

Option 1: Payload using a StableName

Option 2: Payload using an AccountId

Option 3: Payload using an Exclusion

Split Categorizations

Split Payload

Tax Code

Rules Suggestion

Authorizations

Headers

Path Parameters

Body

Response

​Request Body: Single Category or Split

​Category

​Option 1: Payload using a StableName

​Option 2: Payload using an AccountId

​Option 3: Payload using an Exclusion

​Split Categorizations

​Split Payload

​Tax Code

​Rules Suggestion

Authorizations

Headers

Path Parameters

Body

Response

Request Body: Single Category or Split

Category

Option 1: Payload using a StableName

Option 2: Payload using an AccountId

Option 3: Payload using an Exclusion

Split Categorizations

Split Payload

Tax Code

Rules Suggestion