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
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
- 200 OK
- 400 Bad Request - Company does not exist
- 401 Unauthorized - Access Denied
- 500 Internal Server Error
Headers
concur-correlationid
is a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7232 ETag
- RFC 7234 Cache-Control
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
- 201 Created
- 400 Bad Request - Company does not exist
- 401 Unauthorized
- 403 Forbidden
- 415 Unsupported Media Type
- 500 Internal Server Error
Headers
concur-correlationid
is a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7231 Location
- RFC 7234 Cache-Control
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
- 200 OK
- 400 Bad Request - Company does not exist
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found - List not found
- 415 Unsupported Media Type
- 500 Internal Server Error
Headers
concur-correlationid
is a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7234 Cache-Control
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
- 200 OK
- 400 Bad Request - Company does not exist
- 401 Unauthorized
- 404 Not Found
- 500 Internal Server Error
Headers
concur-correlationid
is a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7232 ETag
- RFC 7234 Cache-Control
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
- RFC 7231 Accept
- RFC 7231 Accept-Language
- RFC 7231 Content-Type
- RFC 7232 If-None-Match
- RFC 7235 Authorization
Response
Status Codes
- 200 OK
- 400 Bad Request - Company does not exist
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found - List category not found
- 415 Unsupported Media Type
- 500 Internal Server Error
Headers
concur-correlationid
is a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7232 ETag
- RFC 7234 Cache-Control
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
- 204 No Content - List resource no longer in system
- 400 Bad Request - List could not be deleted
- 401 Unauthorized
- 403 Forbidden
- 500 Internal Server Error
Headers
concur-correlationid
is a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Date
- RFC 7234 Cache-Control
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. |
Link
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. |