Workflows v4

The Workflows v4 APIs are used to get information about as well as take action on a report’s workflow.

Prior Versions

  • Report Workflow Action v1.1 documentation is available here.

Limitations

Access to this documentation does not provide access to the API.

Products and Editions

  • Concur Expense Professional Edition
  • Concur Expense Standard Edition

Scope Usage

Name Description Endpoint
expense.report.read Get information about expense reports. GET
expense.report.readwrite Read and write expense report headers. PATCH, POST
expense.report.workflowstatus.write Approve or Send Back the Report in the workflow PATCH

Dependencies

SAP Concur clients must purchase Concur Expense in order to use this API. Please contact your SAP Concur representative for more information.

Approve or Send Back or Recall a Report

  • The Approve function advances the specified report to the next step (use the short URL Approve API if the report is in a system step).
  • The Send Back function sends back the specified report to the report owner.
  • The Recall function moves the specified report to an unsubmitted state.

Access Token Usage

Approve and Send Back short URL (with no userId and contextType) APIs support the company level access token. Approve, Send Back and Recall long URL (with userId and contextType) APIs support user level access tokens.

Scopes

expense.report.workflowstatus.write - Refer to Scope Usage for full details.

Parameters

Name Type Format Description
userId string - Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userId.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported value for Recall API: TRAVELER, PROXY. Supported value for Approve and Send Back API: MANAGER
reportId string - Required The unique identifier of the report that is being approved or sent back or recalled.

Headers

Request

URI Template

https://{datacenterURI}/expensereports/v4/reports/{reportId}/approve
https://{datacenterURI}/expensereports/v4/reports/{reportId}/sendBack
https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/approve
https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/sendBack
https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/recall

Curl Example (short and long URL)

curl --location --request PATCH 'https://us.api.concursolutions.com/expensereports/reports/764428DD6A664AF0BFCB/approve' \
--header 'Authorization: Bearer {access_token}' 
--header 'Content-Type: application/json' 
--data-raw '{
"comment":"Approved"
}'

curl --location --request PATCH 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/MANAGER/reports/764428DD6A664AF0BFCB/approve' \
--header 'Authorization: Bearer {access_token}' 
--header 'Content-Type: application/json'
--data-raw '{
"comment":"Approved",
"expenseRejectedComment":"Expense rejected"
}'

REST Design Specification

PATCH operations in Expense Reports v4 conform to the JSON Merge Patch specification:

Response

Successful Response

204 No Content

Status Codes

Payload

Submit a Specific Report

The submit operation moves the specified report from un-submitted to submitted state for approval.

Access Token Usage

This API supports both company level and user level access tokens.

Scopes

expense.report.readwrite - Refer to Scope Usage for full details.

Parameters

Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID.
reportId string - Required The unique identifier of the report that is being read.

Headers

Request

URI Template

https://{datacenterURI}/expensereports/v4/users/{userId}/reports/{reportId}/submit

Payloads

  • Request: None
  • Response: None

Curl Example

curl --location --request PATCH https://us.api.concursolutions.com/expensereports/v4/users/aa024d31-95eb-4270-b9yz-cb6b5f558a7c/reports/97F923D6935D4426BF9C/submit
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json'

Response

204 No Content

Status Codes

Get Cost Objects for a Specific Report

This endpoint retrieves all cost objects for a report that the calling approver or their delegators is able to approve. If the workflow setting “Filter expenses to those that are applicable to Cost Object” is set to false, then this endpoint will return all cost objects related to the report regardless of if the approver has permission to approve them.

Access Token Usage

This API supports both company level and user level access tokens.

Scopes

expense.report.read - Refer to Scope Usage for full details.

expense.report.readwrite - Refer to Scope Usage for full details.

Parameters

Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID.
reportId string - Required The unique identifier of the report that is being read.

Headers

Request

URI Template

https://{datacenterURI}/expensereports/v4/users/{userId}/reports/{reportId}/costObjectsForApprover

Curl Example

curl --location --request GET https://us.api.concursolutions.com/expensereports/v4/users/aa024d31-95eb-4270-b9yz-cb6b5f558a7c/reports/97F923D6935D4426BF9C/costObjectsForApprover
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json'

Response

Success Response

[
  {
    "name": "Development",
    "approvedAmount": {
      "value": 150,
      "currencyCode": "USD"
    },
    "claimedAmount": {
      "value": 150,
      "currencyCode": "USD"
    },
    "approverId": "aa024d31-95eb-4270-b9f8-cb6b5f558a7c",
    "expenses": [
      {
        "approvedAmount": {
          "value": 100,
          "currencyCode": "USD"
        },
        "postedAmount": {
          "value": 100,
          "currencyCode": "USD"
        },
        "id": "080286AAA453AD449CB4DD6128BC9BA5"
      },
      {
        "approvedAmount": {
          "value": 50,
          "currencyCode": "USD"
        },
        "postedAmount": {
          "value": 50,
          "currencyCode": "USD"
        },
        "id": "1C7DE29EA1CFB34AAE819264683BAF87"
      }
    ],
    "isOwnedByCaller": true,
    "isFullyApproved": false,
    "isApprovableAsUser": true,
    "isApprovableAsDelegate": false
  }
]

Exception Response

{
  "timestamp": "2023-04-12T15:22:44.248Z",
  "httpStatus": "string",
  "errorMessage": "string",
  "errorId": "string",
  "validationErrors": [
    {
      "source": "string",
      "message": "string",
      "id": "string"
    }
  ],
  "customResponseData": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "path": "string"
}

Status Codes

Schema

CostObjectForApprover

Name Type Format Description
name string - Required The name of the cost object.
approvedAmount Amount - Required The approved amount of the cost object expense(s) in the report currency.
claimedAmount Amount - Required The approved amount of the cost object expense(s) in the report currency.
approverId String - Required The unique identifier of the cost object approver.
expenses CostObjectExpense - Required TA list of expenses associated with the cost object.
isOwnedByCaller boolean true/false Required Whether the caller is one of the cost object owners.
isFullyApproved boolean true/false Required Whether the cost object flow is completed.
isApprovableAsUser boolean true/false Required Whether the cost object is pending approval by the calling approver.
isApprovableAsDelegate boolean true/false Required Whether the cost object flow is pending approval by the calling delegate.

CostObjectExpense

Name Type Format Description
approvedAmount Amount - Required The approved amount of the expense, in the report currency.
claimedAmount Amount - Required The approved amount of the expense, in the report currency.
id String - Required The unique identifier for the expense.

Amount

Name Type Format Description
currencyCode string - Required The 3-letter ISO 4217 currency code for the expense report currency, based on the user’s assigned reimbursement currency when the report was created. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona
value number double Required The amount in the defined currency.

ReportSendBackRequest

Name Type Format Description
comment string - Required Comments for sending back the report.
expectedStepCode string - If expectedStepCode is provided the report must be in an external validation step with same value as the passed step code.
expectedStepSequence string - If expectedStepSequence is provided the report must be on the step as expectedStepSequence.

ReportApproveRequest

Name Type Format Description
comment string - Approver comments.
expenseRejectedComment string - This comment identifies why some of the expense is rejected on this report. Required if the report has rejected expense(s).
expectedStepCode string - If expectedStepCode is provided the report must be in an external validation step with same value as the passed step code.
expectedStepSequence string - If expectedStepSequence is provided the report must be on the step as expectedStepSequence.
statusId string - Status that will be assigned to the report by this workflow transition. Default value: A_APPR

Error

Name Type Format Description
customResponseData object - The custom parameters related to error.
errorId string - The unique identifier of the error associated with the response.
errorMessage string - Required The detailed error message.
httpStatus string - Required The http response code and phrase for the response.
path string - Required The URI of the attempted request.
timestamp string date-time Required The time when the error was captured.
validationErrors ValidationError - The validation error messages.

ValidationError

Name Type Format Description
id string - The ID of the validation error.
message string - The detailed message of the validation error.
source string - The type of validation which failed.

On this page