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

# List expense reports for organization

> Lists expense reports for the specified organization.



## OpenAPI

````yaml openapi/findity-admin-api.json GET /organizations/{organizationId}/reports
openapi: 3.1.0
info:
  title: Findity Admin API
  description: Findity Admin API
  version: 1.0.0
servers:
  - url: https://stage-api.findity.com/api/v1/admin
  - url: https://api.findity.com/api/v1/admin
security:
  - bearerAuth: []
paths:
  /organizations/{organizationId}/reports:
    get:
      tags:
        - Expense Reports
      summary: List expense reports for organization
      description: Lists expense reports for the specified organization.
      operationId: listOrganizationExpenseReports
      parameters:
        - name: organizationId
          in: path
          required: true
          description: The organization id
          schema:
            type: string
          example: test123
        - $ref: '#/components/parameters/statusesQuery'
        - $ref: '#/components/parameters/expenseReportInclude'
        - $ref: '#/components/parameters/max-2'
        - $ref: '#/components/parameters/offset-2'
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/expenseReportsSort'
        - $ref: '#/components/parameters/filterStatus'
        - $ref: '#/components/parameters/fromDate'
        - $ref: '#/components/parameters/toDate'
        - $ref: '#/components/parameters/companyCardOnly'
        - $ref: '#/components/parameters/recipientId'
        - $ref: '#/components/parameters/reportGroup'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfExpenseReports'
components:
  parameters:
    statusesQuery:
      in: query
      name: statuses
      required: false
      description: >-
        Comma separated list of statuses to include, to exclude a status use !
        before the status
      schema:
        type: array
        items:
          type: string
          enum:
            - APPROVAL
            - APPROVED
            - BULK_TRANSFER
            - DELETED
            - ERROR
            - NEW
            - NORMAL
            - ON_HOLD
            - PAID
            - READY_TO_SEND
            - REJECTED
            - REVIEW
            - SEND
            - SENT
            - TRANSFER
            - TRANSFER_TO_RECIPIENT
      example: APPROVAL, !APPROVED
    expenseReportInclude:
      name: include
      in: query
      description: >
        Parameter used to include additional data in the response. Available
        options:

        - expenseRecords: Include all expense records in the report

        - approvalChain: Include approval chain information
        (reminderSentToApprover, hasRejectedExpenseRecords,
        hasIncorrectApprovalChains, currentApproverInfo, approvalAllowed)

        - sendChain: Include send chain information (sendChain,
        hasIncorrectApprovalChains)

        - employeeId: Include the employee ID of the report owner

        - tag: Include tag information (simulatedCardReport, integrationTest,
        dimensions)

        - externalReports: Include reports an integration module is still
        working on, under meta.externalReports

        - meta.violations: Include the report's policy violations

        - meta.messages: Include the direct messages attached to the report

        - meta.autoApproval: Include the AI review guidance verdict for the
        report

        - meta.ids: Include the ids of every report matching the filter,
        ignoring pagination, under meta.ids
      required: false
      schema:
        $ref: '#/components/schemas/expenseIncludeEnum'
      example: expenseRecords,approvalChain,employeeId
    max-2:
      name: max
      in: query
      description: Max records to return
      required: false
      schema:
        type: integer
        format: int
        minimum: 1
        maximum: 1000
        default: 10
    offset-2:
      name: offset
      in: query
      description: Offset to be used in list
      required: false
      schema:
        type: integer
        format: int
        minimum: 0
        default: 0
    search:
      name: q
      in: query
      description: Parameter used in the search
      required: false
      schema:
        type: string
      example: name
    expenseReportsSort:
      name: sort
      in: query
      description: >-
        Sort parameter for expense reports. Accepts one or more sorting criteria
        in the format property:direction, where property is one of name,
        dateCreated, sent, reportNumber, ownerName, totalAmount,
        organizationName, organizationNumber, approved, lastUpdated, paid,
        status, employeeId, dueDate; and direction is either asc or desc.
        Multiple criteria can be provided as a comma-separated list. Default is
        lastUpdated:desc. Company card listings (companyCardOnly=true) always
        append owner last name ascending as a secondary sort, so the order
        within tied values is stable across pages.
      required: false
      example: lastUpdated:desc
      schema:
        type: string
        default: lastUpdated:desc
    filterStatus:
      name: filterStatus
      in: query
      description: Filter ON_HOLD reports by substatus
      required: false
      schema:
        type: string
        enum:
          - card_not_configured
          - reserved_transaction
      example: card_not_configured
    fromDate:
      in: query
      name: fromDate
      required: false
      description: Used for filtering
      schema:
        type: string
        format: date
      example: '2020-01-20'
    toDate:
      in: query
      name: toDate
      required: false
      description: Used for filtering
      schema:
        type: string
        format: date
      example: '2018-01-23'
    companyCardOnly:
      name: companyCardOnly
      in: query
      description: >-
        When true, only company card expense reports are returned. The response
        meta will also include aggregated totalAmount and totalExpenses for the
        whole filtered set.
      required: false
      schema:
        type: boolean
        default: false
      example: true
    recipientId:
      name: recipientId
      in: query
      description: >
        Filters the listing to reports whose next recipient is this one, meaning
        the step with the lowest sortOrder among the steps still in
        TRANSFER_TO_RECIPIENT. Used by the Ready to send tab, which is split per
        recipient. Only applied to organization listings.
      required: false
      schema:
        $ref: '#/components/schemas/Uuid'
      example: 3f2b1a0c9d8e7f6a5b4c3d2e1f0a9b8c
    reportGroup:
      name: reportGroup
      in: query
      description: >
        Zero based index of the report group to return, used by the Ready to
        send tab to split a large listing into slices. Reports are assigned to a
        group by their creation time, so the groups are stable and disjoint.
        Only applied when the owner is configured with more than one group (an
        organization's reportGroupSettings.numberOfRTSGroups, or a partner's
        numberOfReportGroups); otherwise the parameter is ignored and the full
        listing is returned.
      required: false
      schema:
        type: integer
        minimum: 0
  schemas:
    ArrayOfExpenseReports:
      type: object
      properties:
        meta:
          properties:
            count:
              type: integer
            total:
              type: integer
            totalAmount:
              type: number
              description: >-
                Aggregated amount across the whole filtered set, ignoring
                pagination. Only returned for companyCardOnly listings.
            totalExpenses:
              type: integer
              description: >-
                Aggregated expense record count across the whole filtered set,
                ignoring pagination. Only returned for companyCardOnly listings.
            externalReports:
              type: array
              description: >
                Expense reports an integration module has not finished yet, so
                they are not in `data`. Returned for `include=externalReports`.
                Empty when the integration has nothing in progress or is
                unavailable.
              items:
                $ref: '#/components/schemas/ExternalExpenseReport'
            ids:
              type: array
              description: >
                The ids of every expense report matching the filter, ignoring
                pagination and max, so a client can offer "select all on all
                pages" without paging through the whole result. Returned for
                `include=meta.ids`. There is no upper bound, so the array grows
                with the size of the filtered set - ask for it only when the
                listing actually offers a bulk selection, and narrow the filter
                first on organizations with a lot of reports.
              items:
                $ref: '#/components/schemas/Uuid'
        data:
          type: array
          items:
            $ref: '#/components/schemas/ExpenseReport'
      example:
        meta:
          count: 10
          total: 242
          externalReports:
            - id: 9f2c41ab
              name: Payroll batch 2026-04
              downloadUrl: >-
                https://integration.findity.com/ce-integration-kpmg/downloadReport?reportId=9f2c41ab
              sendUrl: >-
                https://integration.findity.com/ce-integration-kpmg/sendReport?reportId=9f2c41ab
              status: READY_TO_SEND
              integrationPluginName: ce-integration-kpmg
        data: []
    expenseIncludeEnum:
      type: array
      items:
        type: string
        enum:
          - expenseRecords
          - approvalChain
          - sendChain
          - employeeId
          - tag
          - externalReports
          - meta.violations
          - meta.messages
          - meta.autoApproval
          - meta.ids
    Uuid:
      type: string
      pattern: ^[0-9a-fA-F]{32}$
      description: UUID without dashes (32-character hex string)
    ExternalExpenseReport:
      type: object
      properties:
        id:
          type: string
          description: Id of the report inside the integration module. String, required.
        name:
          type: string
          description: Display name of the report. String, optional.
        downloadUrl:
          type: string
          description: Absolute url for downloading the report. String.
        sendUrl:
          type: string
          description: Absolute url for making the integration send the report. String.
        status:
          type: string
          description: Always `READY_TO_SEND`. String, enum.
          enum:
            - READY_TO_SEND
        integrationPluginName:
          type: string
          description: Name of the integration plugin the report came from. String.
    ExpenseReport:
      type: object
      properties:
        comment:
          type: string
        dateCreated:
          type: string
          readOnly: true
        emailRecipients:
          type: string
        expenseRecords:
          type: array
          items:
            $ref: '#/components/schemas/ExpenseRecord'
        id:
          type: string
        lastUpdated:
          type: string
        name:
          type: string
        organizationId:
          $ref: '#/components/schemas/Uuid'
        personId:
          $ref: '#/components/schemas/Uuid'
        previewUrl:
          type: string
          readOnly: true
        reportNumber:
          type: string
        sent:
          type: string
          readOnly: true
        paid:
          type: string
          format: date-time
          readOnly: true
          description: >-
            Date when the expense report was paid. ISO-8601 format (e.g.,
            2024-01-15T10:30:00Z). Read-only.
        approved:
          type: string
          format: date-time
          readOnly: true
          description: >-
            Date when the expense report was approved. ISO-8601 format (e.g.,
            2024-01-15T10:30:00Z). Read-only.
        status:
          type: string
          enum:
            - APPROVAL
            - APPROVED
            - READY_TO_SEND
            - BULK_TRANSFER
            - ERROR
            - NEW
            - NORMAL
            - ON_HOLD
            - PAID
            - REJECTED
            - SEND
            - SENT
            - TRANSFER
            - TRANSFER_TO_RECIPIENT
            - REVIEW
          readOnly: true
        processStatus:
          type: string
          enum:
            - DRAFT
            - PROCESSING
            - PROCESSED
            - REJECTED
          readOnly: true
        reimbursement:
          type: number
          readOnly: true
        reimbursementCurrency:
          type: string
          readOnly: true
        type:
          type: string
          enum:
            - AUTOMATIC
            - MANUAL
            - COMPANY_CARD
          readOnly: true
        ownerName:
          type: string
        firstName:
          type: string
          description: First name of the expense report owner
        lastName:
          type: string
          description: Last name of the expense report owner
        adminErrorInformation:
          type: string
          description: Error information from admin operations
        organizationName:
          type: string
        organizationNumber:
          type: string
        organizationLanguage:
          type: string
        organizationUseNewDimensions:
          type: boolean
        organizationRequiresAttestation:
          type: boolean
        organizationUsesPaymentBasis:
          type: boolean
        organizationReviewType:
          type: string
          enum:
            - NONE
            - AFTER_SEND
            - AFTER_APPROVAL
          description: >-
            Review type for the organization. None, before approval, or after
            approval. The AFTER_SEND value actually means before approval.
        expenseRecordCount:
          type: integer
          description: Number of expense records in this report
        totalAmount:
          type: number
          description: Total amount of all expense records in the report
        userCanModifyReports:
          type: boolean
        userCanSendReports:
          type: boolean
        reportGroup:
          type: integer
        onHoldStatus:
          type: object
          description: On-hold status information
          readOnly: true
          properties:
            cards:
              type: array
              items:
                type: object
                properties:
                  bank:
                    type: string
                    description: Bank identifier
                  cardNumber:
                    type: string
                    description: Card number (masked)
              description: List of active cards associated with the expense report
            cardMissingConfig:
              type: array
              items:
                type: object
                properties:
                  erId:
                    type: string
                    description: Expense record ID
                  bank:
                    type: string
                    description: Bank identifier
                  cardNumber:
                    type: string
                    description: Card number (masked)
                  cardExternalId:
                    type: string
                    description: External card ID
              description: List of cards missing configuration
            transactionWithAuthStatus:
              type: array
              items:
                type: string
              description: >-
                List of expense record IDs with authorization status
                transactions
            cardDeleted:
              type: array
              items:
                type: object
                properties:
                  erId:
                    type: string
                    description: Expense record ID
                  bank:
                    type: string
                    description: Bank identifier
                  cardNumber:
                    type: string
                    description: Card number (masked)
                  cardExternalId:
                    type: string
                    description: External card ID
              description: List of deleted cards
            allTransactionsEligibleForClearing:
              type: boolean
              description: Whether all transactions are eligible for manual clearing
        bank:
          type: string
          description: Bank information for payment
        dueDate:
          type: string
          format: date-time
          description: Payment due date. ISO-8601 format (e.g., 2024-01-15T10:30:00Z).
        cardNumber:
          type: string
          description: Card number (masked)
        invoiceRef:
          type: string
          description: Invoice reference
        invoiceNumber:
          type: string
          description: Invoice number
        invoiceDate:
          type: string
          format: date-time
          description: Invoice date. ISO-8601 format (e.g., 2024-01-15T10:30:00Z).
        externalVoucherNumber:
          type: string
          description: External voucher number from integration
        externalVoucherInformation:
          type: string
          description: External voucher information
        externalVoucherErrorInformation:
          type: string
          description: Error information from external voucher system
        externalVoucherId:
          type: string
          description: External voucher ID
        reminderSentToUser:
          type: boolean
          description: Whether a reminder has been sent to the user
        employeeId:
          type: string
          description: Employee ID (included when 'employeeId' is in include parameter)
        reminderSentToApprover:
          type: boolean
          description: >-
            Whether an approver has been reminded (included when 'approvalChain'
            is in include parameter)
        hasRejectedExpenseRecords:
          type: boolean
          description: >-
            Whether the report has rejected expense records (included when
            'approvalChain' is in include parameter)
        hasIncorrectApprovalChains:
          type: boolean
          description: >-
            Whether the report has incorrect approval chains (included when
            'approvalChain' or 'sendChain' is in include parameter)
        approvalAllowed:
          type: boolean
          description: >-
            Whether approval is allowed for this report (included when
            'approvalChain' is in include parameter)
        currentApproverInfo:
          type: object
          description: >-
            Information about the current approver (included when
            'approvalChain' is in include parameter)
          properties:
            singleApprover:
              type: boolean
              description: Whether the report has a single approver
            hasIncorrectApprovalChains:
              type: boolean
              description: Whether the report has incorrect approval chains
            approvalChainId:
              type: string
              description: The approval chain ID
            fullName:
              type: string
              description: Full name of the current approver
            email:
              type: string
              description: Email address of the current approver
        sendChain:
          type: object
          description: >-
            Send chain information (included when 'sendChain' is in include
            parameter)
          properties:
            isComplete:
              type: boolean
              description: Whether every active step in the chain has been sent
            senders:
              type: array
              items:
                type: object
                properties:
                  status:
                    type: string
                    description: >
                      Status of this step in the chain. The step a report is
                      currently waiting on is the one with the lowest sortOrder
                      among the steps still in TRANSFER_TO_RECIPIENT, which is
                      what the recipientId filter matches on.
                  recipient:
                    type: object
                    description: The recipient this step sends to
                    properties:
                      id:
                        type: string
                        description: >-
                          Id of the recipient, the value the recipientId filter
                          takes
                      integrationPluginName:
                        type: string
                        description: >-
                          The integration plugin that delivers to this
                          recipient, if the recipient is served by one
                  sortOrder:
                    type: integer
                    description: Position of this step in the chain, ascending
                  collectReport:
                    type: boolean
                    description: >-
                      Whether this step collects the report instead of sending
                      it on
                  recordInstances:
                    type: array
                    description: >-
                      The per expense record send instances belonging to this
                      step
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: External id of the record send instance
                        expenseRecordId:
                          type: string
                          description: The expense record this instance belongs to
                        externalVoucherNumber:
                          type: string
                          description: Voucher number the recipient booked the record under
                        externalVoucherId:
                          type: string
                          description: The recipient's own id for the voucher
                        externalVoucherUrl:
                          type: string
                          description: Link to the voucher in the recipient system
                        externalVoucherInformation:
                          type: string
                          description: Message returned by the recipient for this record
                        externalVoucherErrorInformation:
                          type: string
                          description: Error returned by the recipient for this record
                        bookingDate:
                          type: string
                          format: date-time
                          description: When the recipient booked the record
                        includedInRecipient:
                          type: boolean
                          description: >-
                            Whether the record was part of what was sent to the
                            recipient
                  uniqueVoucherNumbers:
                    type: array
                    items:
                      type: string
                    description: Unique voucher numbers
                  numberOfNonBookedExpenses:
                    type: integer
                    description: Number of non-booked expenses
                  numberOfBookedExpenses:
                    type: integer
                    description: Number of booked expenses
                  aggregatedVoucherNumbers:
                    type: string
                    description: Aggregated voucher numbers
                  aggregatedVoucherInformation:
                    type: string
                    description: Aggregated voucher information
                  aggregatedVoucherErrorInformation:
                    type: string
                    description: Aggregated voucher error information
              description: List of senders in the chain
        tag:
          type: object
          description: Tag information (included when 'tag' is in include parameter)
          properties:
            simulatedCardReport:
              type: boolean
            dimensions:
              type: object
        meta:
          type: object
          description: >-
            Server-computed metadata for the report. Each property is opt-in
            through the include parameter.
          properties:
            autoApproval:
              type: object
              required:
                - status
              description: >
                AI review guidance for the report, produced by the Controller
                agent and rolled up from the verdicts on the report's expenses.
                Only present when 'meta.autoApproval' is in the include
                parameter, the feature is enabled for the organization, and the
                agent has reached a verdict for every expense in the report.
              properties:
                status:
                  type: string
                  enum:
                    - APPROVED
                    - REJECTED
                  description: >
                    The verdict for the whole report. APPROVED means the report
                    is low risk and needs no manual attention. REJECTED means at
                    least one of its expenses was flagged and the report needs
                    manual review - no rejection has taken place and the
                    report's own status is unaffected. The two values match the
                    per-expense verdict the expense API already exposes under
                    meta.autoApproval, so a client can use one mapping for both.
                    A report the agent has not finished with is omitted entirely
                    rather than reported as pending.
                  readOnly: true
                reasons:
                  type: array
                  description: >
                    Why the agent reached that verdict, in the same wording the
                    approver app shows the end user and already translated for
                    the caller's locale. For REJECTED these are the deviations
                    found on the report's expenses, de-duplicated across them
                    and ordered by reason code. For APPROVED these are the
                    checks that came back clean. Omitted when there is nothing
                    to show, so a REJECTED report can arrive without it.
                  readOnly: true
                  items:
                    type: object
                    required:
                      - reason
                      - description
                    properties:
                      reason:
                        type: string
                        enum:
                          - SIMILAR_REJECTED_ORG
                          - SIMILAR_REJECTED_PERSON
                          - SIMILAR_REJECTED_GLOBAL
                          - POLICY_FAILURE
                          - NOT_VALID_RECEIPT
                          - DEVIATING_AMOUNT_ORG
                          - DEVIATING_AMOUNT_PERSON
                          - DEVIATING_AMOUNT_GLOBAL
                          - PREDICT_AMOUNT_DEVIATION
                          - WEEKEND_PURCHASE_DATE
                          - SPECIAL_ITEM_ALCOHOL
                          - SPECIAL_ITEM_TOBACCO
                        description: >
                          The check the agent ran. The set is closed and matches
                          the agent's reason types; new codes are only added
                          together with a new agent capability.
                      description:
                        type: string
                        description: The translated sentence shown for that reason.
        customFields:
          $ref: '#/components/schemas/ArrayOfCustomFields'
    ExpenseRecord:
      type: object
      description: ExpenseRecord format
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - NEW
            - NORMAL
            - APPROVAL
            - APPROVED
            - REJECTED
          readOnly: true
        personId:
          $ref: '#/components/schemas/Uuid'
        dateCreated:
          type: string
          readOnly: true
        lastUpdated:
          type: string
          readOnly: true
        organizationId:
          $ref: '#/components/schemas/Uuid'
        categoryId:
          $ref: '#/components/schemas/Uuid'
        rejectComment:
          type: string
          readOnly: true
        expenseReportId:
          $ref: '#/components/schemas/Uuid'
        reimbursement:
          type: number
          readOnly: true
        reimbursementCurrency:
          type: string
          readOnly: true
        meta:
          type: object
          properties:
            categoryIconUrl:
              type: string
              example: >-
                https://expense.findity.com/api/resources/8a5f867e9b204742a8cc2ca2b6c57358
    ArrayOfCustomFields:
      type: array
      items:
        type: object
        properties:
          fieldDefinitionId:
            $ref: '#/components/schemas/Uuid'
          value:
            $ref: '#/components/schemas/AnyValue'
    AnyValue:
      description: 'Can be: string, number, integer, date, boolean'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````