> ## 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. # Bulk categorize transactions > Categorize multiple bank transactions in a single request. Each transaction in the request must include a transaction_id and a categorization object specifying how to categorize it. ## OpenAPI ````yaml post /v1/businesses/{businessId}/bank-transactions/bulk-categorize openapi: 3.0.1 info: title: API version: latest servers: [] security: - BearerAuth: [] tags: [] externalDocs: url: / paths: /v1/businesses/{businessId}/bank-transactions/bulk-categorize: post: tags: [] summary: Bulk categorize transactions description: >- Categorize multiple bank transactions in a single request. Each transaction in the request must include a transaction_id and a categorization object specifying how to categorize it. operationId: business.bank-transactions.bulk-categorize.post parameters: - name: businessId in: path description: The UUID of the business. required: true schema: type: string format: uuid - name: Content-Type in: header description: Content-Type must be set to application/json. schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/BulkCategorizationRequest' responses: '200': description: Bulk categorization results. headers: {} content: application/json: schema: $ref: '#/components/schemas/BulkCategorizationResponse' '400': description: Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: Business or transaction not found. content: application/json: schema: $ref: '#/components/schemas/ApiError' deprecated: false components: schemas: BulkCategorizationRequest: type: object required: - transactions properties: transactions: type: array description: List of transactions to categorize. items: $ref: '#/components/schemas/TransactionCategorizationInput' BulkCategorizationResponse: type: object properties: results: type: array description: Results for each transaction categorization. items: $ref: '#/components/schemas/CategorizationResult' ApiError: type: object description: An error object returned in API error responses. properties: type: $ref: '#/components/schemas/ApiErrorType' description: >- A fixed category for the error, helpful for categorizing and processing errors. description: type: string description: A human-readable error description. error_enum: $ref: '#/components/schemas/ApiEnumErrorType' description: >- A stable, machine-readable identifier for programmatically handling specific error conditions. Only present for 4xx client errors—not included for 5xx server errors. Use this instead of parsing the description field, as enum values remain stable across API versions. nullable: true meta: type: object description: Optional additional information about the error. nullable: true required: - type - description TransactionCategorizationInput: type: object required: - transaction_id - categorization properties: transaction_id: type: string format: uuid description: The UUID of the transaction to categorize. categorization: $ref: '#/components/schemas/BankTransactionCategorization' CategorizationResult: type: object properties: transaction_id: type: string format: uuid description: The UUID of the transaction. success: type: boolean description: Whether the categorization was successful. transaction: $ref: '#/components/schemas/ApiBankTransactionWithRuleSuggestion' description: Categorized bank transaction. Present when success is true. error: type: string description: Error message if categorization failed. ApiErrorType: type: string enum: - ResourceArchived - AuthFailure - Plaid - Stripe - InvalidState - ResourceNotFound - InvalidParameters - JsonSerialization - Unknown - BadRequest - PaginationCursor - Conflict - LedgerOperationFailed ApiEnumErrorType: type: string description: >- Stable enum values for programmatic error handling. Only present in 4xx error responses. enum: - AccessCodeInvalid - BalanceSheetDoesNotBalance - BalanceSheetMissingAccount - BankStatementParserError - BillStateError - BulkCategorizeFailure - BulkMatchFailure - BusinessTaskAlreadyCompleted - BusinessTaskDeleted - CalendlyOAuthError - CallBookingError - CantUpdateTransactionInCustomerPayout - CantUpdateTransactionInVendorPayout - CheckPayrollConfigNotFound - CheckPayrollServiceNotFound - ClerkUserAlreadyExists - ConflictingQueryParams - CustomAccountAlreadyExists - CustomTransactionCsvParsingError - CustomTransactionUploadFailure - CustomerPayoutInputFormatError - DoesNotMatchExistingEntity - EmptyBatchRequest - ExpenseParserError - ExternalAccountBalanceReconciliationError - ExternalIdConflict - InvalidCategory - InvalidEffectiveDate - InvalidLedgerOperation - InvalidMonthlyAverageRange - InvalidMultiPartRequest - InvalidPaginationCursor - InvalidPayload - InvoiceDeleted - InvoiceNotFound - InvoiceReferenceMismatch - InvoiceStateError - ManualRateLimit - MultipleTagKeyFiltersUnsupported - NoCognitoUserFound - NoOpeningBalanceFound - NotYetReconciled - OnePasswordApiError - OnePasswordItemNotFound - OnePasswordVaultNotFound - OpenAICategorizationError - PaymentLinkInvalid - PayrollStateError - PeriodIsClosed - PeriodNotClosed - PhoneNumberAlreadyRegistered - PlaidApiError - PlaidConnectionBroken - PlaidCreateLinkTokenError - PlaidCredentialsNotConfigured - PlaidExchangePublicTokenError - PlaidGetInstitutionByIdError - PlaidGetItemError - PlaidInvalidEnvironment - PlaidItemAlreadyExists - PlaidItemNotFound - PlaidProcessorApiError - PlaidUnlinkItemError - QueryParamFormat - QueryParamMissing - QuickbooksBrokenConnection - QuickbooksConnectionAlreadyExists - QuickbooksConnectionAlreadySyncing - QuickbooksConnectionMissing - QuickbooksConnectionNotActivated - QuickbooksInvalidRequest - QuickbooksInvalidState - QuickbooksNoMatchingAccount - QuickbooksNonPostingAccountType - QuickbooksNotConfigured - QuickbooksOAuthCallbackInvalid - QuickbooksOAuthError - QuickbooksTokenExpired - ResourceArchived - ScheduleCNotConfigured - SmsNotEnabled - SpecifiedBadRequest - SpecifiedIdNotFound - SplitTransactionError - StepEvaluationBadRequest - StripeConnectAccountIdNotFound - StripeCredentialsNotConfigured - StripeGetBalanceForConnectAccountFailure - StripeRedirectOrRefreshUrlNotConfigured - TagFilterNotFound - UnexpectedQueryParam - UnitAccountsInUse - WrongAnswerType BankTransactionCategorization: description: >- Categorization payload for a bank transaction. Use `Category` for one category, or `Split` for multiple category entries that sum to the transaction amount. discriminator: propertyName: type mapping: Category: $ref: '#/components/schemas/Category' Split: $ref: '#/components/schemas/ApiSplitInput' oneOf: - $ref: '#/components/schemas/Category' title: Category - $ref: '#/components/schemas/ApiSplitInput' title: Split ApiBankTransactionWithRuleSuggestion: allOf: - $ref: '#/components/schemas/ApiBankTransaction' - type: object properties: update_categorization_rules_suggestion: allOf: - $ref: >- #/components/schemas/ApiCreateCategorizationRuleForCounterpartySuggestion nullable: true description: >- Rule suggestion returned after categorization when Layer recommends creating a reusable categorization rule. Category: type: object description: Single-category categorization payload. required: - type - category properties: type: type: string enum: - Category description: Discriminator for a single-category payload. category: $ref: '#/components/schemas/BankTransactionClassification' description: >- A single-category classification to apply to the full transaction amount. ApiSplitInput: type: object description: >- Split categorization payload. Provide one or more entries whose amounts sum exactly to the transaction amount. required: - type - entries properties: type: type: string enum: - Split description: Discriminator for a split categorization payload. entries: type: array items: $ref: '#/components/schemas/SplitEntry' description: Split entries. Each entry includes a category and amount in cents. ApiBankTransaction: type: object properties: id: type: string format: uuid description: Unique identifier of the bank transaction. business_id: type: string format: uuid description: >- Unique identifier of the business the bank transaction is associated with. source: $ref: '#/components/schemas/TransactionSource' description: Source of the transaction. source_transaction_id: type: string description: >- External transaction ID from the source platform (e.g, Plaid transaction ID). example: g4DlKyjXqGH3Kp5XlaWMtwLRrE4Z9AiE8B4Ko source_account_id: type: string description: >- External account ID from the source platform (e.g, Plaid account ID). example: Aaoy8G7VXZHVeqNoL1GvcmkPdqpLRWi9NArdG imported_at: type: string format: date-time description: Timestamp when the transaction was imported. date: type: string format: date-time description: Date of the transaction. direction: $ref: '#/components/schemas/BankTransactionDirection' description: Direction of the transaction. amount: type: integer format: int64 description: Transaction amount in cents. counterparty_name: type: string nullable: true description: Name of the transaction counterparty. example: WeWork description: type: string nullable: true description: Description of the transaction. example: WeWork monthly rent payment account_name: type: string nullable: true description: Name of the bank account. example: Plaid Checking categorizationStatus: $ref: '#/components/schemas/CategorizationStatus' description: The status of the transaction’s categorization in Layer’s systems. category: $ref: '#/components/schemas/ApiCategorization' description: >- The category assigned to the transaction. Only populated for transactions that have a finalized category. categorization_method: $ref: '#/components/schemas/ClassifierAgent' description: The method used to classify the transaction. projected_income_category: $ref: '#/components/schemas/ProjectedIncomeCategory' suggested_matches: type: array items: $ref: '#/components/schemas/ApiSuggestedMatch' match: $ref: '#/components/schemas/ApiMatch' transaction_tags: type: array items: $ref: '#/components/schemas/ApiTag' memo: type: string nullable: true description: >- Memo for any text you would like to associate with the bank transaction (for example, to display to end users). metadata: $ref: '#/components/schemas/PlatformDefinedJson' nullable: true description: Arbitrary custom metadata in JSON format with a size limit of 1KB. reference_number: type: string nullable: true description: >- Any (typically user-visible) identifier you would like to associate with the bank transaction. Can be used to filter when listing bank transactions. ApiCreateCategorizationRuleForCounterpartySuggestion: type: object description: >- Consumer-facing rule suggestion for creating a categorization rule for a specific counterparty. properties: type: type: string enum: - Create_Categorization_Rule_For_Counterparty id: type: string format: uuid created_at: type: string format: date-time new_rule: $ref: '#/components/schemas/CreateCategorizationRuleParams' business_id: type: string format: uuid nullable: true business_name: type: string nullable: true counterparty: type: object description: Counterparty associated with the suggestion. additionalProperties: true suggestion_prompt: type: string transactions_that_will_be_affected: type: array items: $ref: '#/components/schemas/ApiBankTransactionDataOnly' accepted_at: type: string format: date-time nullable: true dismissed_at: type: string format: date-time nullable: true status: type: string enum: - PENDING - ACCEPTED - REJECTED required: - type - id - created_at - suggestion_prompt - new_rule - transactions_that_will_be_affected - status BankTransactionClassification: discriminator: propertyName: type mapping: AccountId: $ref: '#/components/schemas/AccountId' StableName: $ref: '#/components/schemas/AccountStableName' Exclusion: $ref: '#/components/schemas/Exclusion' oneOf: - $ref: '#/components/schemas/AccountId' title: Account ID - $ref: '#/components/schemas/AccountStableName' title: Account Stable Name - $ref: '#/components/schemas/Exclusion' title: Exclusion SplitEntry: type: object properties: amount: type: integer format: int64 description: Amount in cents for this split entry. category: $ref: '#/components/schemas/BankTransactionClassification' description: Category classification for this split entry amount. TransactionSource: type: string enum: - UNIT - PLAID - API - STRIPE - CUSTOM BankTransactionDirection: type: string enum: - CREDIT - DEBIT CategorizationStatus: type: string enum: - PENDING - READY_FOR_INPUT - CATEGORIZED - SPLIT - LAYER_REVIEW - JOURNALING - MATCHED ApiCategorization: description: Base schema for categorization of API entities. oneOf: - $ref: '#/components/schemas/AccountCategorization' title: Account - $ref: '#/components/schemas/ExclusionCategorization' title: Exclusion - $ref: '#/components/schemas/SplitCategorization' title: Split discriminator: propertyName: type mapping: Account: $ref: '#/components/schemas/AccountCategorization' Exclusion: $ref: '#/components/schemas/ExclusionCategorization' Split_Categorization: $ref: '#/components/schemas/SplitCategorization' ClassifierAgent: type: string enum: - SMS - API - LAYER_AUTO - LAYER_MANUAL ProjectedIncomeCategory: type: string enum: - REVENUE - EXPENSE - EXCLUDE ApiSuggestedMatch: type: object properties: id: type: string format: uuid description: Layer's identifier for the suggested match. matchType: $ref: '#/components/schemas/MatchType' description: Type of the matched object. details: $ref: '#/components/schemas/ApiMatchDetails' description: Details of the suggested match. ApiMatch: type: object properties: id: type: string format: uuid description: Layer's UUID for the match. match_type: $ref: '#/components/schemas/MatchType' description: Type of the object to match. bank_transaction: $ref: '#/components/schemas/ApiBankTransactionInterface' details: $ref: '#/components/schemas/ApiMatchDetails' ApiTag: type: object properties: id: type: string format: uuid description: ID for the tag. key: type: string description: Key for the tag. example: ExampleTagKey dimension_display_name: type: string nullable: true description: Display name for the tag dimension. value: type: string description: Value for the tag. example: ExampleTagValue value_display_name: type: string nullable: true description: Display name for the tag value definition. dimension_id: type: string format: uuid description: ID of the tag dimension this tag belongs to. definition_id: type: string format: uuid description: ID of the tag value definition. archived_at: type: string format: date-time nullable: true description: When the tag was archived. required: - id - key - value - dimension_id - definition_id PlatformDefinedJson: type: object description: Arbitrary JSON data defined by the caller, with a 1KB size constraint. additionalProperties: true example: custom_field: value any valid json: below 1kb nested: meaning of life: 42 array: [] CreateCategorizationRuleParams: type: object description: >- Parameters for creating or updating a categorization rule. At least one filter must be specified. properties: name: type: string description: Optional name for the rule. category: $ref: '#/components/schemas/BankTransactionClassification' suggestion_1: $ref: '#/components/schemas/BankTransactionClassification' suggestion_2: $ref: '#/components/schemas/BankTransactionClassification' suggestion_3: $ref: '#/components/schemas/BankTransactionClassification' apply_retroactively: type: boolean default: false description: Whether to apply this rule to existing uncategorized transactions. external_id: type: string description: >- External identifier for idempotency. Used for create/upsert operations. created_by_suggestion_id: type: string format: uuid description: UUID of the suggestion that created this rule (if applicable). merchant_type_filter: type: string description: Regex pattern to match against merchant type (minimum 7 characters). minLength: 7 transaction_description_filter: type: string description: >- Regex pattern to match against transaction description (minimum 7 characters). minLength: 7 counterparty_filter: type: string format: uuid description: UUID of a specific counterparty (merchant/vendor) to match. bank_transaction_type_filter: $ref: '#/components/schemas/BankTransactionType' bank_direction_filter: type: string enum: - MONEY_IN - MONEY_OUT description: Transaction direction to match. amount_min_filter: type: integer format: int64 description: Minimum transaction amount in cents. amount_max_filter: type: integer format: int64 description: Maximum transaction amount in cents. ApiBankTransactionDataOnly: type: object properties: id: type: string format: uuid description: Unique identifier of the bank transaction. business_id: type: string format: uuid description: >- Unique identifier of the business the bank transaction is associated with. source: $ref: '#/components/schemas/TransactionSource' description: Source of the transaction. source_transaction_id: type: string description: >- External transaction ID from the source platform (e.g, Plaid transaction ID). example: g4DlKyjXqGH3Kp5XlaWMtwLRrE4Z9AiE8B4Ko source_account_id: type: string description: >- External account ID from the source platform (e.g, Plaid account ID). example: Aaoy8G7VXZHVeqNoL1GvcmkPdqpLRWi9NArdG imported_at: type: string format: date-time description: Timestamp when the transaction was imported. date: type: string format: date-time description: Date of the transaction. direction: $ref: '#/components/schemas/BankTransactionDirection' description: Direction of the transaction. amount: type: integer format: int64 description: Transaction amount in cents. counterparty_name: type: string nullable: true description: Name of the transaction counterparty. example: WeWork description: type: string nullable: true description: Description of the transaction. example: WeWork monthly rent payment account_name: type: string nullable: true description: Name of the bank account. example: Plaid Checking categorizationStatus: $ref: '#/components/schemas/CategorizationStatus' description: The status of the transaction’s categorization in Layer’s systems. memo: type: string nullable: true description: >- Memo for any text you would like to associate with the bank transaction (for example, to display to end users). metadata: $ref: '#/components/schemas/PlatformDefinedJson' nullable: true description: Arbitrary custom metadata in JSON format with a size limit of 1KB. reference_number: type: string nullable: true description: >- Any (typically user-visible) identifier you would like to associate with the bank transaction. Can be used to filter when listing bank transactions. AccountId: type: object required: - type - id properties: type: type: string enum: - AccountId description: Resource type. Value will be `AccountId`. example: AccountId id: type: string format: uuid description: ID of the account. AccountStableName: type: object required: - type - stable_name properties: type: type: string enum: - StableName description: Resource type. Value will be `StableName`. example: StableName stable_name: type: string example: CURRENT_ASSETS description: Stable name of the account. Exclusion: type: object properties: type: type: string enum: - Exclusion description: Resource type. Value will be `Exclusion`. exclusion_type: $ref: '#/components/schemas/ExclusionType' required: - type - exclusion_type AccountCategorization: type: object properties: id: type: string format: uuid description: The ID of the Account. stable_name: type: string nullable: true description: The stable name for the account. example: RENT category: type: string description: The account ID or stable name, whichever is present. example: RENT display_name: type: string description: The display name for the account. example: Rent required: - id - category - display_name ExclusionCategorization: type: object properties: id: type: string description: The ID of the exclusion type. enum: - PERSONAL_EXPENSES - PERSONAL_INFLOWS - DUPLICATE_TRANSACTION - OTHER_EXCLUSION category: type: string description: The category of the exclusion type. enum: - PERSONAL_EXPENSES - PERSONAL_INFLOWS - DUPLICATE_TRANSACTION - OTHER_EXCLUSION display_name: type: string description: The display name of the exclusion type. enum: - Personal spending - Personal income sources - Duplicate transaction - Other exclusion required: - id - category - display_name SplitCategorization: type: object properties: entries: type: array items: $ref: '#/components/schemas/SplitCategorizationEntry' required: - entries MatchType: type: string enum: - TRANSFER - INVOICE_PAYMENT - PAYOUT ApiMatchDetails: type: object required: - id - amount - date properties: id: type: string format: uuid description: Layer's ID for the match. amount: type: integer format: int64 description: Monetary amount of the matched transaction, in cents. date: type: string format: date-time description: Date that the matched transaction occurred. description: type: string nullable: true description: Description of the match. example: Transfer from SavingsAccount to CheckingAccount ApiBankTransactionInterface: type: object required: - id - amount - date properties: id: type: string format: uuid description: Layer's UUID for the bank transaction. business_id: type: string format: uuid description: UUID of the business the transaction is for. source: $ref: '#/components/schemas/TransactionSource' description: Source of the bank transaction. source_transaction_id: type: string description: >- External transaction ID from the source platform (e.g, Plaid transaction ID). example: g4DlKyjXqGH3Kp5XlaWMtwLRrE4Z9AiE8B4Ko source_account_id: type: string description: >- External account ID from the source platform (e.g, Plaid account ID). example: Aaoy8G7VXZHVeqNoL1GvcmkPdqpLRWi9NArdG imported_at: type: string format: date-time description: Timestamp when the transaction was imported. date: type: string format: date-time description: Timestamp when the transaction was created. direction: $ref: '#/components/schemas/BankTransactionDirection' description: Direction of the transaction. amount: type: integer format: int64 description: Amount of the transaction, in cents. counterparty_name: type: string nullable: true description: Name of the transaction counterparty. example: WeWork description: type: string nullable: true description: Description of the transaction. example: WeWork monthly rent payment account_name: type: string nullable: true description: Name of the bank account. example: Plaid Checking categorizationStatus: $ref: '#/components/schemas/CategorizationStatus' description: The status of the transaction’s categorization in Layer’s systems. memo: type: string nullable: true description: >- Memo for any text you would like to associate with the bank transaction (for example, to display to end users). metadata: $ref: '#/components/schemas/PlatformDefinedJson' nullable: true description: Arbitrary custom metadata in JSON format with a size limit of 1KB. reference_number: type: string nullable: true description: >- Any (typically user-visible) identifier you would like to associate with the bank transaction. Can be used to filter when listing bank transactions. BankTransactionType: type: string description: Type of bank transaction. enum: - REVENUE - LOAN_DISBURSEMENT - REFUND_RECEIVED - INCOMING_P2P_TRANSFER - INTRA_ACCOUNT_TRANSFER_IN - CHECK_WITHDRAWAL - ATM_DEPOSIT - BANK_DEPOSIT - BANK_VERIFICATION_TRIAL_CREDIT - REVERSAL_IN - CREDIT_CARD_REWARD - CREDIT_CARD_PAYMENT_IN - INTEREST_EARNED - GOVERNMENT_OR_OTHER_GRANT - TAX_REFUND - PURCHASE - REFUND_GIVEN - OUTGOING_P2P_TRANSFER - INTRA_ACCOUNT_TRANSFER_OUT - CHECK_DEPOSIT - CREDIT_CARD_PAYMENT_OUT - ATM_WITHDRAWAL - BANK_WITHDRAWAL - BANKING_FEE - PAYMENT_PROCESSING_FEE - BANK_VERIFICATION_TRIAL_DEBIT - REVERSAL_OUT - LOAN_PAYMENT - TAX_PAYMENT - NOT_ENOUGH_INFORMATION ExclusionType: type: string description: Type of exclusion for a bank transaction. enum: - PERSONAL_EXPENSES - PERSONAL_INFLOWS - DUPLICATE_TRANSACTION - OTHER_EXCLUSION x-displayStrings: PERSONAL_EXPENSES: Personal transactions PERSONAL_INFLOWS: Personal income sources DUPLICATE_TRANSACTION: Duplicate transaction OTHER_EXCLUSION: Other exclusion SplitCategorizationEntry: type: object properties: amount: type: integer format: int64 description: Amount of the parent transaction for this split entry. category: description: >- Category for this split entry. May be an account categorization or an exclusion categorization. oneOf: - $ref: '#/components/schemas/AccountCategorization' title: Account - $ref: '#/components/schemas/ExclusionCategorization' title: Exclusion securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ````