openapi: 3.1.0
info:
  title: SAP Concur Expense Report Allocations Workflows 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: Workflows
  description: Operations for submitting, approving, recalling, and sending back expense reports through the approval workflow.
paths:
  /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'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    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'
    Unauthorized:
      description: Authentication failed. The bearer token is missing, expired, or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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'
    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'
  parameters:
    reportId:
      name: reportId
      in: path
      required: true
      description: The unique identifier of the expense report
      schema:
        type: string
    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
    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
  schemas:
    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
    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: []
    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
    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
          example: example_value
  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.