Tinvio Bank Rules API

openapi: 3.2.0
info:
  title: Tinvio Com Bank Rules API
  version: '1.0'
  contact:
    email: build.with@jaz.ai
    name: API Support
    url: https://jaz.ai
  description: 'Operations tagged Bank Rules across 2 of this provider''s published API definitions: tinvio-com-openapi-original.yaml, tinvio-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.getjaz.com
tags:
- description: Create and manage bank rules that automate statement categorization.
  name: Bank Rules
paths:
  /api/v1/bank-rules:
    get:
      description: List the organization's bank rules, paginated.
      operationId: list-bank-rules
      parameters:
      - description: Maximum number of results per page (max 1000).
        in: query
        name: limit
        schema:
          type: integer
          default: 100
      - description: Zero-indexed row offset into the result set.
        in: query
        name: offset
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageableResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: List Bank Rules
      tags:
      - Bank Rules
    post:
      description: Create a bank rule.
      operationId: create-bank-rule
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Create Bank Rule
      tags:
      - Bank Rules
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateActionShortcutClientRequest'
        description: The bank rule request.
        required: true
    servers:
    - url: https://api.getjaz.com
  /api/v1/bank-rules/search:
    post:
      description: Search bank rules with filters, sort, and pagination.
      operationId: search-bank-rule
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageableResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Search Bank Rules
      tags:
      - Bank Rules
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchActionShortcutRequest'
        description: Search filters.
        required: true
    servers:
    - url: https://api.getjaz.com
  /api/v1/bank-rules/{resourceId}:
    delete:
      description: Delete the bank rule.
      operationId: delete-bank-rule
      parameters:
      - description: Resource ID of the bank rule.
        in: path
        name: resourceId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Delete Bank Rule
      tags:
      - Bank Rules
    get:
      description: Get a single bank rule by its resource ID.
      operationId: get-bank-rule
      parameters:
      - description: Resource ID of the bank rule.
        in: path
        name: resourceId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Get Bank Rule
      tags:
      - Bank Rules
    put:
      description: Update an existing bank rule.
      operationId: update-bank-rule
      parameters:
      - description: Resource ID of the bank rule.
        in: path
        name: resourceId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Update Bank Rule
      tags:
      - Bank Rules
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateActionShortcutClientRequest'
        description: The bank rule request.
        required: true
    servers:
    - url: https://api.getjaz.com
components:
  schemas:
    BaseResponse:
      properties:
        data:
          description: The response object.
      type: object
    ColumnValueMapEntry:
      properties:
        matchType:
          description: How to compare the column value against matchValue (case-insensitive). Omit for a catch-all default row.
          enum:
          - EXACT
          - CONTAINS
          - STARTS_WITH
          type: string
        matchValue:
          description: Value to match against the column. Blank/omitted makes this row a catch-all default (matches any present value).
          type: string
        targetResourceId:
          description: 'What this row resolves to: a resource UUID for account/tax/classifier/contact maps, or the tag NAME for a tags map.'
          type: string
      type: object
    ActionShortcutFilter:
      properties:
        actionType:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: Filter by action type (e.g. RECONCILE_WITH_DIRECT_CASH_ENTRY).
        and:
          description: Combine with another filter using AND.
          type: object
        appliesToReconciliationAccount:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: Filter by bank account UUID.
        businessTransactionType:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: Filter by business transaction type.
        name:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: Filter by rule name.
        or:
          description: Combine with another filter using OR.
          type: object
        reference:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: Filter by reference template.
        resourceId:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: Filter by bank rule UUID.
      type: object
    ReconcileWithDirectCashEntryShortcutConfig:
      properties:
        amountAllocationType:
          description: 'Allocation strategy: FIXED (absolute amounts) or PERCENTAGE (proportional).'
          enum:
          - FIXED
          - PERCENTAGE
          type: string
        contactResourceId:
          description: Contact to pre-fill on created direct cash entries (UUIDv4).
          type: string
        contactResourceIdMap:
          allOf:
          - $ref: '#/components/schemas/ColumnValueMapConfig'
          description: '"Set Contact by" map: pick the contact (target = contact UUIDv4) from a custom bank-column value. Overrides contactResourceId when it resolves.'
        currencySettings:
          allOf:
          - $ref: '#/components/schemas/BTCurrencySettingsRequest'
          description: Transaction currency settings for multi-currency rules.
        fixedAllocation:
          description: Fixed amount allocations (used when amountAllocationType is FIXED).
          items:
            $ref: '#/components/schemas/FixedAllocationRequest'
          type: array
        internalNotes:
          description: Internal notes added to the created direct cash entry.
          type: string
        percentageAllocation:
          description: Percentage allocations (used when amountAllocationType is PERCENTAGE).
          items:
            $ref: '#/components/schemas/PercentageAllocationRequest'
          type: array
        reference:
          description: Reference template for the direct cash entry. Supports standard placeholders ({{bankPayee}}, {{bankReference}}, {{bankDescription}}) and custom-column tokens {{column:<key>}} (signed) / {{column_abs:<key>}} (absolute, AMOUNT columns).
          type: string
        tags:
          description: Tags to apply to created direct cash entries (max 50 tags, each up to 50 characters).
          items:
            type: string
          maxItems: 50
          type: array
        tagsMap:
          allOf:
          - $ref: '#/components/schemas/ColumnValueMapConfig'
          description: '"Set Tag by" map: append a tag (target = tag NAME, not a UUID) resolved from a custom bank-column value, in addition to the static tags.'
        taxCurrencySettings:
          allOf:
          - $ref: '#/components/schemas/BTCurrencySettingsRequest'
          description: Tax currency settings for tax reporting in a different currency.
      required:
      - reference
      type: object
    BTCurrencySettingsRequest:
      properties:
        exchangeToken:
          description: Exchange rate quote token.
          type: string
        rateFunctionalToSource:
          description: Exchange rate from the organization's base currency to the source currency.
          type: number
        sourceCurrencyCode:
          description: Source currency code (ISO 4217).
          type: string
      type: object
    PageableResponse:
      properties:
        data:
          description: Result rows for the requested page.
        totalElements:
          description: Total number of records matching the query.
          type: integer
        totalPages:
          description: Total number of pages.
          type: integer
      type: object
    ActionShortcutConfiguration:
      properties:
        reconcileWithDirectCashEntry:
          allOf:
          - $ref: '#/components/schemas/ReconcileWithDirectCashEntryShortcutConfig'
          description: Direct cash entry settings applied when the rule runs.
      required:
      - reconcileWithDirectCashEntry
      type: object
    CreateActionShortcutClientRequest:
      properties:
        appliesToReconciliationAccount:
          description: Bank account (reconciliation account) where this rule applies (UUIDv4).
          type: string
        businessTransactionType:
          default: BANK_STATEMENT_ENTRY
          description: Type of business transaction this rule applies to. Defaults to BANK_STATEMENT_ENTRY if omitted.
          enum:
          - BANK_STATEMENT_ENTRY
          type: string
        configuration:
          allOf:
          - $ref: '#/components/schemas/ActionShortcutConfiguration'
          description: Rule configuration with allocation details.
        name:
          description: Display name for the bank rule.
          minLength: 1
          type: string
        searchFilter:
          description: 'Condition that decides which bank statement entries the rule applies to, as an object with `version` (always 1), `raw` (the one-line form shown in the app, for example `description:grab`) and `parsed` (the structured condition, for example `{"description": {"contains": "grab"}}`). Conditions can test `description`, `extReference`, `extContactName`, `netAmount` and `valueDate`. `raw` may be blank; some conditions saved in the app carry no one-line form. Magic reconciliation suggests only rules that have a condition.'
          type: object
      required:
      - appliesToReconciliationAccount
      - configuration
      - name
      type: object
    ClassifierConfigRequest:
      properties:
        printable:
          description: When true, the classifier appears on printed and PDF documents.
          type: boolean
        resourceId:
          description: Resource ID of the classifier.
          type: string
        selectedClasses:
          description: Classes selected within the classifier.
          items:
            $ref: '#/components/schemas/SelectedClassRequest'
          type: array
        type:
          description: Transaction type the classifier applies to.
          enum:
          - bill
          - invoice
          type: string
      required:
      - printable
      - resourceId
      - selectedClasses
      - type
      type: object
    ColumnValueMapConfig:
      properties:
        columnKey:
          description: Key of the custom bank-statement column to read the value from.
          type: string
        mappings:
          description: Ordered lookup rows; the first matching row wins. Place a catch-all (blank matchValue) last.
          items:
            $ref: '#/components/schemas/ColumnValueMapEntry'
          type: array
      type: object
    FixedAllocationRequest:
      properties:
        amount:
          description: Fixed amount to allocate (must be >= 0). Omit when amountSourceColumnKey is set.
          minimum: 0
          type: number
        amountSourceColumnKey:
          description: '"Set amount by": take this line''s amount from the absolute value of a custom AMOUNT column (camelCase key) instead of a static amount.'
          type: string
        classifierConfig:
          description: Classifier (catalog) assignment for this allocation line.
          items:
            $ref: '#/components/schemas/ClassifierConfigRequest'
          type: array
        classifierConfigMap:
          allOf:
          - $ref: '#/components/schemas/ColumnValueMapConfig'
          description: '"Set Classifier by" map: pick the classifier class (target = classifier class UUIDv4) from a custom bank-column value.'
        description:
          description: Description for this allocation line.
          type: string
        organizationAccountResourceId:
          description: GL account to post this allocation to (UUIDv4). Optional when organizationAccountResourceIdMap is set.
          type: string
        organizationAccountResourceIdMap:
          allOf:
          - $ref: '#/components/schemas/ColumnValueMapConfig'
          description: '"Set Account by" map: pick the GL account (target = account UUIDv4) from a custom bank-column value, in lieu of a static account.'
        taxProfileResourceId:
          description: Tax profile to apply to this allocation (UUIDv4).
          type: string
        taxProfileResourceIdMap:
          allOf:
          - $ref: '#/components/schemas/ColumnValueMapConfig'
          description: '"Set Tax by" map: pick the tax profile (target = tax profile UUIDv4) from a custom bank-column value.'
      type: object
    ActionShortcutSortFilter:
      properties:
        order:
          description: Sort direction, ASC or DESC.
          enum:
          - ASC
          - asc
          - DESC
          - desc
          type: string
        sortBy:
          description: Fields to sort by, in priority order.
          items:
            type: string
          maxItems: 13
          type: array
          uniqueItems: true
      required:
      - sortBy
      type: object
    UpdateActionShortcutClientRequest:
      properties:
        appliesToReconciliationAccount:
          description: Bank account (reconciliation account) where this rule applies (UUIDv4).
          type: string
        businessTransactionType:
          default: BANK_STATEMENT_ENTRY
          description: Type of business transaction. Defaults to BANK_STATEMENT_ENTRY if omitted.
          enum:
          - BANK_STATEMENT_ENTRY
          type: string
        configuration:
          allOf:
          - $ref: '#/components/schemas/ActionShortcutConfiguration'
          description: 'Full replacement configuration: the entire configuration is replaced, not merged.'
        name:
          description: Updated display name for the bank rule.
          minLength: 1
          type: string
        resourceId:
          description: UUID of the bank rule to update.
          type: string
        searchFilter:
          description: Condition that decides which bank statement entries the rule applies to, in the same shape as on create. Omit it to keep the rule's current condition, or send `null` to remove it.
          type: object
      required:
      - appliesToReconciliationAccount
      - configuration
      - resourceId
      type: object
    SearchActionShortcutRequest:
      properties:
        filter:
          allOf:
          - $ref: '#/components/schemas/ActionShortcutFilter'
          description: Filter criteria for narrowing results.
        limit:
          default: 100
          description: Maximum number of results per page (max 1000).
          maximum: 1000
          minimum: 1
          type: integer
        offset:
          default: 0
          description: Zero-indexed row offset into the result set. Sort is required when offset is set.
          maximum: 65536
          minimum: 0
          type: integer
        query:
          description: 'Structured search query using Jaz search operators. Parsed automatically into filter fields.

            Explicit filter fields override query results on conflict.

            Example: "status:unpaid AND $500+".'
          maxLength: 1000
          type: string
        sort:
          allOf:
          - $ref: '#/components/schemas/ActionShortcutSortFilter'
          description: Sort configuration (required when using offset).
        viewStatus:
          description: Filter by view status.
          type: string
      type: object
    ErrorResponse:
      properties:
        error:
          allOf:
          - $ref: '#/components/schemas/ErrorResponseData'
          description: Error details.
      type: object
    SelectedClassRequest:
      properties:
        className:
          description: Name of the selected class.
          type: string
        entityResourceId:
          description: 'Resource ID of the selected record, when the classifier draws its options from

            customers, suppliers, contacts, employees, or users. Send this instead of resourceId.'
          type: string
        resourceId:
          description: Resource ID of the selected class. Required when the classifier lists its own classes.
          type: string
      required:
      - className
      type: object
    StringExpression:
      properties:
        contains:
          description: Match values containing this substring.
          type: string
        endWith:
          description: Match values ending with this term (case sensitive).
          type: string
        eq:
          description: Match values equal to this.
          type: string
        in:
          description: Match values equal to any of these.
          items:
            type: string
          maxItems: 100
          type: array
        isBlank:
          description: Match records where the field is null or empty ("true") or neither ("false").
          type: string
        isNotBlank:
          description: Match records where the field is neither null nor empty ("true").
          type: string
        isNull:
          description: Match records where the field is null ("true") or not null ("false").
          type: string
        likeIn:
          description: Match values containing any of these substrings.
          items:
            type: string
          maxItems: 100
          type: array
        neq:
          description: Match values not equal to this.
          type: string
        notContains:
          description: Match values not containing this substring.
          type: string
        notEndWith:
          description: Match values not ending with this term (case sensitive).
          type: string
        notStartWith:
          description: Match values not starting with this term (case sensitive).
          type: string
        reg:
          description: Match values containing any of these terms. This is a substring match, not a regular expression, despite the name.
          items:
            type: string
          maxItems: 100
          type: array
        startWith:
          description: Match values starting with this term (case sensitive).
          type: string
      required:
      - in
      - likeIn
      - reg
      type: object
    PercentageAllocationRequest:
      properties:
        amount:
          description: Percentage of the matched bank entry amount to allocate (0-100).
          maximum: 100
          minimum: 0
          type: number
        classifierConfig:
          description: Classifier (catalog) assignment for this allocation line.
          items:
            $ref: '#/components/schemas/ClassifierConfigRequest'
          type: array
        classifierConfigMap:
          allOf:
          - $ref: '#/components/schemas/ColumnValueMapConfig'
          description: '"Set Classifier by" map: pick the classifier class (target = classifier class UUIDv4) from a custom bank-column value.'
        description:
          description: Description for this allocation line.
          type: string
        organizationAccountResourceId:
          description: GL account to post this allocation to (UUIDv4). Optional when organizationAccountResourceIdMap is set.
          type: string
        organizationAccountResourceIdMap:
          allOf:
          - $ref: '#/components/schemas/ColumnValueMapConfig'
          description: '"Set Account by" map: pick the GL account (target = account UUIDv4) from a custom bank-column value, in lieu of a static account.'
        taxProfileResourceId:
          description: Tax profile to apply to this allocation (UUIDv4).
          type: string
        taxProfileResourceIdMap:
          allOf:
          - $ref: '#/components/schemas/ColumnValueMapConfig'
          description: '"Set Tax by" map: pick the tax profile (target = tax profile UUIDv4) from a custom bank-column value.'
      type: object
    ErrorResponseData:
      properties:
        error_type:
          description: Error category, for example validation_error, invalid_request_body, or internal_server_error.
          example: validation_error
          type: string
        errors:
          description: Error messages describing what went wrong.
          items:
            type: string
          type: array
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: Organization API key. Pass it in the x-jk-api-key header on every request.
      in: header
      name: x-jk-api-key
      type: apiKey
x-refined-from:
- tinvio-com-openapi-original.yaml
- tinvio-com-openapi.yml