SAP Concur Expenses API

openapi: 3.1.0
info:
  title: SAP Concur Expense Report Allocations Expenses 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: Expenses
  description: Operations for retrieving, updating, and deleting expense entries (line items) on a report, and retrieving itemizations.
paths:
  /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'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    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
    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
          example: 10
    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
          example: '500123'
    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: []
    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
    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
    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: []
    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.0
        currencyCode:
          type: string
          description: ISO 4217 three-letter currency code
          minLength: 3
          maxLength: 3
          examples:
          - USD
    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
    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
    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: []
    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
    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.
    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'
    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
    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'
          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: []
  parameters:
    expenseId:
      name: expenseId
      in: path
      required: true
      description: The unique identifier of the expense entry
      schema:
        type: string
    reportId:
      name: reportId
      in: path
      required: true
      description: The unique identifier of the expense report
      schema:
        type: string
    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
    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
        form

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sap-concur/refs/heads/main/openapi/sap-concur-expenses-api-openapi.yml