List v4

The Lists APIs allow you to view your configured lists within SAP Concur products and create new lists. The lists are shared between multiple SAP Concur products.

Prior Versions

List v3 documentation is available here.

Limitations

This API is only available to partners who have been granted access by us. Access to this documentation does not provide access to the API.

Process Flow

A process flow diagram of the List API

Products and Editions

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

Scope Usage

Name Description Endpoints
spend.list.read Read-only access to spend lists. GET
spend.list.write Read and write access to spend lists. GET, POST, PUT
spend.list.delete Delete capabilities for spend lists. DELETE

Dependencies

Users must be an Expense, Invoice, Shared or Request Configuration Administrator in order to perform POST, PUT, and DELETE actions.

Access Token Usage

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

Get All Lists

Returns all lists for a company.

Scopes

spend.list.read - Refer to Scope Usage for full details.

Request

URI

Template
GET /list/v4/lists
Parameters
Name Type Description
Accept-Language string Language code. Default: Company defined default language
page integer($int32) Page number starting from 1. Default: 1
sortBy string Field to order by {name, levelcount, listcategory}. Sort by name is ordered by value. Sort by levelcount is ordered by levelCount. Sort by listcategory is ordered by category.type. Default: name
sortDirection string Sort direction {asc, desc}. Default: asc

Headers

Response

Status Codes

Headers

Payload

Example

Request

GET https://us.api.concursolutions.com/list/v4/lists?page=1
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}

Response

HTTP/1.1 200
concur-correlationid: 746696dc-8782-4642-815d-3080640786c7
content-length: 5632
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 02:45:48 GMT
etag: "02ebe9fc5c950a031f85c57ac91a0babb"
cache-control: no-cache, private

{
    "links": [],
    "content": [
        {
            "id": "a80a5070-3951-4316-886a-a60ab790f06b",
            "value": "Airlines",
            "levelCount": 1,
            "searchCriteria": "TEXT",
            "displayFormat": "(CODE) TEXT",
            "category": {
                "id": "a2dfc451-8f3c-410e-a5f2-20d79c8fc3dc",
                "type": "Vendor"
            },
            "isReadOnly": false,
            "isDeleted": false
        },
        {
            "id": "8652cdf9-c12b-4051-b8d1-80e20840ce9b",
            "value": "Employee Groups",
            "levelCount": 1,
            "searchCriteria": "TEXT",
            "displayFormat": "(CODE) TEXT",
            "category": {
                "id": "d232b1e3-43da-4a2d-adaf-eb948045e8cf",
                "type": "Configuration"
            },
            "isReadOnly": false,
            "isDeleted": false
        }
    ],
    "page": {
        "size": 100,
        "totalElements": 2,
        "totalPages": 1,
        "number": 1
    }
}

Create a New List

Creates a new list.

Scopes

spend.list.write - Refer to Scope Usage for full details.

Request

URI

Template
POST /list/v4/lists
Parameters
Name Type Description
Accept-Language string Language code. Default: Company defined default language
listRequest - Required List object that is created for the company.

Headers

Payload

Response

Status Codes

Headers

Payload

Example

Request

POST https://us.api.concursolutions.com/list/v4/lists
Accept: application/json
Content-Type: application/json
Authorization: Bearer {token}
Example 1:
{
  "searchCriteria": "TEXT",
  "value": "Custom List",
  "displayFormat": "(CODE) TEXT"
}
Example 2:
{
  "searchCriteria": "TEXT",
  "value": "Custom Vendor List",
  "categoryId": "a2dfc451-8f3c-410e-a5f2-20d79c8fc3dc",
  "displayFormat": "(CODE) TEXT"
}

Response

HTTP/1.1 201
concur-correlationid: 5512c7be-3fab-4d65-ae69-8a74a04a0c7f
content-length: 269
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 03:00:42 GMT
location: http://us.api.concursolutions.com/list/v4/lists/80edb3fa-c15e-a34a-b97f-f2ec291ab44f
cache-control: no-cache, private

{
    "id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
    "value": "Custom List",
    "levelCount": 1,
    "searchCriteria": "TEXT",
    "displayFormat": "(CODE) TEXT",
    "category": {
        "id": "77b85a76-8157-0c4e-b5e3-7785d8de1a6b",
        "type": "Normal"
    },
    "isReadOnly": false,
    "isDeleted": false
}

Update a List

Update an existing list.

Scopes

spend.list.write - Refer to Scope Usage for full details.

Request

URI

Template
PUT /list/v4/lists/{listId}
Parameters
Name Type Description
Accept-Language string Language code. Default: Company defined default language
listId string($uuid) Required The unique identifier of the list.
listUpdate - Required List object that is updated for the company.

Headers

Payload

Response

Status Codes

Headers

Payload

Example

Request

PUT https://us.api.concursolutions.com/list/v4/lists/80edb3fa-c15e-a34a-b97f-f2ec291ab44f
Accept: application/json
Accept-Language: en
Content-Type: application/json
Authorization: Bearer {token}

{
  "value": "Custom List Renamed",
  "searchCriteria": "TEXT",
  "displayFormat": "(CODE) TEXT"
}

Response

HTTP/1.1 200
concur-correlationid: e3a4d4cf-e1b2-4f22-a95c-b5bb8a2cb0e1
content-length: 275
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 03:24:16 GMT
cache-control: no-cache, private

{
  "id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
  "value": "Custom List Renamed",
  "levelCount": 1,
  "searchCriteria": "TEXT",
  "displayFormat": "(CODE) TEXT",
  "category": {
    "id": "77b85a76-8157-0c4e-b5e3-7785d8de1a6b",
    "type": "Normal"
  },
  "isReadOnly": false,
  "isDeleted": false
}

Get a List by List ID

Returns a list by a List ID.

Scopes

spend.list.read - Refer to Scope Usage for full details.

Request

URI

Template
GET /list/v4/lists/{listId}
Parameters
Name Type Description
Accept-Language string Language code. Default: Company defined default language
listId string($uuid) Required The unique identifier of the list.

Headers

Response

Status Codes

Headers

Payload

Example

Request

GET https://us.api.concursolutions.com/list/v4/lists/80edb3fa-c15e-a34a-b97f-f2ec291ab44f
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}

Response

HTTP/1.1 200
concur-correlationid: 6a5803f6-b63b-49d8-88b3-872f456206c2
content-length: 275
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 02:45:48 GMT
etag: "08514b0fce90d634c211aba29d1cc94c2"
cache-control: no-cache, private

{
  "id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
  "value": "Custom List Renamed",
  "levelCount": 1,
  "searchCriteria": "TEXT",
  "displayFormat": "(CODE) TEXT",
  "category": {
    "id": "77b85a76-8157-0c4e-b5e3-7785d8de1a6b",
    "type": "Normal"
  },
  "isReadOnly": false,
  "isDeleted": false
}

Get a List by Category ID

Returns a list by a category ID.

Scopes

spend.list.read - Refer to Scope Usage for full details.

Request

URI

Template
GET /list/v4/categories/{categoryId}/lists
Parameters
Name Type Description
Accept-Language string Language code. Default: Company defined default language
categoryId string($uuid) Required The unique identifier of the category.
page integer($int32) Page number starting from 1. Default: 1

Headers

Response

Status Codes

Headers

Payload

Example

Request

GET https://us.api.concursolutions.com/list/v4/categories/77b85a76-8157-0c4e-b5e3-7785d8de1a6b/lists?page=1
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}

Response

HTTP/1.1 200
concur-correlationid: 0e80dff7-93b7-4b43-a1b6-a91ebe5c55f0
content-length: 364
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 02:45:48 GMT
etag: "02e60234cf6ae61aadd7f066e839b07fb"
cache-control: no-cache, private

{
  "links": [],
  "content": [
    {
      "id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
      "value": "Custom List Renamed",
      "levelCount": 1,
      "searchCriteria": "TEXT",
      "displayFormat": "(CODE) TEXT",
      "category": {
        "id": "77b85a76-8157-0c4e-b5e3-7785d8de1a6b",
        "type": "Normal"
      },
      "isReadOnly": false,
      "isDeleted": false
    }
  ],
  "page": {
    "size": 100,
    "totalElements": 1,
    "totalPages": 1,
    "number": 1
  }
}

Remove a List

Delete a list.

Scopes

spend.list.delete - Refer to Scope Usage for full details.

Request

URI

Template
DELETE /list/v4/lists/{listId}
Parameters
Name Type Description
listId string($uuid) Required The unique identifier of the list.

Headers

Response

Status Codes

Headers

Payload

Example

Request

DELETE https://us.api.concursolutions.com/list/v4/lists/80edb3fa-c15e-a34a-b97f-f2ec291ab44f
Accept: application/json
Authorization: Bearer {token}

Response

HTTP/1.1 204
concur-correlationid: d92ab0c7-510b-4730-99a8-14a79ad99b7c
date: Wed, 08 Jul 2020 02:45:48 GMT
cache-control: no-cache, private

Schema

Paged Resources List Response

Name Type Format Description
content array ListResponse -
page PageMetadata - Metadata for the page of data returned.
links array Link Href links to the next, previous, first, and/or last pages of data.

List Response

Name Type Format Description
id string uuid Unique identifier of a list.
value string - Name of the list.
levelCount integer int32 Number of levels in the list.
searchCriteria string - What attribute to search by {TEXT, CODE}.
displayFormat string - Whether the code or value is displayed first {(CODE) TEXT, TEXT (CODE)}.
category ListCategory - The category of the list.
isReadOnly boolean true/false If true, the list is read-only.
isDeleted boolean true/false If true, the list has been deleted.

List Category

Name Type Format Description
id string uuid Unique identifier of a category.
type string - Category type.

List Request

Name Type Format Description
searchCriteria string - What attribute to search by. Supported values: TEXT, CODE
value string - Required Name of the list.
categoryId string uuid The unique identifier of the category that the list belongs to.
displayFormat string - Whether we display code or value first. Supported values: (CODE) TEXT, TEXT (CODE)

List Update

Name Type Format Description
value string - Required Name of the list.
searchCriteria string - What attribute to search by. Supported values: TEXT, CODE
displayFormat string - Whether we display code or value first. Supported values: (CODE) TEXT, TEXT (CODE)

Message

Name Type Format Description
message string - The detailed error message.
id string - The identifier of the error.

Page Metadata

Name Type Format Description
number integer int32 The page number.
size integer int32 The number of lists per page, which is fixed at 100.
totalElements integer int32 The number of total elements.
totalPages integer int32 The number of total pages.
Name Type Format Description
rel string - The link relation.
href string - The link href.

Error Message

Name Type Format Description
error Message - 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 array ValidationError The validation error messages.

Validation Error

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

On this page