SAP Concur Comments API

openapi: 3.1.0
info:
  title: SAP Concur Expense Report Allocations Comments 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: Comments
  description: Operations for creating, retrieving, updating, and deleting comments at the report header or individual expense level.
paths:
  /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'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    CommentRequest:
      type: object
      description: Request body for creating or updating a comment
      required:
      - comment
      properties:
        comment:
          type: string
          description: The comment text content
          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
    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
    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:
    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'
    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:
    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
    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
    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
  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.