As a Technical Consultant at SAP Concur, I get to work with clients across various industries to understand their business and processes so I can provide guidance to ensure a successful deployment and integration of SAP Concur solutions.   After implementation is complete, there is still a need of ongoing processes to identify and update data for quality assurance.   One key component that requires ongoing maintenance is list data.

In SAP Concur, lists provide a structured way to manage and control various aspects of expense management.  These lists can include customer lists, project codes, expense categories, and more.  Clients that are looking to retrieve, create, update, and delete list items in a more dynamic integration should consider implementing Concur Web Services.  Compared to a daily scheduled batch job, Concur Web Services allow for a more accurate database, by making real time updates.  In this blog, I will go over the latest APIs available that can be used for managing list data.

Prerequisites

Please make sure that you are familiar with how to get started with web services.  You can read this blog going over just that written by my colleague, Tim Chapman here. I will be using the environment variables referenced in his blog.

The APIs mentioned in this blog will work with these SAP Concur solutions:

• Concur Expense Professional Edition
• Concur Expense Standard Edition
• Concur Invoice Professional Edition
• Concur Invoice Standard Edition
• Concur Request Professional Edition
• Concur Request Standard Edition

Introduction

Managing your lists is essential to ensure that users have access to the most updated, relevant information when submitting expenses, managing projects, or performing other tasks within the system. It also enables administrators to define and enforce business rules and policies by controlling the options available in the various lists.   To help with effectively managing lists in SAP Concur, organizations can leverage the following APIs to add, edit and delete list items to match a list data that is maintained externally (example: department or project codes).

• List v4 – to view your configured lists within SAP Concur products and create new lists.
• List Item v4 – provides an automated solution to retrieve and add list items.

In this blog, I will walk you through some common request methods you can do with these APIs using postman, with a focus on managing list items for an existing list.

1. Retrieve lists.
2. Retrieve list item (2.a) or retrieve connected list Item (2.b).
3. Add a new list item (3.a) or add a second level list item (3.b).
4. Update a list item.
5. Delete a list item from a list.

Information about the List v4, List Item v4, as well as SAP Concur’s other APIs can be found here.  I have also saved the steps in this walkthrough in a Postman Collection which you can download here.

Detailed Walkthrough

1 – Retrieving a List of the Lists

You can start by checking what lists are currently configured in your environment, and what their correlated list ids are.

• API Endpoint: /lists
• Request Method
  • GET https://{{dataCenterURI}}/list/v4/lists/

In postman, there is an option to view the results in ‘Pretty’ view which formats JSON responses in a easier to read view, which is the format you’ll see on all my screenshots.

You can filter your results (by category type, level count, etc.) on each request, as well as sort the results using any of the available parameters listed in the List v4 documentation.

Highlighted in the screenshot above, you can see the id (listId) for one of my lists, labeled ‘*Country-Dept-Activity’ in the body of the response.  I will reference this to review the list items in this list in the next step.  Please note that if you have more than 100 lists, you will have to specify page number, for example:

• GET https://{{dataCenterURI}}/list/v4/lists?page=2.

(Please note clients should not add or delete lists without contacting Concur Support.)

2.A– Retrieving list items of a list

Now that I have the listId from step 1, I can view all the list items currently in list labeled ‘*Country-Dept-Activity’.

• API Endpoint: /items
• Request method
  • GET https://{{dataCenterURI}}//list/v4/lists/{{listId}}/items

This list I am using happens to be a 3-level connected list, that is organized by country, department, and activity. List should always correspond with what you see under list management (accessible by expense admins only), so I can always check the UI for additional validation.   For additional information regarding list management, you can view the list management documentation here.

Currently I only have 1 level-one list item here for the purposes of this walkthrough, which is the country ‘US’.   This is a parent list item, which we can tell since ‘hasChildren’=True.  Highlighted is the id (itemId) for ‘US’.

2.B – Retrieving children items of a parent list item

With the itemId (53c12e49-69d8-5943-8a48-92c7078ea43f )of parent item ‘US’, I can then retrieve the children list items by running the following:

• Request method
  • GET https://{{dataCenterURI}}/list/v4/lists/{{listId}}/items/{{itemId}}/children

Please note in this case, the following variables would be replaced with actual values retrieved from the previous responses.  For example, these would be the values in my case:

• listId =55571409-aa64-7044-aaf9-5d6662fc8ed0
• itemId=53c12e49-69d8-5943-8a48-92c7078ea43f

As you follow along these steps against your own list and list items, make sure you update the variables in your requests for all steps going forward with the correct ids from your responses accordingly.

I currently have one department so far, which is ‘Finance’.  However you could then repeat the step again at every level to retrieve its children list items at every level if needed.

3.A – Add a list items

Now let’s add another country besides item ‘US’ to my country list.  There are 3 required parameters that need to be included in the request (listId, shortCode, & value).

• API Endpoint: /items
• Request Method
  • POST https://{{dataCenterURI}}/list/v4/items
• Required parameters (provided via JSON)

As you can see in the screenshot above, after provided the required parameters, I was able to add listId (75aeef38-6601-764b-88f0-73c0994f9b36), with shortCode=’0002’ and value=’CA’, which is Canada.  I now have 2 countries.

3.B – Create a second level list item in a connected list:

Now, what if I wanted to add a second level list item (department) under country US?  Let’s add a list item for Marketing.  To do this, I will now have to include the parentCode parameter in my JSON, see the screenshot below.

• API Endpoint: /items
• Request Method
  • POST https://{{dataCenterURI}}/list/v4/items
• Required parameters (provided via JSON)

Now I should be able to see the ‘Marketing’ list item under ‘US’ when I review the list management menu.

4 – To update a list item:

What if we need to edit an existing list item?  We will need the itemId to send a PUT request.  Let’s update the value for ‘MKT’ from ‘Marketing’ to ‘Sales and Marketing’, see below.

• API Endpoint: /items
• Request method
  • PUT https://{{dataCenterURI}}/list/v4/items/{{itemId}}
• Required parameters

We can then see the new value reflected under list management in the UI:

5 – To delete a list item from a list:

The last task I want to cover is deleting a list item.  I now will delete the second level list item, ‘MKT’.  For this, I will need to reference both the itemId and its listId ‘*Country-Dept-Activity’)

• API Endpoint: /items
• Request Method
  • DEL https://{{dataCenterURI}}/list/v4/lists/{{listId}}/items/{{itemId}}

As long as there is no error code returned, the list item was successfully deleted.

Conclusion

As you get familiar with interacting with Concur’s List and List Items API, your team can begin to automate list data synchronization.  Below is a general outline of what you next steps might look like:

1. Set up your development environment, including Implementing authentication.
2. Fetch and process retrieved data as per your requirements using the appropriate endpoints.
3. Store or sync the data. This may involve storing it in a database, writing it to a file, or syncing it with another system.
4. Schedule automation after determining how often the synchronization process should run (or trigger when change event occurs).
5. Implement error handling and logging mechanisms. This will help troubleshoot issues and ensure the reliability of your automation solution.
6. Regularly monitor and maintain your automation solution. Keep an eye on any changes to the Concur APIs and update your solution accordingly.

Automating list data synchronization helps ensure users are always selecting from the most up-to-date list – reducing errors and creation of duplicate records. Remember to refer to the Concur API documentation for specific details on the List API endpoints, request/response formats, and any additional requirements.

By leveraging Concur APIs, businesses can streamline their processes, improve data accuracy, and enhance the overall user experience. With Concur’s commitment to innovation and continuous improvement, we can expect these APIs to evolve and expand, providing even more value to organizations in the future.

(Disclaimer: Please do not edit any lists related to your employee groups or any list that starts with ‘VAT’ or ‘Vendors’ to avoid unexpected system wide impact.)