openapi: 3.0.1
info:
  title: Modern Treasury AccountCapability LedgerAccount API
  version: v1
  contact:
    name: Modern Treasury Engineering Team
    url: https://moderntreasury.com
  description: The Modern Treasury REST API. Please see https://docs.moderntreasury.com for more details.
servers:
- url: http://localhost:3000
- url: https://app.moderntreasury.com
tags:
- name: LedgerAccount
paths:
  /api/ledger_accounts:
    get:
      summary: list ledger_accounts
      tags:
      - LedgerAccount
      operationId: listLedgerAccounts
      description: Get a list of ledger accounts.
      security:
      - basic_auth: []
      parameters:
      - name: after_cursor
        in: query
        schema:
          type: string
          nullable: true
        required: false
      - name: per_page
        in: query
        schema:
          type: integer
        required: false
      - $ref: '#/components/parameters/metadata_query'
      - $ref: '#/components/parameters/bulk_id'
      - $ref: '#/components/parameters/bulk_name'
      - name: ledger_id
        in: query
        schema:
          type: string
        required: false
      - name: external_id
        in: query
        schema:
          type: string
        required: false
      - name: currency
        in: query
        required: false
        schema:
          type: string
      - name: balances
        in: query
        schema:
          type: object
          properties:
            as_of_date:
              type: string
              format: date
            effective_at:
              type: string
              format: date-time
            effective_at_lower_bound:
              type: string
              format: date-time
            effective_at_upper_bound:
              type: string
              format: date-time
          additionalProperties: false
        style: deepObject
        required: false
        description: Use `balances[effective_at_lower_bound]` and `balances[effective_at_upper_bound]` to get the balances change between the two timestamps. The lower bound is inclusive while the upper bound is exclusive of the provided timestamps. If no value is supplied the balances will be retrieved not including that bound.
        explode: true
      - name: pending_balance_amount
        in: query
        schema:
          type: object
          properties:
            gt:
              type: integer
            lt:
              type: integer
            gte:
              type: integer
            lte:
              type: integer
            eq:
              type: integer
            not_eq:
              type: integer
          additionalProperties: false
        style: deepObject
        required: false
        description: Use `gt` (>), `gte` (>=), `lt` (<), `lte` (<=), `eq` (=), or `not_eq` (!=) to filter by balance amount.
        explode: true
      - name: posted_balance_amount
        in: query
        schema:
          type: object
          properties:
            gt:
              type: integer
            lt:
              type: integer
            gte:
              type: integer
            lte:
              type: integer
            eq:
              type: integer
            not_eq:
              type: integer
          additionalProperties: false
        style: deepObject
        required: false
        description: Use `gt` (>), `gte` (>=), `lt` (<), `lte` (<=), `eq` (=), or `not_eq` (!=) to filter by balance amount.
        explode: true
      - name: available_balance_amount
        in: query
        schema:
          type: object
          properties:
            gt:
              type: integer
            lt:
              type: integer
            gte:
              type: integer
            lte:
              type: integer
            eq:
              type: integer
            not_eq:
              type: integer
          additionalProperties: false
        style: deepObject
        required: false
        description: Use `gt` (>), `gte` (>=), `lt` (<), `lte` (<=), `eq` (=), or `not_eq` (!=) to filter by balance amount.
        explode: true
      - name: normal_balance
        in: query
        schema:
          type: string
          enum:
          - credit
          - debit
          _x-stainless-modelDefPath: $shared.transaction_direction
      - name: created_at
        in: query
        schema:
          type: object
          additionalProperties:
            type: string
            format: date-time
        style: deepObject
        required: false
        description: Use `gt` (>), `gte` (>=), `lt` (<), `lte` (<=), or `eq` (=) to filter by the created at timestamp. For example, for all times after Jan 1 2000 12:00 UTC, use created_at%5Bgt%5D=2000-01-01T12:00:00Z.
        explode: true
      - name: updated_at
        in: query
        schema:
          type: object
          additionalProperties:
            type: string
            format: date-time
        style: deepObject
        required: false
        description: Use `gt` (>), `gte` (>=), `lt` (<), `lte` (<=), or `eq` (=) to filter by the updated at timestamp. For example, for all times after Jan 1 2000 12:00 UTC, use updated_at%5Bgt%5D=2000-01-01T12:00:00Z.
        explode: true
      - name: ledger_account_category_id
        in: query
        schema:
          type: string
        required: false
      responses:
        '200':
          description: successful
          headers:
            X-After-Cursor:
              schema:
                type: string
                nullable: true
              required: false
              description: The cursor for the next page. Including this in a call as `after_cursor` will return the next page.
            X-Per-Page:
              schema:
                type: integer
                nullable: true
              description: The current `per_page`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ledger_account'
        '422':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
    post:
      summary: create ledger_account
      tags:
      - LedgerAccount
      operationId: createLedgerAccount
      description: Create a ledger account.
      security:
      - basic_auth: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: This key should be something unique, preferably something like an UUID.
        schema:
          type: string
      responses:
        '201':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ledger_account'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '422':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ledger_account_create_request'
  /api/ledger_accounts/{id}:
    parameters:
    - name: id
      in: path
      schema:
        type: string
      description: The ledger account id (UUID)
      required: true
    get:
      summary: get ledger_account
      tags:
      - LedgerAccount
      operationId: getLedgerAccount
      description: Get details on a single ledger account.
      security:
      - basic_auth: []
      parameters:
      - name: id
        in: path
        schema:
          type: string
        description: The ledger account id (UUID) or external_id
        required: true
      - name: balances
        in: query
        schema:
          type: object
          properties:
            as_of_date:
              type: string
              format: date
            effective_at:
              type: string
              format: date-time
            effective_at_lower_bound:
              type: string
              format: date-time
            effective_at_upper_bound:
              type: string
              format: date-time
            as_of_lock_version:
              type: integer
          additionalProperties: false
        style: deepObject
        required: false
        description: Use `balances[effective_at_lower_bound]` and `balances[effective_at_upper_bound]` to get the balances change between the two timestamps. The lower bound is inclusive while the upper bound is exclusive of the provided timestamps. If no value is supplied the balances will be retrieved not including that bound. Use `balances[as_of_lock_version]` to retrieve a balance as of a specific Ledger Account `lock_version`.
        explode: true
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ledger_account'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '422':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
    patch:
      summary: update ledger_account
      tags:
      - LedgerAccount
      operationId: updateLedgerAccount
      description: Update the details of a ledger account.
      security:
      - basic_auth: []
      parameters: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ledger_account'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '409':
          description: conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '422':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ledger_account_update_request'
    delete:
      summary: delete ledger_account
      tags:
      - LedgerAccount
      operationId: deleteLedgerAccount
      description: Delete a ledger account.
      security:
      - basic_auth: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ledger_account'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
components:
  schemas:
    ledger_account_update_request:
      type: object
      properties:
        name:
          type: string
          description: The name of the ledger account.
        description:
          type: string
          description: The description of the ledger account.
          nullable: true
        metadata:
          type: object
          description: Additional data represented as key-value pairs. Both the key and value must be strings.
          additionalProperties:
            type: string
          example:
            key: value
            foo: bar
            modern: treasury
        external_id:
          type: string
          description: An optional user-defined 180 character unique identifier.
          nullable: true
    ledger_account_create_request:
      type: object
      properties:
        name:
          type: string
          description: The name of the ledger account.
        description:
          type: string
          description: The description of the ledger account.
          nullable: true
        normal_balance:
          type: string
          enum:
          - credit
          - debit
          description: The normal balance of the ledger account.
          _x-stainless-modelDefPath: $shared.transaction_direction
        ledger_id:
          type: string
          format: uuid
          description: The id of the ledger that this account belongs to.
        currency:
          type: string
          description: The currency of the ledger account.
        currency_exponent:
          type: integer
          description: The currency exponent of the ledger account.
          nullable: true
        ledger_account_category_ids:
          type: array
          items:
            type: string
            format: uuid
          description: The array of ledger account category ids that this ledger account should be a child of.
        ledgerable_id:
          type: string
          format: uuid
          description: If the ledger account links to another object in Modern Treasury, the id will be populated here, otherwise null.
        ledgerable_type:
          type: string
          enum:
          - counterparty
          - external_account
          - internal_account
          - virtual_account
          description: If the ledger account links to another object in Modern Treasury, the type will be populated here, otherwise null. The value is one of internal_account or external_account.
        metadata:
          type: object
          description: Additional data represented as key-value pairs. Both the key and value must be strings.
          additionalProperties:
            type: string
          example:
            key: value
            foo: bar
            modern: treasury
        external_id:
          type: string
          nullable: true
          description: An optional user-defined 180 character unique identifier.
      required:
      - name
      - normal_balance
      - ledger_id
      - currency
    error_message:
      type: object
      properties:
        errors:
          type: object
          properties:
            code:
              type: string
              enum:
              - parameter_invalid
              - parameter_missing
              - resource_not_found
              - not_found
              - forbidden
              - invalid_ip
              - invalid_key
              - header_invalid
              - expired_key
              - conflict
              - too_many_requests
            message:
              type: string
            parameter:
              type: string
      required:
      - errors
    ledger_balances_with_effective_at:
      type: object
      properties:
        effective_at_lower_bound:
          type: string
          format: date-time
          description: The inclusive lower bound of the effective_at timestamp for the returned balances.
          nullable: true
        effective_at_upper_bound:
          type: string
          format: date-time
          description: The exclusive upper bound of the effective_at timestamp for the returned balances.
          nullable: true
        pending_balance:
          $ref: '#/components/schemas/ledger_balance'
          description: The pending_balance is the sum of all pending and posted entries.
        posted_balance:
          $ref: '#/components/schemas/ledger_balance'
          description: The posted_balance is the sum of all posted entries.
        available_balance:
          $ref: '#/components/schemas/ledger_balance'
          description: The available_balance is the sum of all posted inbound entries and pending outbound entries. For credit normal, available_amount = posted_credits - pending_debits; for debit normal, available_amount = posted_debits - pending_credits.
      additionalProperties: false
      minProperties: 5
      required:
      - effective_at_lower_bound
      - effective_at_upper_bound
      - pending_balance
      - posted_balance
      - available_balance
    ledger_balance:
      type: object
      properties:
        credits:
          type: integer
        debits:
          type: integer
        amount:
          type: integer
        currency:
          type: string
          description: The currency of the ledger account.
        currency_exponent:
          type: integer
          description: The currency exponent of the ledger account.
      additionalProperties: false
      minProperties: 5
      required:
      - credits
      - debits
      - amount
      - currency
      - currency_exponent
    ledger_account:
      type: object
      properties:
        id:
          type: string
          format: uuid
        object:
          type: string
        live_mode:
          type: boolean
          description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        discarded_at:
          type: string
          format: date-time
          nullable: true
        name:
          type: string
          description: The name of the ledger account.
        description:
          type: string
          description: The description of the ledger account.
          nullable: true
        normal_balance:
          type: string
          enum:
          - credit
          - debit
          description: The normal balance of the ledger account.
          _x-stainless-modelDefPath: $shared.transaction_direction
        balances:
          $ref: '#/components/schemas/ledger_balances_with_effective_at'
          description: The pending, posted, and available balances for this ledger account. The posted balance is the sum of all posted entries on the account. The pending balance is the sum of all pending and posted entries on the account. The available balance is the posted incoming entries minus the sum of the pending and posted outgoing amounts.
        lock_version:
          type: integer
          description: Lock version of the ledger account.
        ledger_id:
          type: string
          format: uuid
          description: The id of the ledger that this account belongs to.
        ledgerable_id:
          type: string
          format: uuid
          nullable: true
          description: If the ledger account links to another object in Modern Treasury, the id will be populated here, otherwise null.
        external_id:
          type: string
          nullable: true
          description: An optional user-defined 180 character unique identifier.
        ledgerable_type:
          type: string
          enum:
          - counterparty
          - external_account
          - internal_account
          - virtual_account
          nullable: true
          description: If the ledger account links to another object in Modern Treasury, the type will be populated here, otherwise null. The value is one of internal_account or external_account.
        metadata:
          type: object
          description: Additional data represented as key-value pairs. Both the key and value must be strings.
          additionalProperties:
            type: string
          example:
            key: value
            foo: bar
            modern: treasury
      additionalProperties: false
      minProperties: 16
      required:
      - id
      - object
      - live_mode
      - created_at
      - updated_at
      - discarded_at
      - name
      - description
      - normal_balance
      - balances
      - lock_version
      - ledger_id
      - ledgerable_id
      - external_id
      - ledgerable_type
      - metadata
  parameters:
    bulk_id:
      name: id[]
      in: query
      style: form
      explode: true
      allowReserved: true
      schema:
        type: array
        items:
          type: string
      required: false
      description: If you have specific IDs to retrieve in bulk, you can pass them as query parameters delimited with `id[]=`, for example `?id[]=123&id[]=abc`.
    bulk_name:
      name: name[]
      in: query
      style: form
      explode: true
      allowReserved: true
      schema:
        type: array
        items:
          type: string
      required: false
      description: If you have specific names to retrieve in bulk, you can pass them as query parameters delimited with `name[]=`, for example `?name[]=123&name[]=abc`.
    metadata_query:
      name: metadata
      in: query
      schema:
        type: object
        additionalProperties:
          type: string
      style: deepObject
      explode: true
      required: false
      description: For example, if you want to query for records with metadata key `Type` and value `Loan`, the query would be `metadata%5BType%5D=Loan`. This encodes the query parameters.
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic