openapi: 3.1.0
info:
  title: SAP Concur Expense Report API
  description: >-
    The SAP Concur Expense Report v4 API enables integration with Concur
    Expense for creating, retrieving, updating, and managing expense reports,
    expenses (entries), allocations, comments, and workflow actions. This API
    follows RESTful conventions with JSON Merge Patch (RFC 7386) for partial
    updates and HATEOAS links for resource navigation.
  version: 4.0.0
  contact:
    name: SAP Concur Developer Support
    url: https://developer.concur.com/support/
  license:
    name: SAP Concur API Terms of Use
    url: https://www.concur.com/terms-of-use
  x-api-id: sap-concur-expense-report-v4
  x-audience: external-partner

servers:
- url: https://us.api.concursolutions.com
  description: US Production Datacenter
- url: https://us2.api.concursolutions.com
  description: US2 Production Datacenter
- url: https://emea.api.concursolutions.com
  description: EMEA Production Datacenter
- url: https://cn.api.concursolutions.com
  description: China Production Datacenter

security:
- bearerAuth: []

tags:
- name: Allocations
  description: >-
    Operations for retrieving and updating expense allocations, which
    distribute expense amounts across cost centers or accounts.
- name: Comments
  description: >-
    Operations for creating, retrieving, updating, and deleting comments
    at the report header or individual expense level.
- name: Expenses
  description: >-
    Operations for retrieving, updating, and deleting expense entries
    (line items) on a report, and retrieving itemizations.
- name: Reports
  description: >-
    Operations for creating, retrieving, updating, and deleting expense
    reports, as well as retrieving reports pending approval.
- name: Workflows
  description: >-
    Operations for submitting, approving, recalling, and sending back
    expense reports through the approval workflow.

paths:
  # ──────────────────────────────────────────────────────────────────────
  # Reports
  # ──────────────────────────────────────────────────────────────────────
  /expensereports/v4/users/{userID}/context/{contextType}/reports:
    post:
      operationId: createReport
      summary: Sap Concur Create a New Expense Report
      description: >-
        Creates a new expense report for the specified user. The report is
        created in an unsubmitted state and can be populated with expenses
        before submission through the workflow.
      tags:
      - Reports
      parameters:
      - $ref: '#/components/parameters/userID'
      - $ref: '#/components/parameters/contextTypeWritable'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewReport'
            examples:
              CreatereportRequestExample:
                summary: Default createReport request
                x-microcks-default: true
                value:
                  name: Example Title
                  businessPurpose: example_value
                  reportDate: '2026-01-15'
                  startDate: '2026-01-15'
                  endDate: '2026-01-15'
                  currencyCode: example_value
                  countryCode: example_value
                  countrySubDivisionCode: example_value
                  policyId: '500123'
                  customData:
                  - id: abc123
                    value: example_value
                    isValid: '500123'
      responses:
        '201':
          description: Report created successfully
          headers:
            Location:
              description: URI of the newly created report
              schema:
                type: string
                format: uri
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceCreatedResponse'
              examples:
                Createreport201Example:
                  summary: Default createReport 201 response
                  x-microcks-default: true
                  value:
                    uri: https://www.example.com
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}:
    get:
      operationId: getReport
      summary: Sap Concur Retrieve an Expense Report by Id
      description: >-
        Returns the full details of a specific expense report including
        header information, amounts, approval status, and custom data.
      tags:
      - Reports
      parameters:
      - $ref: '#/components/parameters/userID'
      - $ref: '#/components/parameters/contextType'
      - $ref: '#/components/parameters/reportId'
      responses:
        '200':
          description: Report retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportDetails'
              examples:
                Getreport200Example:
                  summary: Default getReport 200 response
                  x-microcks-default: true
                  value:
                    reportId: '500123'
                    name: Example Title
                    businessPurpose: example_value
                    reportDate: '2026-01-15'
                    startDate: '2026-01-15'
                    endDate: '2026-01-15'
                    countryCode: example_value
                    countrySubDivisionCode: example_value
                    currencyCode: example_value
                    policyId: '500123'
                    reportFormId: '500123'
                    ledgerId: '500123'
                    approvalStatus: example_value
                    approvalStatusId: '500123'
                    paymentStatus: example_value
                    paymentStatusId: '500123'
                    claimedAmount:
                      value: 42.5
                      currencyCode: example_value
                    approvedAmount:
                      value: 42.5
                      currencyCode: example_value
                    reportTotal:
                      value: 42.5
                      currencyCode: example_value
                    amountDueEmployee:
                      value: 42.5
                      currencyCode: example_value
                    userId: '500123'
                    isSubmitted: true
                    isSentBack: true
                    creationDate: '2026-01-15T10:30:00Z'
                    submitDate: '2026-01-15T10:30:00Z'
                    reportVersion: 10
                    customData:
                    - id: abc123
                      value: example_value
                      isValid: '500123'
                    links:
                    - rel: example_value
                      href: https://www.example.com
                      hreflang: example_value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateReport
      summary: Sap Concur Update an Unsubmitted Expense Report
      description: >-
        Partially updates an unsubmitted expense report using JSON Merge
        Patch (RFC 7386). Only fields included in the request body are
        updated; omitted fields remain unchanged.
      tags:
      - Reports
      parameters:
      - $ref: '#/components/parameters/userID'
      - $ref: '#/components/parameters/contextTypeWritable'
      - $ref: '#/components/parameters/reportId'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/UpdateReport'
            examples:
              UpdatereportRequestExample:
                summary: Default updateReport request
                x-microcks-default: true
                value:
                  name: Example Title
                  businessPurpose: example_value
                  reportDate: '2026-01-15'
                  startDate: '2026-01-15'
                  endDate: '2026-01-15'
                  countryCode: example_value
                  countrySubDivisionCode: example_value
                  policyId: '500123'
                  customData:
                  - id: abc123
                    value: example_value
                    isValid: '500123'
      responses:
        '204':
          description: Report updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /expensereports/v4/reports/{reportId}:
    patch:
      operationId: updateSubmittedReport
      summary: Sap Concur Update a Submitted Expense Report
      description: >-
        Partially updates a submitted expense report. Only Company JWT
        authentication is permitted. Updatable fields are limited to
        businessPurpose, comment, customData, name, and
        isPaperReceiptsReceived.
      tags:
      - Reports
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/reportId'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/UpdateSubmittedReport'
            examples:
              UpdatesubmittedreportRequestExample:
                summary: Default updateSubmittedReport request
                x-microcks-default: true
                value:
                  name: Example Title
                  businessPurpose: example_value
                  comment: example_value
                  isPaperReceiptsReceived: true
                  customData:
                  - id: abc123
                    value: example_value
                    isValid: '500123'
      responses:
        '204':
          description: Report updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteReport
      summary: Sap Concur Delete an Expense Report
      description: >-
        Permanently deletes an expense report and all associated expenses,
        allocations, and comments. Only unsubmitted reports can be deleted.
      tags:
      - Reports
      parameters:
      - $ref: '#/components/parameters/reportId'
      responses:
        '204':
          description: Report deleted successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /expensereports/v4/reports/{reportId}/formFields:
    get:
      operationId: getReportFormFields
      summary: Sap Concur Retrieve Report Form Field Configuration
      description: >-
        Returns the configured form fields for a specific expense report,
        including field metadata, validation rules, and display properties.
      tags:
      - Reports
      parameters:
      - $ref: '#/components/parameters/reportId'
      - name: policyId
        in: query
        description: Policy identifier to determine applicable form fields
        schema:
          type: string
        example: '500123'
      responses:
        '200':
          description: Form fields retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FormField'
              examples:
                Getreportformfields200Example:
                  summary: Default getReportFormFields 200 response
                  x-microcks-default: true
                  value:
                  - id: abc123
                    label: Example Title
                    controlType: example_value
                    dataType: example_value
                    isRequired: true
                    isCustom: true
                    maxLength: 10
                    sequence: 10
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /expensereports/v4/users/{userId}/context/{contextType}/reportsToApprove:
    get:
      operationId: getReportsToApprove
      summary: Sap Concur Retrieve Reports Pending Approval
      description: >-
        Returns a list of expense reports awaiting approval for the
        specified manager, including delegate approvals if requested.
      tags:
      - Reports
      parameters:
      - name: userId
        in: path
        required: true
        description: The unique identifier of the approving manager
        schema:
          type: string
          format: uuid
        example: '500123'
      - name: contextType
        in: path
        required: true
        description: Must be MANAGER for this endpoint
        schema:
          type: string
          enum:
          - MANAGER
        example: MANAGER
      - name: sort
        in: query
        description: Field to sort results by
        schema:
          type: string
        example: example_value
      - name: order
        in: query
        description: Sort order
        schema:
          type: string
          enum:
          - ASC
          - DESC
        example: ASC
      - name: includeDelegateApprovals
        in: query
        description: Whether to include reports delegated for approval
        schema:
          type: boolean
          default: false
        example: true
      responses:
        '200':
          description: Reports to approve retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReportToApprove'
              examples:
                Getreportstoapprove200Example:
                  summary: Default getReportsToApprove 200 response
                  x-microcks-default: true
                  value:
                  - reportId: '500123'
                    name: Example Title
                    userId: '500123'
                    approvalStatus: example_value
                    reportTotal:
                      value: 42.5
                      currencyCode: example_value
                    submitDate: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  # ──────────────────────────────────────────────────────────────────────
  # Expenses (Entries)
  # ──────────────────────────────────────────────────────────────────────
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/expenses:
    get:
      operationId: getExpenses
      summary: Sap Concur Retrieve All Expenses on a Report
      description: >-
        Returns a summary list of all expense entries (line items)
        associated with the specified expense report.
      tags:
      - Expenses
      parameters:
      - $ref: '#/components/parameters/userID'
      - $ref: '#/components/parameters/contextType'
      - $ref: '#/components/parameters/reportId'
      responses:
        '200':
          description: Expenses retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExpenseSummary'
              examples:
                Getexpenses200Example:
                  summary: Default getExpenses 200 response
                  x-microcks-default: true
                  value:
                  - expenseId: '500123'
                    transactionDate: '2026-01-15'
                    transactionAmount:
                      value: 42.5
                      currencyCode: example_value
                    postedAmount:
                      value: 42.5
                      currencyCode: example_value
                    approvedAmount:
                      value: 42.5
                      currencyCode: example_value
                    expenseType:
                      id: abc123
                      name: Example Title
                      code: example_value
                      isDeleted: true
                    businessPurpose: example_value
                    vendor:
                      id: abc123
                      name: Example Title
                      description: A sample description.
                    links:
                    - {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/expenses/{expenseId}:
    get:
      operationId: getExpense
      summary: Sap Concur Retrieve a Single Expense by Id
      description: >-
        Returns the full details of a specific expense entry including
        transaction amounts, vendor information, location, payment type,
        allocation state, tax summary, mileage, and travel data.
      tags:
      - Expenses
      parameters:
      - $ref: '#/components/parameters/userID'
      - $ref: '#/components/parameters/contextType'
      - $ref: '#/components/parameters/reportId'
      - $ref: '#/components/parameters/expenseId'
      responses:
        '200':
          description: Expense retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpenseDetail'
              examples:
                Getexpense200Example:
                  summary: Default getExpense 200 response
                  x-microcks-default: true
                  value:
                    expenseId: '500123'
                    transactionDate: '2026-01-15'
                    transactionAmount:
                      value: 42.5
                      currencyCode: example_value
                    postedAmount:
                      value: 42.5
                      currencyCode: example_value
                    approvedAmount:
                      value: 42.5
                      currencyCode: example_value
                    approverAdjustedAmount:
                      value: 42.5
                      currencyCode: example_value
                    businessPurpose: example_value
                    expenseType:
                      id: abc123
                      name: Example Title
                      code: example_value
                      isDeleted: true
                    paymentType:
                      id: abc123
                      name: Example Title
                      code: example_value
                    location:
                      id: abc123
                      name: Example Title
                      city: example_value
                      countryCode: example_value
                      countrySubDivisionCode: example_value
                    vendor:
                      id: abc123
                      name: Example Title
                      description: A sample description.
                    exchangeRate:
                      value: 42.5
                      operation: MULTIPLY
                    allocationState: FULLY_ALLOCATED
                    isPersonalExpense: true
                    isExpenseRejected: true
                    isPaperReceiptReceived: true
                    hasExceptions: true
                    expenseTaxSummary: {}
                    mileage:
                      totalDistance: 10
                      vehicleId: '500123'
                      odometerStart: 10
                      odometerEnd: 10
                      passengerCount: 10
                      personalDistance: 10
                      isMarkedAsHigherRate: true
                      routeId: '500123'
                      hasMachinery: true
                    travel:
                      startLocation: example_value
                      endLocation: example_value
                      ticketNumber: example_value
                      hotelCheckinDate: '2026-01-15'
                      hotelCheckoutDate: '2026-01-15'
                      carRentalDays: 10
                      airlineServiceClassCode: BUSIN
                      airlineFeeTypeCode: example_value
                    travelAllowance:
                      isExpensePartOfTravelAllowance: true
                      dailyTravelAllowanceId: '500123'
                      dailyLimitAmount: 42.5
                    invoiceId: '500123'
                    customData:
                    - id: abc123
                      value: example_value
                      isValid: '500123'
                    lastModifiedDate: '2026-01-15T10:30:00Z'
                    links:
                    - rel: example_value
                      href: https://www.example.com
                      hreflang: example_value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/expenses/{expenseId}/itemizations:
    get:
      operationId: getExpenseItemizations
      summary: Sap Concur Retrieve Itemizations for an Expense
      description: >-
        Returns the itemized breakdown of a parent expense entry, such as
        individual charges on a hotel folio or conference registration.
      tags:
      - Expenses
      parameters:
      - $ref: '#/components/parameters/userID'
      - $ref: '#/components/parameters/contextType'
      - $ref: '#/components/parameters/reportId'
      - $ref: '#/components/parameters/expenseId'
      responses:
        '200':
          description: Itemizations retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExpenseItemization'
              examples:
                Getexpenseitemizations200Example:
                  summary: Default getExpenseItemizations 200 response
                  x-microcks-default: true
                  value:
                  - itemizationId: '500123'
                    expenseId: '500123'
                    transactionDate: '2026-01-15'
                    transactionAmount:
                      value: 42.5
                      currencyCode: example_value
                    expenseType:
                      id: abc123
                      name: Example Title
                      code: example_value
                      isDeleted: true
                    businessPurpose: example_value
                    customData:
                    - {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /expensereports/v4/reports/{reportId}/expenses/{expenseId}:
    patch:
      operationId: updateSubmittedExpense
      summary: Sap Concur Update an Expense on a Submitted Report
      description: >-
        Partially updates an expense on a submitted report. Only Company
        JWT authentication is permitted. Updatable fields are limited to
        businessPurpose, customData, expenseSource, isExpenseRejected,
        and isPaperReceiptReceived.
      tags:
      - Expenses
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/reportId'
      - $ref: '#/components/parameters/expenseId'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/UpdateSubmittedExpense'
            examples:
              UpdatesubmittedexpenseRequestExample:
                summary: Default updateSubmittedExpense request
                x-microcks-default: true
                value:
                  businessPurpose: example_value
                  expenseSource: EA
                  isExpenseRejected: true
                  isPaperReceiptReceived: true
                  customData:
                  - id: abc123
                    value: example_value
                    isValid: '500123'
      responses:
        '204':
          description: Expense updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteExpense
      summary: Sap Concur Delete an Expense From a Report
      description: >-
        Permanently removes an expense entry and its associated
        allocations and itemizations from a report.
      tags:
      - Expenses
      parameters:
      - $ref: '#/components/parameters/reportId'
      - $ref: '#/components/parameters/expenseId'
      responses:
        '204':
          description: Expense deleted successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /expensereports/v4/reports/{reportId}/expenses/{expenseId}/formFields:
    get:
      operationId: getExpenseFormFields
      summary: Sap Concur Retrieve Expense Form Field Configuration
      description: >-
        Returns the configured form fields for a specific expense entry,
        including field metadata, validation rules, and display properties.
      tags:
      - Expenses
      parameters:
      - $ref: '#/components/parameters/reportId'
      - $ref: '#/components/parameters/expenseId'
      - name: expenseTypeId
        in: query
        description: Expense type identifier to filter applicable fields
        schema:
          type: string
        example: '500123'
      responses:
        '200':
          description: Form fields retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FormField'
              examples:
                Getexpenseformfields200Example:
                  summary: Default getExpenseFormFields 200 response
                  x-microcks-default: true
                  value:
                  - id: abc123
                    label: Example Title
                    controlType: example_value
                    dataType: example_value
                    isRequired: true
                    isCustom: true
                    maxLength: 10
                    sequence: 10
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  # ──────────────────────────────────────────────────────────────────────
  # Allocations
  # ──────────────────────────────────────────────────────────────────────
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/expenses/{expenseId}/allocations:
    get:
      operationId: getAllocations
      summary: Sap Concur Retrieve Allocations for an Expense
      description: >-
        Returns all allocations associated with a specific expense entry,
        showing how the expense amount is distributed across cost centers,
        departments, or accounts.
      tags:
      - Allocations
      parameters:
      - $ref: '#/components/parameters/userID'
      - $ref: '#/components/parameters/contextType'
      - $ref: '#/components/parameters/reportId'
      - $ref: '#/components/parameters/expenseId'
      responses:
        '200':
          description: Allocations retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Allocation'
              examples:
                Getallocations200Example:
                  summary: Default getAllocations 200 response
                  x-microcks-default: true
                  value:
                  - allocationId: '500123'
                    expenseId: '500123'
                    accountCode: example_value
                    overLimitAccountCode: example_value
                    allocationAmount:
                      value: 42.5
                      currencyCode: example_value
                    approvedAmount:
                      value: 42.5
                      currencyCode: example_value
                    claimedAmount:
                      value: 42.5
                      currencyCode: example_value
                    percentage: 42.5
                    isSystemAllocation: true
                    isPercentEdited: true
                    customData:
                    - {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/allocations/{allocationId}:
    get:
      operationId: getAllocation
      summary: Sap Concur Retrieve a Single Allocation by Id
      description: >-
        Returns the full details of a specific allocation including
        account codes, amounts, percentage, and custom data fields.
      tags:
      - Allocations
      parameters:
      - $ref: '#/components/parameters/userID'
      - $ref: '#/components/parameters/contextType'
      - $ref: '#/components/parameters/reportId'
      - $ref: '#/components/parameters/allocationId'
      responses:
        '200':
          description: Allocation retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Allocation'
              examples:
                Getallocation200Example:
                  summary: Default getAllocation 200 response
                  x-microcks-default: true
                  value:
                    allocationId: '500123'
                    expenseId: '500123'
                    accountCode: example_value
                    overLimitAccountCode: example_value
                    allocationAmount:
                      value: 42.5
                      currencyCode: example_value
                    approvedAmount:
                      value: 42.5
                      currencyCode: example_value
                    claimedAmount:
                      value: 42.5
                      currencyCode: example_value
                    percentage: 42.5
                    isSystemAllocation: true
                    isPercentEdited: true
                    customData:
                    - id: abc123
                      value: example_value
                      isValid: '500123'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateAllocation
      summary: Sap Concur Update an Allocation
      description: >-
        Partially updates an allocation using JSON Merge Patch (RFC 7386).
        Typically used to update custom data fields on allocations. The
        request body includes the allocation update and the list of
        expense IDs to which the update applies.
      tags:
      - Allocations
      parameters:
      - $ref: '#/components/parameters/userID'
      - $ref: '#/components/parameters/contextTypeWritable'
      - $ref: '#/components/parameters/reportId'
      - $ref: '#/components/parameters/allocationId'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/UpdateAllocationRequest'
            examples:
              UpdateallocationRequestExample:
                summary: Default updateAllocation request
                x-microcks-default: true
                value:
                  allocation:
                    customData:
                    - {}
                  expenseIds:
                  - example_value
      responses:
        '204':
          description: Allocation updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  # ──────────────────────────────────────────────────────────────────────
  # Comments
  # ──────────────────────────────────────────────────────────────────────
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/comments:
    get:
      operationId: getReportComments
      summary: Sap Concur Retrieve Report-level Comments
      description: >-
        Returns all comments associated with the expense report header.
      tags:
      - Comments
      parameters:
      - $ref: '#/components/parameters/userID'
      - $ref: '#/components/parameters/contextType'
      - $ref: '#/components/parameters/reportId'
      - name: includeAllComments
        in: query
        description: Whether to return comments from all report levels
        schema:
          type: boolean
          default: false
        example: true
      responses:
        '200':
          description: Comments retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Comment'
              examples:
                Getreportcomments200Example:
                  summary: Default getReportComments 200 response
                  x-microcks-default: true
                  value:
                  - comment: example_value
                    author:
                      userId: '500123'
                      firstName: example_value
                      lastName: example_value
                    creationDate: '2026-01-15T10:30:00Z'
                    isLatest: true
                    isAuditLog: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createReportComment
      summary: Sap Concur Create a Report-level Comment
      description: >-
        Adds a new comment to the expense report header.
      tags:
      - Comments
      parameters:
      - $ref: '#/components/parameters/userID'
      - $ref: '#/components/parameters/contextType'
      - $ref: '#/components/parameters/reportId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentRequest'
            examples:
              CreatereportcommentRequestExample:
                summary: Default createReportComment request
                x-microcks-default: true
                value:
                  comment: example_value
      responses:
        '201':
          description: Comment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceCreatedResponse'
              examples:
                Createreportcomment201Example:
                  summary: Default createReportComment 201 response
                  x-microcks-default: true
                  value:
                    uri: https://www.example.com
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateReportComment
      summary: Sap Concur Update the Latest Report-level Comment
      description: >-
        Replaces the content of the most recent comment on the report
        header. Only the latest comment by the authenticated user can be
        updated.
      tags:
      - Comments
      parameters:
      - $ref: '#/components/parameters/userID'
      - $ref: '#/components/parameters/contextType'
      - $ref: '#/components/parameters/reportId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentRequest'
            examples:
              UpdatereportcommentRequestExample:
                summary: Default updateReportComment request
                x-microcks-default: true
                value:
                  comment: example_value
      responses:
        '200':
          description: Comment updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteReportComment
      summary: Sap Concur Delete the Latest Report-level Comment
      description: >-
        Removes the most recent comment from the expense report header.
        Only the latest comment by the authenticated user can be deleted.
      tags:
      - Comments
      parameters:
      - $ref: '#/components/parameters/userID'
      - $ref: '#/components/parameters/contextType'
      - $ref: '#/components/parameters/reportId'
      responses:
        '204':
          description: Comment deleted successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/expenses/{expenseId}/comments:
    get:
      operationId: getExpenseComments
      summary: Sap Concur Retrieve Expense-level Comments
      description: >-
        Returns all comments associated with a specific expense entry.
      tags:
      - Comments
      parameters:
      - $ref: '#/components/parameters/userID'
      - $ref: '#/components/parameters/contextType'
      - $ref: '#/components/parameters/reportId'
      - $ref: '#/components/parameters/expenseId'
      responses:
        '200':
          description: Comments retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Comment'
              examples:
                Getexpensecomments200Example:
                  summary: Default getExpenseComments 200 response
                  x-microcks-default: true
                  value:
                  - comment: example_value
                    author:
                      userId: '500123'
                      firstName: example_value
                      lastName: example_value
                    creationDate: '2026-01-15T10:30:00Z'
                    isLatest: true
                    isAuditLog: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createExpenseComment
      summary: Sap Concur Create an Expense-level Comment
      description: >-
        Adds a new comment to a specific expense entry.
      tags:
      - Comments
      parameters:
      - $ref: '#/components/parameters/userID'
      - $ref: '#/components/parameters/contextType'
      - $ref: '#/components/parameters/reportId'
      - $ref: '#/components/parameters/expenseId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentRequest'
            examples:
              CreateexpensecommentRequestExample:
                summary: Default createExpenseComment request
                x-microcks-default: true
                value:
                  comment: example_value
      responses:
        '201':
          description: Comment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceCreatedResponse'
              examples:
                Createexpensecomment201Example:
                  summary: Default createExpenseComment 201 response
                  x-microcks-default: true
                  value:
                    uri: https://www.example.com
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  # ──────────────────────────────────────────────────────────────────────
  # Workflows
  # ──────────────────────────────────────────────────────────────────────
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /expensereports/v4/users/{userId}/reports/{reportId}/submit:
    patch:
      operationId: submitReport
      summary: Sap Concur Submit an Expense Report for Approval
      description: >-
        Submits an unsubmitted expense report into the approval workflow.
        The report must have at least one expense entry and pass all
        configured validation rules.
      tags:
      - Workflows
      parameters:
      - name: userId
        in: path
        required: true
        description: The unique identifier of the report owner
        schema:
          type: string
          format: uuid
        example: '500123'
      - $ref: '#/components/parameters/reportId'
      responses:
        '204':
          description: Report submitted successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/approve:
    patch:
      operationId: approveReport
      summary: Sap Concur Approve an Expense Report
      description: >-
        Approves an expense report in the current workflow step. The
        authenticated user must be an assigned approver. Individual
        expenses can be rejected within the approval by specifying
        expenseRejectedComment.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/userID'
      - name: contextType
        in: path
        required: true
        description: Must be MANAGER for approval actions
        schema:
          type: string
          enum:
          - MANAGER
        example: MANAGER
      - $ref: '#/components/parameters/reportId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportApproveRequest'
            examples:
              ApprovereportRequestExample:
                summary: Default approveReport request
                x-microcks-default: true
                value:
                  comment: example_value
                  expenseRejectedComment: example_value
                  statusId: '500123'
                  expectedStepCode: example_value
                  expectedStepSequence: 10
      responses:
        '204':
          description: Report approved successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/sendBack:
    patch:
      operationId: sendBackReport
      summary: Sap Concur Send Back an Expense Report to the Submitter
      description: >-
        Returns a submitted expense report to the employee for
        corrections. A comment explaining the reason is required.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/userID'
      - name: contextType
        in: path
        required: true
        description: Must be MANAGER for send-back actions
        schema:
          type: string
          enum:
          - MANAGER
        example: MANAGER
      - $ref: '#/components/parameters/reportId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportSendBackRequest'
            examples:
              SendbackreportRequestExample:
                summary: Default sendBackReport request
                x-microcks-default: true
                value:
                  comment: example_value
                  expectedStepCode: example_value
                  expectedStepSequence: 10
      responses:
        '204':
          description: Report sent back successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/recall:
    patch:
      operationId: recallReport
      summary: Sap Concur Recall a Submitted Expense Report
      description: >-
        Recalls a previously submitted expense report back to unsubmitted
        status, removing it from the approval workflow. Only the report
        owner or a proxy can recall a report.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/userID'
      - $ref: '#/components/parameters/contextTypeWritable'
      - $ref: '#/components/parameters/reportId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportApproveRequest'
            examples:
              RecallreportRequestExample:
                summary: Default recallReport request
                x-microcks-default: true
                value:
                  comment: example_value
                  expenseRejectedComment: example_value
                  statusId: '500123'
                  expectedStepCode: example_value
                  expectedStepSequence: 10
      responses:
        '204':
          description: Report recalled successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /expensereports/v4/users/{userId}/reports/{reportId}/costObjectsForApprover:
    get:
      operationId: getCostObjectsForApprover
      summary: Sap Concur Retrieve Cost Objects for an Approver
      description: >-
        Returns the cost objects (cost centers, departments, projects)
        associated with expenses on a report that are relevant to the
        specified approver.
      tags:
      - Workflows
      parameters:
      - name: userId
        in: path
        required: true
        description: The unique identifier of the approving manager
        schema:
          type: string
          format: uuid
        example: '500123'
      - $ref: '#/components/parameters/reportId'
      responses:
        '200':
          description: Cost objects retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CostObjectForApprover'
              examples:
                Getcostobjectsforapprover200Example:
                  summary: Default getCostObjectsForApprover 200 response
                  x-microcks-default: true
                  value:
                  - costObjectId: '500123'
                    name: Example Title
                    code: example_value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

# ════════════════════════════════════════════════════════════════════════
# Components
# ════════════════════════════════════════════════════════════════════════
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        OAuth 2.0 Bearer token. Obtain tokens via the SAP Concur
        Authentication API using either Company or User level grants.
        Required scopes vary by operation.

  parameters:
    userID:
      name: userID
      in: path
      required: true
      description: >-
        The unique identifier (UUID) of the SAP Concur user. Obtain via
        the Identity v4 API.
      schema:
        type: string
        format: uuid
    contextType:
      name: contextType
      in: path
      required: true
      description: >-
        The access context for the request. TRAVELER for the report
        owner, MANAGER for an approver, PROXY for a delegate.
      schema:
        type: string
        enum:
        - TRAVELER
        - MANAGER
        - PROXY
    contextTypeWritable:
      name: contextType
      in: path
      required: true
      description: >-
        The access context for write operations. TRAVELER for the report
        owner or PROXY for a delegate acting on behalf of the owner.
      schema:
        type: string
        enum:
        - TRAVELER
        - PROXY
    reportId:
      name: reportId
      in: path
      required: true
      description: The unique identifier of the expense report
      schema:
        type: string
    expenseId:
      name: expenseId
      in: path
      required: true
      description: The unique identifier of the expense entry
      schema:
        type: string
    allocationId:
      name: allocationId
      in: path
      required: true
      description: The unique identifier of the allocation
      schema:
        type: string

  schemas:
    # ── Amount ─────────────────────────────────────────────────────────
    Amount:
      type: object
      description: A monetary amount with its currency code
      required:
      - value
      - currencyCode
      properties:
        value:
          type: number
          format: double
          description: The numeric monetary amount
          examples:
          - 250.00
        currencyCode:
          type: string
          description: ISO 4217 three-letter currency code
          minLength: 3
          maxLength: 3
          examples:
          - USD

    # ── CustomData ─────────────────────────────────────────────────────
    CustomData:
      type: object
      description: >-
        A custom field value configured by the organization. Field IDs
        follow patterns like custom1-custom40 and orgUnit1-orgUnit6.
      required:
      - id
      properties:
        id:
          type: string
          description: >-
            The identifier of the custom field (e.g., custom1, orgUnit1)
          examples:
          - custom1
        value:
          type: string
          description: The value assigned to the custom field
          maxLength: 48
          examples:
          - Marketing Department
        isValid:
          type: boolean
          description: Whether the current value passes validation rules

    # ── Report Models ──────────────────────────────────────────────────
          example: '500123'
    NewReport:
      type: object
      description: Request body for creating a new expense report
      required:
      - name
      - currencyCode
      - policyId
      properties:
        name:
          type: string
          description: The name or title of the expense report
          examples:
          - Q1 2026 Business Travel
        businessPurpose:
          type: string
          description: The business justification for the expenses
          examples:
          - Client meetings in New York
        reportDate:
          type: string
          format: date
          description: The date of the report (YYYY-MM-DD)
          example: '2026-01-15'
        startDate:
          type: string
          format: date
          description: The start date of the reporting period
          example: '2026-01-15'
        endDate:
          type: string
          format: date
          description: The end date of the reporting period
          example: '2026-01-15'
        currencyCode:
          type: string
          description: ISO 4217 three-letter currency code for the report
          minLength: 3
          maxLength: 3
          examples:
          - USD
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 country code
          minLength: 2
          maxLength: 2
          examples:
          - US
        countrySubDivisionCode:
          type: string
          description: ISO 3166-2 subdivision code (state/province)
          example: example_value
        policyId:
          type: string
          description: The identifier of the expense policy to apply
          example: '500123'
        customData:
          type: array
          description: Custom field values for the report header
          items:
            $ref: '#/components/schemas/CustomData'

          example: []
    UpdateReport:
      type: object
      description: >-
        JSON Merge Patch body for updating an unsubmitted report. All
        fields from NewReport are updatable.
      properties:
        name:
          type: string
          description: The name or title of the expense report
          example: Example Title
        businessPurpose:
          type: string
          description: The business justification for the expenses
          example: example_value
        reportDate:
          type: string
          format: date
          example: '2026-01-15'
        startDate:
          type: string
          format: date
          example: '2026-01-15'
        endDate:
          type: string
          format: date
          example: '2026-01-15'
        countryCode:
          type: string
          minLength: 2
          maxLength: 2
          example: example_value
        countrySubDivisionCode:
          type: string
          example: example_value
        policyId:
          type: string
          example: '500123'
        customData:
          type: array
          items:
            $ref: '#/components/schemas/CustomData'

          example: []
    UpdateSubmittedReport:
      type: object
      description: >-
        Limited-field JSON Merge Patch for updating a submitted report.
        Only accessible with Company JWT authentication.
      properties:
        name:
          type: string
          description: The name or title of the expense report
          example: Example Title
        businessPurpose:
          type: string
          description: The business justification
          example: example_value
        comment:
          type: string
          description: A comment to accompany the update
          example: example_value
        isPaperReceiptsReceived:
          type: boolean
          description: Whether physical receipts have been received
          example: true
        customData:
          type: array
          items:
            $ref: '#/components/schemas/CustomData'

          example: []
    ReportDetails:
      type: object
      description: The full representation of an expense report
      required:
      - reportId
      - name
      - currencyCode
      - policyId
      - approvalStatus
      - paymentStatus
      - userId
      - isSubmitted
      - creationDate
      - reportVersion
      properties:
        reportId:
          type: string
          description: Unique identifier of the expense report
          example: '500123'
        name:
          type: string
          description: The name or title of the report
          example: Example Title
        businessPurpose:
          type: string
          description: The business justification for the expenses
          example: example_value
        reportDate:
          type: string
          format: date
          description: The date of the report
          example: '2026-01-15'
        startDate:
          type: string
          format: date
          description: The start date of the reporting period
          example: '2026-01-15'
        endDate:
          type: string
          format: date
          description: The end date of the reporting period
          example: '2026-01-15'
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: example_value
        countrySubDivisionCode:
          type: string
          description: ISO 3166-2 subdivision code
          example: example_value
        currencyCode:
          type: string
          description: ISO 4217 three-letter currency code
          example: example_value
        policyId:
          type: string
          description: The expense policy applied to this report
          example: '500123'
        reportFormId:
          type: string
          description: The form template used for this report
          example: '500123'
        ledgerId:
          type: string
          description: The financial ledger associated with this report
          example: '500123'
        approvalStatus:
          type: string
          description: Human-readable approval status label
          examples:
          - Not Submitted
          - Submitted & Pending Approval
          - Approved
        approvalStatusId:
          type: string
          description: Machine-readable approval status code
          examples:
          - A_NOTF
          - A_PEND
          - A_APPR
        paymentStatus:
          type: string
          description: Human-readable payment status label
          examples:
          - Not Paid
          - Payment Confirmed
        paymentStatusId:
          type: string
          description: Machine-readable payment status code
          example: '500123'
        claimedAmount:
          $ref: '#/components/schemas/Amount'
        approvedAmount:
          $ref: '#/components/schemas/Amount'
        reportTotal:
          $ref: '#/components/schemas/Amount'
        amountDueEmployee:
          $ref: '#/components/schemas/Amount'
        userId:
          type: string
          format: uuid
          description: The unique identifier of the report owner
          example: '500123'
        isSubmitted:
          type: boolean
          description: Whether the report has been submitted
          example: true
        isSentBack:
          type: boolean
          description: Whether the report was sent back for corrections
          example: true
        creationDate:
          type: string
          format: date-time
          description: When the report was created (ISO 8601)
          example: '2026-01-15T10:30:00Z'
        submitDate:
          type: string
          format: date-time
          description: When the report was last submitted (ISO 8601)
          example: '2026-01-15T10:30:00Z'
        reportVersion:
          type: integer
          format: int32
          description: The version number, incremented on each modification
          example: 10
        customData:
          type: array
          description: Custom field values on the report header
          items:
            $ref: '#/components/schemas/CustomData'
          example: []
        links:
          type: array
          description: HATEOAS navigation links
          items:
            $ref: '#/components/schemas/Link'

          example: []
    ReportToApprove:
      type: object
      description: A summary of an expense report awaiting approval
      properties:
        reportId:
          type: string
          description: Unique identifier of the report
          example: '500123'
        name:
          type: string
          description: The report name
          example: Example Title
        userId:
          type: string
          format: uuid
          description: The report owner's user ID
          example: '500123'
        approvalStatus:
          type: string
          description: Current approval status
          example: example_value
        reportTotal:
          $ref: '#/components/schemas/Amount'
        submitDate:
          type: string
          format: date-time
          description: When the report was submitted

    # ── Expense Models ─────────────────────────────────────────────────
          example: '2026-01-15T10:30:00Z'
    ExpenseSummary:
      type: object
      description: A summary of an expense entry on a report
      properties:
        expenseId:
          type: string
          description: Unique identifier of the expense
          example: '500123'
        transactionDate:
          type: string
          format: date
          description: The date the transaction occurred
          example: '2026-01-15'
        transactionAmount:
          $ref: '#/components/schemas/Amount'
        postedAmount:
          $ref: '#/components/schemas/Amount'
        approvedAmount:
          $ref: '#/components/schemas/Amount'
        expenseType:
          $ref: '#/components/schemas/ExpenseType'
        businessPurpose:
          type: string
          description: Business justification for this expense
          example: example_value
        vendor:
          $ref: '#/components/schemas/Vendor'
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'

          example: []
    ExpenseDetail:
      type: object
      description: The full representation of an expense entry
      required:
      - expenseId
      properties:
        expenseId:
          type: string
          description: Unique identifier of the expense
          example: '500123'
        transactionDate:
          type: string
          format: date
          description: The date the transaction occurred
          example: '2026-01-15'
        transactionAmount:
          $ref: '#/components/schemas/Amount'
        postedAmount:
          $ref: '#/components/schemas/Amount'
        approvedAmount:
          $ref: '#/components/schemas/Amount'
        approverAdjustedAmount:
          $ref: '#/components/schemas/Amount'
        businessPurpose:
          type: string
          description: Business justification, maximum 64 characters
          maxLength: 64
          example: example_value
        expenseType:
          $ref: '#/components/schemas/ExpenseType'
        paymentType:
          $ref: '#/components/schemas/PaymentType'
        location:
          $ref: '#/components/schemas/Location'
        vendor:
          $ref: '#/components/schemas/Vendor'
        exchangeRate:
          $ref: '#/components/schemas/ExchangeRate'
        allocationState:
          type: string
          description: The allocation status of this expense
          enum:
          - FULLY_ALLOCATED
          - NOT_ALLOCATED
          - PARTIALLY_ALLOCATED
          example: FULLY_ALLOCATED
        isPersonalExpense:
          type: boolean
          description: Whether this is a non-reimbursable personal expense
          example: true
        isExpenseRejected:
          type: boolean
          description: Whether the expense has been rejected by an approver
          example: true
        isPaperReceiptReceived:
          type: boolean
          description: Whether a physical receipt has been received
          example: true
        hasExceptions:
          type: boolean
          description: Whether the expense has policy exceptions
          example: true
        expenseTaxSummary:
          $ref: '#/components/schemas/ExpenseTaxSummary'
        mileage:
          $ref: '#/components/schemas/Mileage'
        travel:
          $ref: '#/components/schemas/Travel'
        travelAllowance:
          $ref: '#/components/schemas/TravelAllowance'
        invoiceId:
          type: string
          description: Reference to a supplier invoice
          example: '500123'
        customData:
          type: array
          items:
            $ref: '#/components/schemas/CustomData'
          example: []
        lastModifiedDate:
          type: string
          format: date-time
          description: When the expense was last modified (ISO 8601)
          example: '2026-01-15T10:30:00Z'
        links:
          type: array
          description: HATEOAS navigation links
          items:
            $ref: '#/components/schemas/Link'

          example: []
    UpdateSubmittedExpense:
      type: object
      description: >-
        Limited-field update for an expense on a submitted report. Only
        accessible with Company JWT authentication.
      required:
      - expenseSource
      properties:
        businessPurpose:
          type: string
          description: Business justification, maximum 64 characters
          maxLength: 64
          example: example_value
        expenseSource:
          type: string
          description: The source system that created or modified the expense
          enum:
          - EA
          - MOB
          - OTHER
          - SE
          - TA
          - TR
          - UI
          example: EA
        isExpenseRejected:
          type: boolean
          description: Whether to mark the expense as rejected
          example: true
        isPaperReceiptReceived:
          type: boolean
          description: Whether a physical receipt has been received
          example: true
        customData:
          type: array
          items:
            $ref: '#/components/schemas/CustomData'

          example: []
    ExpenseItemization:
      type: object
      description: >-
        An itemized line within a parent expense, representing a
        breakdown of the total amount.
      properties:
        itemizationId:
          type: string
          description: Unique identifier of the itemization
          example: '500123'
        expenseId:
          type: string
          description: The parent expense identifier
          example: '500123'
        transactionDate:
          type: string
          format: date
          description: The date of the itemized charge
          example: '2026-01-15'
        transactionAmount:
          $ref: '#/components/schemas/Amount'
        expenseType:
          $ref: '#/components/schemas/ExpenseType'
        businessPurpose:
          type: string
          description: Purpose of this specific itemization
          example: example_value
        customData:
          type: array
          items:
            $ref: '#/components/schemas/CustomData'

    # ── Supporting Type Models ─────────────────────────────────────────
          example: []
    ExpenseType:
      type: object
      description: An expense category classification
      properties:
        id:
          type: string
          description: >-
            The expense type identifier (e.g., BRKFT, LODNG, AIRFR)
          maxLength: 5
          example: abc123
        name:
          type: string
          description: The localized display name
          example: Example Title
        code:
          type: string
          description: The expense type code
          example: example_value
        isDeleted:
          type: boolean
          description: Whether this type has been deactivated

          example: true
    PaymentType:
      type: object
      description: A payment method used for an expense
      properties:
        id:
          type: string
          description: The payment type identifier (e.g., CASH, CPAID)
          maxLength: 4
          example: abc123
        name:
          type: string
          description: The localized display name
          example: Example Title
        code:
          type: string
          description: The payment type code

          example: example_value
    Location:
      type: object
      description: A geographic location associated with an expense
      properties:
        id:
          type: string
          description: The location identifier
          example: abc123
        name:
          type: string
          description: The localized location name
          example: Example Title
        city:
          type: string
          description: The city name
          example: example_value
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: example_value
        countrySubDivisionCode:
          type: string
          description: ISO 3166-2 subdivision code

          example: example_value
    Vendor:
      type: object
      description: Vendor or merchant information for an expense
      properties:
        id:
          type: string
          description: The vendor identifier
          example: abc123
        name:
          type: string
          description: The vendor or merchant name
          example: Example Title
        description:
          type: string
          description: Additional vendor description

          example: A sample description.
    ExchangeRate:
      type: object
      description: Currency exchange rate applied to an expense
      required:
      - value
      - operation
      properties:
        value:
          type: number
          format: double
          description: The exchange rate multiplier or divisor
          example: 42.5
        operation:
          type: string
          description: How to apply the rate to convert currencies
          enum:
          - MULTIPLY
          - DIVIDE

          example: MULTIPLY
    Mileage:
      type: object
      description: Mileage-specific data for distance-based expenses
      properties:
        totalDistance:
          type: integer
          description: Total distance traveled
          example: 10
        vehicleId:
          type: string
          description: The identifier of the vehicle used
          example: '500123'
        odometerStart:
          type: integer
          description: Starting odometer reading
          example: 10
        odometerEnd:
          type: integer
          description: Ending odometer reading
          example: 10
        passengerCount:
          type: integer
          description: Number of passengers
          example: 10
        personalDistance:
          type: integer
          description: Distance attributed to personal use
          example: 10
        isMarkedAsHigherRate:
          type: boolean
          description: Whether the higher mileage rate applies
          example: true
        routeId:
          type: string
          description: The identifier of the route taken
          example: '500123'
        hasMachinery:
          type: boolean
          description: Whether equipment was transported

          example: true
    Travel:
      type: object
      description: Travel-specific data for transportation expenses
      properties:
        startLocation:
          type: string
          description: Trip origin location
          maxLength: 100
          example: example_value
        endLocation:
          type: string
          description: Trip destination location
          maxLength: 100
          example: example_value
        ticketNumber:
          type: string
          description: Ticket or booking reference number
          maxLength: 32
          example: example_value
        hotelCheckinDate:
          type: string
          format: date
          description: Hotel check-in date
          example: '2026-01-15'
        hotelCheckoutDate:
          type: string
          format: date
          description: Hotel check-out date
          example: '2026-01-15'
        carRentalDays:
          type: integer
          description: Number of car rental days
          example: 10
        airlineServiceClassCode:
          type: string
          description: Airline cabin class code
          enum:
          - BUSIN
          - COACH
          - FIRST
          example: BUSIN
        airlineFeeTypeCode:
          type: string
          description: Airline fee type identifier

          example: example_value
    TravelAllowance:
      type: object
      description: Travel allowance (per diem) data associated with an expense
      properties:
        isExpensePartOfTravelAllowance:
          type: boolean
          description: Whether this expense is part of a travel allowance
          example: true
        dailyTravelAllowanceId:
          type: string
          description: Identifier of the daily travel allowance
          maxLength: 32
          example: '500123'
        dailyLimitAmount:
          type: number
          format: double
          description: The daily allowance limit amount

          example: 42.5
    ExpenseTaxSummary:
      type: object
      description: Tax information summarized for an expense
      properties:
        netAdjustedTaxAmount:
          $ref: '#/components/schemas/Amount'
        netReclaimAdjustedAmount:
          $ref: '#/components/schemas/Amount'
        netReclaimAmount:
          $ref: '#/components/schemas/Amount'
        netTaxAmount:
          $ref: '#/components/schemas/Amount'
        totalReclaimAdjustedAmount:
          $ref: '#/components/schemas/Amount'
        totalReclaimPostedAmount:
          $ref: '#/components/schemas/Amount'
        totalTaxAdjustedAmount:
          $ref: '#/components/schemas/Amount'
        totalTaxPostedAmount:
          $ref: '#/components/schemas/Amount'

    # ── Allocation Models ──────────────────────────────────────────────
    Allocation:
      type: object
      description: >-
        An expense allocation that distributes an expense amount across
        cost centers, departments, or general ledger accounts.
      required:
      - allocationId
      - expenseId
      - percentage
      - isSystemAllocation
      - isPercentEdited
      properties:
        allocationId:
          type: string
          description: Unique identifier of the allocation
          example: '500123'
        expenseId:
          type: string
          description: The expense this allocation belongs to
          example: '500123'
        accountCode:
          type: string
          description: The ledger account code
          example: example_value
        overLimitAccountCode:
          type: string
          description: Account code for amounts exceeding policy limits
          example: example_value
        allocationAmount:
          $ref: '#/components/schemas/Amount'
        approvedAmount:
          $ref: '#/components/schemas/Amount'
        claimedAmount:
          $ref: '#/components/schemas/Amount'
        percentage:
          type: number
          format: double
          description: >-
            The percentage of the total expense allocated (0-100)
          minimum: 0
          maximum: 100
          example: 42.5
        isSystemAllocation:
          type: boolean
          description: >-
            Whether this allocation was automatically created by the
            system (true) or manually created by a user (false)
          example: true
        isPercentEdited:
          type: boolean
          description: Whether the allocation percentage has been modified
          example: true
        customData:
          type: array
          description: Custom field values on the allocation
          items:
            $ref: '#/components/schemas/CustomData'

          example: []
    UpdateAllocationRequest:
      type: object
      description: Request body for updating an allocation
      properties:
        allocation:
          type: object
          description: The allocation fields to update
          properties:
            customData:
              type: array
              items:
                $ref: '#/components/schemas/CustomData'
          example: example_value
        expenseIds:
          type: array
          description: The expense IDs to which this update applies
          items:
            type: string

    # ── Comment Models ─────────────────────────────────────────────────
          example: []
    Comment:
      type: object
      description: A comment on a report or expense
      properties:
        comment:
          type: string
          description: The comment text content
          example: example_value
        author:
          type: object
          description: The user who authored the comment
          properties:
            userId:
              type: string
              format: uuid
              description: The author's user identifier
            firstName:
              type: string
              description: The author's first name
            lastName:
              type: string
              description: The author's last name
          example: example_value
        creationDate:
          type: string
          format: date-time
          description: When the comment was created
          example: '2026-01-15T10:30:00Z'
        isLatest:
          type: boolean
          description: Whether this is the most recent comment
          example: true
        isAuditLog:
          type: boolean
          description: Whether this is a system-generated audit entry

          example: true
    CommentRequest:
      type: object
      description: Request body for creating or updating a comment
      required:
      - comment
      properties:
        comment:
          type: string
          description: The comment text content

    # ── Workflow Models ────────────────────────────────────────────────
          example: example_value
    ReportApproveRequest:
      type: object
      description: Request body for approving or recalling a report
      properties:
        comment:
          type: string
          description: An optional comment accompanying the approval
          example: example_value
        expenseRejectedComment:
          type: string
          description: >-
            Comment explaining why specific expenses are being rejected
            within an otherwise approved report
          example: example_value
        statusId:
          type: string
          description: Target status identifier
          example: '500123'
        expectedStepCode:
          type: string
          description: >-
            The expected current workflow step code for optimistic
            concurrency control
          example: example_value
        expectedStepSequence:
          type: integer
          description: >-
            The expected current workflow step sequence number for
            optimistic concurrency control

          example: 10
    ReportSendBackRequest:
      type: object
      description: Request body for sending a report back to the submitter
      required:
      - comment
      properties:
        comment:
          type: string
          description: >-
            Explanation of why the report is being returned for corrections
          example: example_value
        expectedStepCode:
          type: string
          description: The expected current workflow step code
          example: example_value
        expectedStepSequence:
          type: integer
          description: The expected current workflow step sequence number

          example: 10
    CostObjectForApprover:
      type: object
      description: >-
        A cost object relevant to an approver, representing how expenses
        on a report map to organizational cost structures.
      properties:
        costObjectId:
          type: string
          description: Unique identifier of the cost object
          example: '500123'
        name:
          type: string
          description: Display name of the cost object
          example: Example Title
        code:
          type: string
          description: Cost object code

    # ── Form Field Models ──────────────────────────────────────────────
          example: example_value
    FormField:
      type: object
      description: >-
        A configured form field with its metadata, display properties,
        and validation rules.
      properties:
        id:
          type: string
          description: The field identifier
          example: abc123
        label:
          type: string
          description: The localized display label
          example: Example Title
        controlType:
          type: string
          description: The UI control type for rendering
          example: example_value
        dataType:
          type: string
          description: The data type of the field value
          example: example_value
        isRequired:
          type: boolean
          description: Whether the field is mandatory
          example: true
        isCustom:
          type: boolean
          description: Whether this is a customer-configured custom field
          example: true
        maxLength:
          type: integer
          description: Maximum allowed character length
          example: 10
        sequence:
          type: integer
          description: Display order sequence number

    # ── Common Models ──────────────────────────────────────────────────
          example: 10
    Link:
      type: object
      description: A HATEOAS hypermedia link for resource navigation
      properties:
        rel:
          type: string
          description: The link relation type
          example: example_value
        href:
          type: string
          format: uri
          description: The target URI
          example: https://www.example.com
        hreflang:
          type: string
          description: Language of the target resource

          example: example_value
    ResourceCreatedResponse:
      type: object
      description: Response returned when a resource is successfully created
      properties:
        uri:
          type: string
          format: uri
          description: The URI of the newly created resource

          example: https://www.example.com
    ErrorResponse:
      type: object
      description: Standard error response
      properties:
        errorId:
          type: string
          description: Unique identifier for this error occurrence
          example: '500123'
        errorMessage:
          type: string
          description: Human-readable error description
          example: example_value
        httpStatus:
          type: string
          description: The HTTP status code as a string
          example: example_value
        path:
          type: string
          description: The request path that triggered the error
          example: example_value
        timestamp:
          type: string
          format: date-time
          description: When the error occurred
          example: '2026-01-15T10:30:00Z'
        validationErrors:
          type: array
          description: Detailed field-level validation failures
          items:
            type: object
            properties:
              source:
                type: string
                description: The field or parameter that failed validation
              message:
                type: string
                description: Description of the validation failure

          example: []
  responses:
    BadRequest:
      description: >-
        The request was malformed or contained invalid parameters.
        Check the validationErrors array for field-level details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: >-
        Authentication failed. The bearer token is missing, expired,
        or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: >-
        The authenticated user does not have the required scope or
        permission to perform this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: >-
        The requested resource (report, expense, allocation, or user)
        was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: >-
        The request conflicts with the current state of the resource.
        For example, attempting to delete a submitted report or approve
        a report that has already been processed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: >-
        An unexpected server error occurred. Retry the request or
        contact SAP Concur support with the Concur-CorrelationId header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'