Web Services for Concur Expense - Updating Expense Reports and Entries

[TriciaConnolly]

Introduction

Concur offers a wide variety of Expense APIs, this blog post is to help guide anyone interested in using Web Services to retrieve and/or update expense report and expense report entry data

The APIs mentioned in this blog work with SAP Concur Expense Standard and Professional Editions. The following scenarios will be explained along with examples in this post:

1. Retrieving header data for all expense reports
2. Retrieving expense report header data for a specific ReportIDRetrieve Unique User ID
3. Retrieving expense entries for a specific ReportID
4. Retrieving expense entry data for a specific Expense ID
5. Updating expense report header data
   
   1. Update Header Text Field
   2. Update Header Connect List Fields
6. How to update expense report entry fields

Prior to making any of the requests below, you will need to have authenticated and have a current Access Token. If you are unfamiliar with this process, I highly suggest reviewing my colleague Tim's blog post on Authentication. I have also saved the steps in this walkthrough in a Postman Collection which you can download here .

Detailed Walkthrough

First let's get familiar with some of the key variables needed to make these requests. This blog post will walk you through how to get all of these values and I have them built into my Postman collection linked in the section above.

1. Retrieving header data for all expense reports

Before we get into updating expense reports, it might be useful to know what reports are currently in Concur and some high-level attributes like their report ID, approval or payment status, and when they were submitted. To get a response that includes report header data for all reports in Concur, you can use the following:

GET https://{{dataCenterURI}}/api/v3.0/expense/reports?user=ALL

There are a wide variety of parameters you can use to filter this request, but you should always include the "user" parameter. This page lists all available params and how they should be formatted - Expense Report V3 Parameters.

2. Retrieving expense report header data for a specific ReportID

Prior to updating expense report header data, it's helpful to see what data and fields already exist. To retrieve the expense report header data you will need the unique user ID and the report ID. Instructions for how to retrieve the unique user ID are in section 2a.

GET https://{{dataCenterURI}}/expensereports/v4/users/{{userID}}/context/{{contextType}}/reports/{{reportID}}

2a - Retrieve Unique User ID -

Before we make any updates to expense report data or retrieve specific report data, we will need to retrieve the unique identifier of the SAP Concur user. The unique identifier will be used for the "userId" parameter and can be found using the Identity v4 API like this:

GET https://{{dataCenterURI}}/profile/identity/v4/Users?filter=userName eq "tricia.connolly@tconnolly.com"

*This userID will be used in future requests to make updates to reports!*

3. Retrieving expense entries for a specific ReportID

It will also be helpful to know what entries exist on the report that you are trying to update if plan on updating entry data as well. You will notice that each expense entry has its own unique "expenseId" that will be used in the next few scenarios.

To see expense entries for a report you will need to use the following:

GET https://{{dataCenterURI}}/expensereports/v4/users/{{userID}}/context/{{contextType}}/reports/{{reportID}}/expenses

*Note that each expense has its own expenseID, we will use this going forward*

4. Retrieving expense entry data for a specific Expense ID

You might notice that there is some entry data missing from the request above, specifically, entry custom field data. In order to see the custom field data for an expense entry, you will need to add the expenseID from the last request like this:

GET https://{{dataCenterURI}}/expensereports/v4/users/{{userID}}/context/{{contextType}}/reports/{{reportID}}/expenses/{{expenseID}}

5. Updating expense report header data

Each report header contains a variety of different fields depending on how your Concur site is setup. For the purposes of this blog post, I will be updating a few different fields in my test report header seen in the screenshot below.

5a - Update Header Text Field - 

First, I want to update the free text "Business Purpose" field. To do this I will send the new business purpose value in the body along with the reportId and the userId that we retrieved in the previous steps like this:

PATCH https://{{dataCenterURI}}/expensereports/v4/users/{{userID}}/context/TRAVELER/reports/{{reportID}}

You can expect to receive a "204 No Content" response if the patch is successful.

5b - Update Header Connected List Field- 

Next, I want to make updates to the "Region" and "Department" custom list fields in my report header. To do this, I will follow the 3 steps below:

Step 1 - Get all list data to find the list ID of the list you want to update

GET https://{{dataCenterURI}}/list/v4/lists/

Step 2 - Find the list item ids for the items you want to update using the list ID from step 1

GET https://{{dataCenterURI}}/list/v4/lists/{{listID}}/items

Note - If you are updating a connected or multi-level list, you will also need to find the child list item IDs

GET https://{{dataCenterURI}}/list/v4/lists/{{listID}}/items/{{itemID}}/children

Step 3- Use the list item ID to update the custom list fields

PATCH https://{{dataCenterURI}}/expensereports/v4/users/{{userID}}/context/TRAVELER/reports/{{reportID}}

You can expect to receive a "204 No Content" response if the patch is successful.

6. Updating Expense Report Entry Fields

Updating field values for expense items is just like header level fields, but you will need to include the expenseID that we retrieved in example 3 above. In this example I'm going to update the expense entry expense type and  the transaction amount. You can find a list of expense types and their ids using  Expense Group Configurations v3.0.

PATCH https://{{dataCenterURI}}/expensereports/v4/users/{{userID}}/context/{{contextType}}/reports/{{reportID}}/expenses/{{expenseID}}

You can expect to receive a "204 No Content" response if the patch is successful.

Conclusion

Using the examples in this post you should be able to view and update existing expense report and expense entry data. I recommend using this post to complement Concurs existing API documentation. The following were referenced while making this post -

• Expenses v4
• Reports v4
• Reports v3
• List v4
• Expense Group Configurations v3

Feel free to comment if you have any questions. Thanks!