Skip to main content
PUT
/
v1
/
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"
        }
      }'

{
  "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":{

  }
}
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: Category or Split

Either a Category or a Split may be provided. Splits are 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.

​
Category

Category payloads should have a type field and a category field. This category field can be any Account Identifier. The available categories can be fetched using the Get Chart of Accounts endpoint.

​
Option 1: Payload using a StableName

​
type
enum
required
Set to Category when categorizing the transaction as a single (non-split) category.
​
category
enum
required

​
Option 2: Payload using an AccountId

​
type
enum
required
Set to Category when categorizing the transaction as a single (non-split) category.
​
category
enum
required

​
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

​
type
enum
required
Set to Split when categorizing the transaction as a single (non-split) category.
​
entries
array
required
Array of entries consisting of a category and an amount.

​
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"
        }
      }'

{
  "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":{

  }
}

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).

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

​
category
Account ID · object

A single-category classification to apply to the full transaction amount.

Response

​
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.