SAP Concur Reports API

openapi: 3.1.0
info:
  title: SAP Concur Expense Report Allocations Reports 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: Reports
  description: Operations for creating, retrieving, updating, and deleting expense reports, as well as retrieving reports pending approval.
paths:
  /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'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    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: []
    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'
    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
    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: []
    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: []
    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
          example: '2026-01-15T10:30:00Z'
    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
    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: []
    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
    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: []
  responses:
    NotFound:
      description: The requested resource (report, expense, allocation, or user) was not found.
      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'
    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'
    Unauthorized:
      description: Authentication failed. The bearer token is missing, expired, or invalid.
      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'
    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'
  parameters:
    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
    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
  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.