> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List expenses



## OpenAPI

````yaml /.tooling/schemas/rest/tags/product-finops.json get /expenses
openapi: 3.1.0
info:
  title: Tesouro Partner API
  version: '2025-06-23'
  description: The Tesouro REST API, for Tesouro partners to integrate with our solution.
  termsOfService: https://tesouro.com/terms
  contact:
    name: Tesouro team
    url: https://tesouro.com/about/
    email: developers@tesouro.com
servers:
  - url: https://api.sandbox.tesouro.com
    description: Sandbox
security: []
tags:
  - name: Accounting connections
  - name: Accounting data pull
  - name: Accounting synchronized records
  - name: Accounting tax rates
  - name: Analytics
  - name: Approval policies
  - name: Approval requests
  - name: Bank details
  - name: Comments
  - name: Cost centers
  - name: Counterpart addresses
  - name: Counterpart bank accounts
  - name: Counterpart contacts
  - name: Counterpart VAT IDs
  - name: Counterparts
  - name: Credit notes
  - name: Custom tax rates
  - name: Data exports
  - name: Delivery notes
  - name: Departments
  - name: Disclosures
  - name: Documents
  - name: Events
  - name: Expenses
  - name: Files
  - name: Ledger accounts
  - name: Locations
  - name: Mail templates
  - name: Mailbox domains
  - name: Mailboxes
  - name: Measure units
  - name: OCR
  - name: OIDC applications
  - name: Organizations
  - name: Overdue reminders
  - name: Payable duplicates
  - name: Payable line items
  - name: Payables
  - name: Payment intents
  - name: Payment links
  - name: Payment methods
  - name: Payment records
  - name: Payment reminders
  - name: Payment terms
  - name: PDF templates
  - name: Products
  - name: Projects
  - name: Purchase orders
  - name: Receipts
  - name: Receivables
  - name: Recurrences
  - name: Roles
  - name: Tags
  - name: Text templates
  - name: Transactions
  - name: Users
  - name: Webhook deliveries
  - name: Webhook subscriptions
paths:
  /expenses:
    servers:
      - url: https://api.sandbox.tesouro.com/finops/v1
        description: Sandbox
    get:
      tags:
        - Expenses
      summary: List expenses
      operationId: get_expenses
      parameters:
        - required: true
          schema:
            type: string
            format: date
          example: '2025-06-23'
          name: x-finops-version
          in: header
        - name: has_validation_errors
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
          description: >-
            Filter expenses by validation errors. An expense has validation
            errors when it is missing one or more fields required by the
            entity's required fields configuration (e.g. receipt_id,
            description). true: return only expenses with at least one missing
            required field. false: return only expenses where all required
            fields are present. Omit to return all expenses regardless of
            validation state.
        - name: order
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/OrderEnum'
            default: asc
          description: Order by
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            default: 100
          description: Max is 100
        - name: pagination_token
          in: query
          required: false
          schema:
            type: string
          description: A token, obtained from previous page. Prior over other filters
        - name: sort
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/ExpenseCursorFields'
              - type: 'null'
          description: Allowed sort fields
        - name: created_at__gt
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
          description: Created after this datetime (exclusive)
        - name: created_at__lt
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
          description: Created before this datetime (exclusive)
        - name: updated_at__gt
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
          description: Updated after this datetime (exclusive)
        - name: updated_at__lt
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
          description: Updated before this datetime (exclusive)
        - name: started_at__gt
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
          description: Expense started after this datetime (exclusive)
        - name: started_at__lt
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
          description: Expense started before this datetime (exclusive)
        - name: payment_processing_status__in
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  $ref: '#/components/schemas/TransactionStatusEnum'
              - type: 'null'
          description: One or multiple of the payment processing statuses
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/ExpenseTypeEnum'
              - type: 'null'
          description: The kind of expense. Omit to return every kind.
        - name: type__in
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  $ref: '#/components/schemas/ExpenseTypeEnum'
              - type: 'null'
          description: One or multiple kinds of expense
        - name: subtype__in
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  $ref: '#/components/schemas/ExpenseSubtypeEnum'
              - type: 'null'
          description: One or multiple of the expense subtypes
        - name: payout_status
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/PayoutStatusEnum'
              - type: 'null'
          description: Filter by payout status
        - name: payout_status__in
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  $ref: '#/components/schemas/PayoutStatusEnum'
              - type: 'null'
          description: One or multiple payout statuses
        - name: entity_user_id__in
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                  format: uuid
                type: array
              - type: 'null'
          description: One or multiple of the entity users
        - name: external_id__in
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
              - type: 'null'
          description: One or multiple of the expense external ids
        - name: amount__gt
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
          description: Amount greater than (exclusive)
        - name: amount__lt
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
          description: Amount less than (exclusive)
        - name: currency__in
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  $ref: '#/components/schemas/CurrencyEnum'
              - type: 'null'
          description: One or multiple of the expense currencies
        - name: merchant_amount__gt
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
          description: Merchant amount greater than (exclusive)
        - name: merchant_amount__lt
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
          description: Merchant amount less than (exclusive)
        - name: merchant_currency__in
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  $ref: '#/components/schemas/CurrencyEnum'
              - type: 'null'
          description: One or multiple of the expense merchant currencies
        - name: merchant_name__icontains
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
          description: Partially matched merchant name
        - name: payment_method
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/TransactionPaymentMethodTypeEnum'
              - type: 'null'
          description: Payment method type of the expense
        - name: payment_method__in
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  $ref: '#/components/schemas/TransactionPaymentMethodTypeEnum'
              - type: 'null'
          description: One or multiple of the payment method types
        - name: expense_status
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/ExpenseStatusEnum'
              - type: 'null'
          description: Filter by expense status
        - name: expense_status__in
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  $ref: '#/components/schemas/ExpenseStatusEnum'
              - type: 'null'
          description: One or multiple expense statuses
        - name: has_receipt
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
          description: >-
            Filter by presence of a linked receipt. true: return only expenses
            that have a receipt attached. false: return only expenses without a
            receipt. Omit to return all expenses.
        - name: x-organization-id
          in: header
          required: true
          schema:
            type: string
            format: uuid
            examples:
              - 9d2b4c8f-2087-4738-ba91-7359683c49a4
          description: The ID of the entity that owns the requested resource.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpenseResponseList'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchemaResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchemaResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchemaResponse'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchemaResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchemaResponse'
      security:
        - HTTPBearer: []
components:
  schemas:
    OrderEnum:
      type: string
      enum:
        - asc
        - desc
    ExpenseCursorFields:
      type: string
      enum:
        - created_at
        - updated_at
        - started_at
        - amount
        - merchant_amount
        - merchant_name
        - status
        - subtype
        - external_id
    TransactionStatusEnum:
      type: string
      enum:
        - created
        - processing
        - succeeded
        - declined
        - refunded
        - failed
    ExpenseTypeEnum:
      type: string
      enum:
        - card
        - reimbursement
    ExpenseSubtypeEnum:
      type: string
      enum:
        - capture
        - refund
        - cash_withdrawal
        - fee
        - adjustment
        - reversal
        - out_of_pocket
    PayoutStatusEnum:
      type: string
      enum:
        - unpaid
        - paid
    CurrencyEnum:
      type: string
      enum:
        - AED
        - AFN
        - ALL
        - AMD
        - ANG
        - AOA
        - ARS
        - AUD
        - AWG
        - AZN
        - BAM
        - BBD
        - BDT
        - BGN
        - BHD
        - BIF
        - BMD
        - BND
        - BOB
        - BRL
        - BSD
        - BTN
        - BWP
        - BYN
        - BZD
        - CAD
        - CDF
        - CHF
        - CLP
        - CNY
        - COP
        - CRC
        - CVE
        - CZK
        - DJF
        - DKK
        - DOP
        - DZD
        - EGP
        - ETB
        - EUR
        - FJD
        - FKP
        - GBP
        - GEL
        - GHS
        - GIP
        - GMD
        - GNF
        - GTQ
        - GYD
        - HKD
        - HNL
        - HTG
        - HUF
        - IDR
        - ILS
        - INR
        - IQD
        - ISK
        - JMD
        - JOD
        - JPY
        - KES
        - KGS
        - KHR
        - KMF
        - KRW
        - KWD
        - KYD
        - KZT
        - LAK
        - LBP
        - LKR
        - LRD
        - LSL
        - LYD
        - MAD
        - MDL
        - MGA
        - MKD
        - MMK
        - MNT
        - MOP
        - MUR
        - MVR
        - MWK
        - MXN
        - MYR
        - MZN
        - NAD
        - NGN
        - NIO
        - NOK
        - NPR
        - NZD
        - OMR
        - PAB
        - PEN
        - PGK
        - PHP
        - PKR
        - PLN
        - PYG
        - QAR
        - RON
        - RSD
        - RUB
        - RWF
        - SAR
        - SBD
        - SCR
        - SEK
        - SGD
        - SHP
        - SLE
        - SOS
        - SRD
        - SSP
        - SVC
        - SZL
        - THB
        - TJS
        - TMT
        - TND
        - TOP
        - TRY
        - TTD
        - TWD
        - TZS
        - UAH
        - UGX
        - USD
        - UYU
        - UZS
        - VND
        - VUV
        - WST
        - XAF
        - XCD
        - XOF
        - XPF
        - YER
        - ZAR
        - ZMW
    TransactionPaymentMethodTypeEnum:
      type: string
      enum:
        - card
        - bank_account
    ExpenseStatusEnum:
      type: string
      enum:
        - new
        - approve_in_progress
        - approved
        - rejected
        - canceled
        - deleted
    ExpenseResponseList:
      properties:
        data:
          items:
            $ref: '#/components/schemas/ExpenseResponse'
          type: array
        next_pagination_token:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            A token that can be sent in the `pagination_token` query parameter
            to get the next page of results, or `null` if there is no next page
            (i.e. you've reached the last page).
        prev_pagination_token:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            A token that can be sent in the `pagination_token` query parameter
            to get the previous page of results, or `null` if there is no
            previous page (i.e. you've reached the first page).
      type: object
      required:
        - data
      description: A paginated list of expenses.
    ErrorSchemaResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorSchema'
      type: object
      required:
        - error
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
      type: object
    ExpenseResponse:
      properties:
        id:
          type: string
          format: uuid
          description: A unique system-generated ID assigned to this transaction.
        amount:
          type: integer
          description: >-
            The transaction amount in [minor
            units](https://docs.tesouro.com/finops/support/currencies#minor-units).
            Positive values for in-flow, negative values for out-flow.
        applied_policy_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          description: ID of the approval policy applied to this transaction, if any.
        currency:
          $ref: '#/components/schemas/CurrencyEnum'
          description: ISO currency code.
          examples:
            - USD
        department_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          description: ID of the department associated with this transaction.
        description:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          description: A human-readable description of the transaction.
        entity_id:
          type: string
          format: uuid
          description: ID of the entity that owns this resource.
        entity_user_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          description: >-
            ID of the entity user who owns the transaction. Must be an active or
            invited user of the organization. When omitted and the request is
            made as an entity user, the caller becomes the owner; an explicit
            null leaves the transaction unowned. A caller limited to their own
            transactions may only name themselves or one of their direct
            reportees, and becomes the owner when the field is null.
        expense_status:
          $ref: '#/components/schemas/ExpenseStatusEnum'
          description: The current expense approval status of the transaction.
        external_id:
          anyOf:
            - type: string
              maxLength: 128
            - type: 'null'
          description: >-
            External identifier for idempotency, if provided by the source
            system.
        has_validation_errors:
          type: boolean
          description: >-
            Whether the transaction has missing required fields per the entity's
            TransactionValidation config. Always false when no config is set.
        ledger_account_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          description: ID of the ledger account from the Accounting service.
        location_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          description: ID of the location associated with this transaction.
        merchant_amount:
          type: integer
          description: Original merchant transaction amount in minor units.
        merchant_currency:
          $ref: '#/components/schemas/CurrencyEnum'
          description: ISO currency code for the `merchant_amount`.
        merchant_location:
          anyOf:
            - type: string
              maxLength: 128
            - type: 'null'
          description: >-
            The merchant location. Always set on cards, optional on
            reimbursements.
          examples:
            - New York, US
        merchant_name:
          type: string
          maxLength: 128
          description: The merchant name.
          examples:
            - Acme Inc.
        no_receipt_reason:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Reason provided by the employee when submitting without a receipt
            (e.g. receipt was lost or unavailable). Set via the submit endpoint;
            bypasses the receipt_id required-field check.
        paid_at:
          anyOf:
            - type: string
            - type: 'null'
          description: When a reimbursement was paid out. Null until paid.
        paid_by_entity_user_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          description: >-
            ID of the entity user who marked a reimbursement paid. Null until
            paid.
        partner_metadata:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          description: >-
            Extensible key-value pairs for storing additional custom information
            for partner needs.
        payment_method:
          anyOf:
            - $ref: '#/components/schemas/TransactionPaymentMethod'
            - type: 'null'
          description: >-
            How a card expense was paid. Always set on cards, null on
            reimbursements.
        payment_processing_status:
          $ref: '#/components/schemas/TransactionStatusEnum'
          description: The current processing status of the transaction.
          default: created
        payout_method:
          anyOf:
            - $ref: '#/components/schemas/PayoutMethodEnum'
            - type: 'null'
          description: How a reimbursement was paid out. Null until paid.
        payout_status:
          anyOf:
            - $ref: '#/components/schemas/PayoutStatusEnum'
            - type: 'null'
          description: >-
            Whether a reimbursement has been paid out to the employee. Null on
            cards.
        receipt_file_url:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            URL of the attached receipt's file. Present when receipt_id is set
            and the receipt is reachable; null otherwise.
        receipt_id:
          anyOf:
            - type: string
            - type: 'null'
          description: ID of the related receipt from payables service, if any.
        reject_reason:
          anyOf:
            - type: string
            - type: 'null'
          description: Optional reason explaining why the transaction was rejected.
        source_of_data:
          anyOf:
            - $ref: '#/components/schemas/SourceOfData'
            - type: 'null'
          description: >-
            Per-field source tracking. Each field indicates how its value was
            set: user, generated, or automatched.
        started_at:
          type: string
          description: Date and time when the transaction was initiated.
        subtype:
          $ref: '#/components/schemas/ExpenseSubtypeEnum'
          description: The kind of charge, such as a capture or a refund.
        type:
          $ref: '#/components/schemas/ExpenseTypeEnum'
          description: The kind of expense.
      type: object
      required:
        - type
        - started_at
        - amount
        - currency
        - merchant_amount
        - merchant_currency
        - merchant_name
        - id
        - entity_id
        - expense_status
        - has_validation_errors
        - subtype
    ErrorSchema:
      properties:
        message:
          type: string
      type: object
      required:
        - message
    ValidationError:
      properties:
        ctx:
          type: object
        input: {}
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
        msg:
          type: string
        type:
          type: string
      type: object
      required:
        - loc
        - msg
        - type
    TransactionPaymentMethod:
      oneOf:
        - $ref: '#/components/schemas/CardPaymentMethod'
        - $ref: '#/components/schemas/BankAccountPaymentMethod'
      discriminator:
        propertyName: type
        mapping:
          bank_account: '#/components/schemas/BankAccountPaymentMethod'
          card: '#/components/schemas/CardPaymentMethod'
    PayoutMethodEnum:
      type: string
      enum:
        - outside_platform
    SourceOfData:
      properties:
        department_id:
          anyOf:
            - $ref: '#/components/schemas/FieldSourceEnum'
            - type: 'null'
          description: Source of department_id.
        description:
          anyOf:
            - $ref: '#/components/schemas/FieldSourceEnum'
            - type: 'null'
          description: Source of description.
        ledger_account_id:
          anyOf:
            - $ref: '#/components/schemas/FieldSourceEnum'
            - type: 'null'
          description: Source of ledger_account_id.
        location_id:
          anyOf:
            - $ref: '#/components/schemas/FieldSourceEnum'
            - type: 'null'
          description: Source of location_id.
        receipt_id:
          anyOf:
            - $ref: '#/components/schemas/FieldSourceEnum'
            - type: 'null'
          description: Source of receipt_id.
      type: object
    CardPaymentMethod:
      properties:
        details:
          $ref: '#/components/schemas/CardPaymentMethodDetails'
        type:
          type: string
          const: card
      type: object
      required:
        - details
        - type
    BankAccountPaymentMethod:
      properties:
        details:
          $ref: '#/components/schemas/BankAccountPaymentMethodDetails'
        type:
          type: string
          const: bank_account
      type: object
      required:
        - details
        - type
    FieldSourceEnum:
      type: string
      enum:
        - user
        - generated
        - automatched
    CardPaymentMethodDetails:
      properties:
        brand:
          $ref: '#/components/schemas/CardBrandEnum'
          maxLength: 32
          description: The card brand name.
        card_type:
          $ref: '#/components/schemas/CardTypeEnum'
          description: The card type
        expiry_month:
          type: integer
          maximum: 12
          minimum: 1
          description: The card's expiration month (1 - January, 12 - December).
        expiry_year:
          type: integer
          maximum: 2099
          exclusiveMinimum: 2001
          description: The card's expiration year.
        last4:
          type: string
          maxLength: 4
          minLength: 4
          description: The last four digits of the card number.
          examples:
            - 1234
      type: object
      required:
        - brand
        - card_type
        - expiry_month
        - expiry_year
        - last4
    BankAccountPaymentMethodDetails:
      properties:
        account_holder_name:
          anyOf:
            - type: string
            - type: 'null'
          description: The name of the person or business that owns this bank account.
          examples:
            - Bob Jones
        account_number:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The bank account number. US account numbers contain 9 to 12 digits.
            UK account numbers typically contain 8 digits.
          examples:
            - '12345678'
        bic:
          anyOf:
            - type: string
              maxLength: 11
            - type: 'null'
          description: >-
            The SWIFT/BIC code of the bank. Can be either 8 or 11 characters
            long.
          examples:
            - CHASUS33XXX
        currency:
          anyOf:
            - $ref: '#/components/schemas/CurrencyEnum'
            - type: 'null'
          description: ISO currency code of the bank account.
        iban:
          anyOf:
            - type: string
              maxLength: 34
            - type: 'null'
          description: The IBAN of the bank account, up to 34 characters.
          examples:
            - GB29NWBK60161331926819
        name:
          anyOf:
            - type: string
              maxLength: 200
            - type: 'null'
          description: >-
            The name of the bank account, if available. For example, "Primary
            account" or "Savings account".
        routing_number:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The bank's routing transit number (RTN). US routing numbers consist
            of 9 digits.
        sort_code:
          anyOf:
            - type: string
            - type: 'null'
          description: The bank's sort code.
          examples:
            - '123456'
      type: object
    CardBrandEnum:
      type: string
      enum:
        - visa
        - mastercard
        - maestro
        - amex
        - union_pay
        - jcb
        - discover
        - dinners_club
        - unknown
    CardTypeEnum:
      type: string
      enum:
        - credit
        - debit
        - prepaid
        - unknown
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.