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

# Match bank transaction

> Match a bank transaction to a financial event such as an invoice payment or a payout.

This should be used when platforms have pre-existing knowledge of what bank transactions are associated with a financial event, or when a user confirms a suggested match in a UI.

If you are using Layer's [Bank Transactions](/embedded-components/components/bank-transactions) embedded component, you are unlikely to need to call this endpoint directly.

Suggested matches can be found on a [Bank Transaction Object](/api-reference/bank-transaction/bank-transaction).


## OpenAPI

````yaml put /v1/businesses/{businessId}/bank-transactions/{transactionId}/match
openapi: 3.0.1
info:
  title: API
  version: latest
servers: []
security:
  - BearerAuth: []
tags: []
externalDocs:
  url: /
paths:
  /v1/businesses/{businessId}/bank-transactions/{transactionId}/match:
    put:
      tags: []
      summary: Match bank transaction
      description: >-
        Match a bank transaction to a financial event such as an invoice payment
        or a payout.
      operationId: business.bank-transactions.match.put
      parameters:
        - name: businessId
          in: path
          description: ID of the business the bank transaction is associated with.
          required: true
          schema:
            type: string
        - name: transactionId
          in: path
          description: The UUID of the bank transaction to match.
          required: true
          schema:
            type: string
        - 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/ConfirmMatch'
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiMatch'
        '404':
          description: >-
            Id of the business, or one of the specified bank transaction or
            match ids, is not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: >-
            Match failure, typically either the transaction or the prospective
            match have been updated and are no longer compatible matches.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      deprecated: false
components:
  schemas:
    ConfirmMatch:
      type: object
      properties:
        type:
          type: string
          description: Polymorphic discriminator, this must be set as `Confirm_Match`.
          example: Confirm_Match
        match_id:
          type: string
          format: uuid
          description: ID of the suggested match to confirm.
    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'
    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
    MatchType:
      type: string
      enum:
        - TRANSFER
        - INVOICE_PAYMENT
        - PAYOUT
    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.
    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
    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
    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
    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: []
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````