The SAP Concur List Item API provides an automated solution to clients who would like to retrieve and add list items. Use of the API is subject to some limitations on the volume of list data. You may need to manage the initial load of large volumes of data via a file import due to capacity limitations. This is also true if ongoing maintenance of list values involves a large volume.
Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.
Name | Description | Endpoint |
---|---|---|
spend.listitem.read |
Read-only access to spend list items. | GET |
spend.listitem.write |
Read and write access to spend list items. | GET, POST, PUT |
spend.listitem.delete |
Delete capabilities for spend list items. | DELETE |
Users must be an Expense, Invoice, Shared or Request Configuration Administrator in order to perform POST and PUT actions.
This API supports both company level and user level access tokens.
Retrieve a list item by ID.
spend.listitem.read
- Refer to Scope Usage for full details.
GET /list/v4/items/{itemId}
Name | Type | Description |
---|---|---|
Accept-Language |
string |
Language code. Default: Company defined default language |
itemId |
string |
Required The unique identifier of the list item. |
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 NamespaceGET https://us.api.concursolutions.com/list/v4/items/{itemId}
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}
HTTP/1.1 200
concur-correlationid: 663d7795-fc21-4d98-ba31-87be20aeacd2
content-length: 360
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 14:07:25 GMT
etag: "0950be10ca5a9f5069898e2468db6e137"
cache-control: no-cache, private
{
"id": "63b7fbd9-ae08-0840-abdb-62b0b9160081",
"code": "ITEM-SECOND LEVEL ITEM",
"shortCode": "SECOND LEVEL ITEM",
"value": "SECOND LEVEL ITEM",
"parentId": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
"level": 2,
"isDeleted": false,
"lists": [
{
"id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"hasChildren": false
}
]
}
Create a list item with the provided request body.
spend.listitem.write
- Refer to Scope Usage for full details.
POST /list/v4/items
Name | Type | Description |
---|---|---|
Accept-Language |
string |
Language code. Default: Company defined default language |
listItem |
- | Required List Item object that is created for the company. |
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 NamespacePOST https://us.api.concursolutions.com/list/v4/lists
Accept: application/json
Accept-Language: en
Content-Type: application/json
Authorization: Bearer {token}
Example 1 (create first level list item):
{
"listId": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"shortCode": "ITEM",
"value": "ITEM"
}
Example 2 (create second level list item by parent list item ID):
{
"listId": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"parentId": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
"shortCode": "SECOND LEVEL ITEM",
"value": "SECOND LEVEL ITEM"
}
Example 3 (create second level list item by parent list item code):
{
"listId": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"parentCode": "ITEM",
"shortCode": "SECOND LEVEL ITEM",
"value": "SECOND LEVEL ITEM"
}
HTTP/1.1 201
concur-correlationid: 85b8deb7-db84-4dfb-bdca-d4bccb2ef06e
content-length: 282
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 13:47:25 GMT
location: http://localhost:5000/list/v4/items/7c6d0435-c4d1-8b48-8492-7e7b625e148d
cache-control: no-cache, private
Example 1:
{
"id": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
"code": "ITEM",
"shortCode": "ITEM",
"value": "ITEM",
"parentId": null,
"level": 1,
"isDeleted": false,
"lists": [
{
"id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"hasChildren": false
}
]
}
Example 2 and Example 3:
{
"id": "63b7fbd9-ae08-0840-abdb-62b0b9160081",
"code": "ITEM-SECOND LEVEL ITEM",
"shortCode": "SECOND LEVEL ITEM",
"value": "SECOND LEVEL ITEM",
"parentId": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
"level": 2,
"isDeleted": false,
"lists": [
{
"id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"hasChildren": false
}
]
}
Update a list item with provided request body.
spend.listitem.write
- Refer to Scope Usage for full details.
PUT /list/v4/items/{itemId}
Name | Type | Description |
---|---|---|
Accept-Language |
string |
Language code. Default: Company defined default language |
itemId |
string |
Required The unique identifier of the list item. |
listItem |
- | Required List Item object that is updated. |
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 NamespacePUT https://us.api.concursolutions.com/list/v4/items/7c6d0435-c4d1-8b48-8492-7e7b625e148d
Accept: application/json
Accept-Language: en
Content-Type: application/json
Authorization: Bearer {token}
{
"shortCode": "ITEM",
"value": "ITEM UPDATED"
}
HTTP/1.1 200
concur-correlationid: 27abed5d-20cc-4edf-81b6-3e2dbf70ba39
content-length: 289
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 14:16:21 GMT
cache-control: no-cache, private
{
"id": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
"code": "ITEM",
"shortCode": "ITEM",
"value": "ITEM UPDATED",
"parentId": null,
"level": 1,
"isDeleted": false,
"lists": [
{
"id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"hasChildren": true
}
]
}
Delete a list item by list item ID. A list item shared between multiple lists will be deleted from all lists.
spend.listitem.delete
- Refer to Scope Usage for full details.
DELETE /list/v4/items/{itemId}
Name | Type | Description |
---|---|---|
itemId |
string |
Required The unique identifier of the list item. |
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 NamespaceDELETE https://us.api.concursolutions.com/list/v4/items/7c6d0435-c4d1-8b48-8492-7e7b625e148d
Accept: application/json
Authorization: Bearer {token}
HTTP/1.1 204
concur-correlationid: d92ab0c7-510b-4730-99a8-14a79ad99b7c
date: Wed, 08 Jul 2020 14:16:21 GMT
cache-control: no-cache, private
Delete a list item by list item ID from a particular list. This enables deleting a shared list item from one list, not all lists.
spend.listitem.delete
- Refer to Scope Usage for full details.
DELETE /list/v4/lists/{listId}/items/{itemId}
Name | Type | Description |
---|---|---|
listId |
string |
Required The unique identifier of the list. |
itemId |
string |
Required The unique identifier of the list item. |
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 NamespaceDELETE https://us.api.concursolutions.com/list/v4/lists/80edb3fa-c15e-a34a-b97f-f2ec291ab44f/items/7c6d0435-c4d1-8b48-8492-7e7b625e148d
Accept: application/json
Authorization: Bearer {token}
HTTP/1.1 204
concur-correlationid: d92ab0c7-510b-4730-99a8-14a79ad99b7c
date: Wed, 08 Jul 2020 14:16:21 GMT
cache-control: no-cache, private
Retrieve the direct children for a given list item.
spend.listitem.read
- Refer to Scope Usage for full details.
GET /list/v4/items/{itemId}/children?page={page}&sortBy={sortBy}
Name | Type | Description |
---|---|---|
Accept-Language |
string |
Language code. Default: Company defined default language |
hasChildren |
boolean |
If true , displays items with children. |
isDeleted |
boolean |
If true , displays deleted items. |
itemId |
string |
Required The unique identifier of the list item. |
page |
integer |
Page number starting from 1. Default: 1 |
shortCode |
string |
Filter capabilities for shortCode . |
shortCodeOrValue |
string |
Filter capabilities for value or shortCode . |
sortBy |
string |
Field to sort by. Supported values: value , shortCode . Default: value |
sortDirection |
string |
Sort direction. Supported values: asc , desc |
value |
string |
Filter capabilities for value . |
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 NamespaceGET https://us.api.concursolutions.com/list/v4/items/7c6d0435-c4d1-8b48-8492-7e7b625e148d/children?page=1&sortBy=value
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}
HTTP/1.1 200
concur-correlationid: 50dcec14-c984-479c-84e2-186a7e62f87e
content-length: 449
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 14:27:13 GMT
etag: "05cb0f0ed5a73bedf1e8cd4171e360e41"
cache-control: no-cache, private
{
"links": [],
"content": [
{
"id": "63b7fbd9-ae08-0840-abdb-62b0b9160081",
"code": "ITEM-SECOND LEVEL ITEM",
"shortCode": "SECOND LEVEL ITEM",
"value": "SECOND LEVEL ITEM",
"parentId": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
"level": 2,
"isDeleted": false,
"lists": [
{
"id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"hasChildren": false
}
]
}
],
"page": {
"size": 100,
"totalElements": 1,
"totalPages": 1,
"number": 1
}
}
Retrieve the direct children for a given list item in a particular list. For a list item shared between multiple lists, this API enables retrieving children from a particular list.
spend.listitem.read
- Refer to Scope Usage for full details.
GET /list/v4/lists/{listId}/items/{itemId}/children?page={page}&sortBy={sortBy}
Name | Type | Description |
---|---|---|
Accept-Language |
string |
Language code. Default: Company defined default language |
hasChildren |
boolean |
If true , displays items with children. |
isDeleted |
boolean |
If true , displays deleted items. |
itemId |
string |
Required The unique identifier of the list item. |
listId |
string |
Required The unique identifier of the list. |
page |
integer |
Page number starting from 1. Default: 1 |
shortCode |
string |
Filter capabilities for shortCode . |
shortCodeOrValue |
string |
Filter capabilities for value or shortCode . |
sortBy |
string |
Field to sort by. Supported values: value , shortCode . Default: value |
sortDirection |
string |
Sort direction. Supported values: asc , desc |
value |
string |
Filter capabilities for value . |
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 NamespaceGET https://us.api.concursolutions.com/list/v4/lists/80edb3fa-c15e-a34a-b97f-f2ec291ab44f/items/7c6d0435-c4d1-8b48-8492-7e7b625e148d/children?page=1&sortBy=value
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}
HTTP/1.1 200
concur-correlationid: 50dcec14-c984-479c-84e2-186a7e62f87e
content-length: 449
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 14:27:13 GMT
etag: "05cb0f0ed5a73bedf1e8cd4171e360e41"
cache-control: no-cache, private
{
"links": [],
"content": [
{
"id": "63b7fbd9-ae08-0840-abdb-62b0b9160081",
"code": "ITEM-SECOND LEVEL ITEM",
"shortCode": "SECOND LEVEL ITEM",
"value": "SECOND LEVEL ITEM",
"parentId": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
"level": 2,
"isDeleted": false,
"lists": [
{
"id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"hasChildren": false
}
]
}
],
"page": {
"size": 100,
"totalElements": 1,
"totalPages": 1,
"number": 1
}
}
Retrieves the first level list items for a given List ID.
spend.listitem.read
- Refer to Scope Usage for full details.
GET /list/v4/lists/{listId}/children?page={page}&sortBy={sortBy}
Name | Type | Description |
---|---|---|
Accept-Language |
string |
Language code. Default: Company defined default language |
hasChildren |
boolean |
If true , displays items with children. |
isDeleted |
boolean |
If true , displays deleted items. |
listId |
string |
Required The unique identifier of the list. |
page |
integer |
Page number starting from 1. Default: 1 |
shortCode |
string |
Filter capabilities for shortCode . |
shortCodeOrValue |
string |
Filter capabilities for value or shortCode . |
sortBy |
string |
Field to sort by. Supported values: value , shortCode . Default: value |
sortDirection |
string |
Sort direction. Supported values: asc , desc |
value |
string |
Filter capabilities for value . |
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 NamespaceGET https://us.api.concursolutions.com/list/v4/lists/7c6d0435-c4d1-8b48-8492-7e7b625e148d/children?page=1&sortBy=value
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}
HTTP/1.1 200
concur-correlationid: 50dcec14-c984-479c-84e2-186a7e62f87e
content-length: 449
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 14:27:13 GMT
etag: "05cb0f0ed5a73bedf1e8cd4171e360e41"
cache-control: no-cache, private
{
"links": [],
"content": [
{
"id": "63b7fbd9-ae08-0840-abdb-62b0b9160081",
"code": "ITEM-FIRST LEVEL ITEM",
"shortCode": "FIRST LEVEL ITEM",
"value": "FIRST LEVEL ITEM",
"level": 1,
"isDeleted": false,
"lists": [
{
"id": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
"hasChildren": false
}
]
}
],
"page": {
"size": 100,
"totalElements": 1,
"totalPages": 1,
"number": 1
}
}
The List Item API supports filtering on the Retrieve First Level Children Items of a List,
Retrieve Children of a List Item, and Retrieve Children of a List Item by List APIs.
The filter may be applied to the value
, shortCode
, and shortCodeOrValue
query parameters.
GET /lists/v4/lists/{listId}/children?value=test
GET /lists/v4/lists/{listId}/children?shortCode=test
GET /lists/v4/lists/{listId}/children?shortCodeOrValue=test
GET /lists/v4/items/{listId}/children?value=test
GET /lists/v4/items/{listId}/children?shortCode=test
GET /lists/v4/items/{listId}/children?shortCodeOrValue=test
GET /list/v4/lists/{listId}/items/{itemId}/children?value=test
GET /list/v4/lists/{listId}/items/{itemId}/children?shortCode=test
GET /list/v4/lists/{listId}/items/{itemId}/children?shortCodeOrValue=test
The general format of a query syntax parameter is as follows:
/lists/v4/resource?field_name=<op>:<value>
field_name
- The name of the field that will be compared against.
op
- (Optional) The comparison operator to use when comparing the specified value to the field. Defaults to eq
.
value
- The value being checked for.
Ensure the url generated is properly URL encoded
. For example, if you have a field_name
or value
with a &
, please convert it to %26
.
Examples:
/lists/v4/lists/{listId}/children?value=PSO
/lists/v4/lists/{listId}/children?shortCode=sw:British
/lists/v4/lists/{listId}/children?value=ew:Airlines&shortCode=not:British+Airlines
/lists/v4/lists/{listId}/children?value=sw:Question%3FMark
Complex queries using parentheses are not supported.
There is basic support for OR functionality with the shortCodeOrValue
query parameter. shortCodeOrValue
will search both shortCode
and value
properties and return all resources that match either field.
eq
returns results where a field is equal to the supplied value. This is the default if no operator is specified.
/lists/v4/lists/{listId}/children?value=test
/lists/v4/items/{itemId}/children?value=eq:test
/lists/v4/items/{itemId}/children?shortCodeOrValue=eq:test
cp
returns results where the provided pattern exists in the specified field.
/lists/v4/lists/{listId}/children?value=cp:test
not
returns results where a field is not equal to the supplied value.
/lists/v4/items/{itemId}/children?shortCode=not:test
sw
returns results where a field startsWith the supplied value.
/lists/v4/lists/{listId}/children?shortCode=sw:test
ew
returns results where a field endsWith the supplied value.
/lists/v4/items/{itemId}/children?value=ew:test
Name | Type | Format | Description |
---|---|---|---|
id |
string |
uuid |
The unique identifier of the list item. |
code |
string |
- | List item long code. |
shortCode |
string |
- | List item short code. |
value |
string |
- | List item value. |
parentId |
string |
uuid |
The unique identifier of the parent list item. |
listId |
string |
uuid |
The unique identifier of the list that contains the list item. |
level |
integer |
int32 |
Level of the list item within the list. |
lists |
ListItemMemberList |
- | The unique identifiers of the lists that contains the list item. The list item may exist under one or more lists. |
isDeleted |
boolean |
true /false |
Indicates the deleted state of the item in a particular list. If false , the list item is not deleted from one or more lists. The lists field will include only the lists that contain the list item in a not-deleted state. isDeleted will only be true when the list item is deleted from all lists. The lists field will include all lists that contain the list item. |
Name | Type | Format | Description |
---|---|---|---|
listId |
string |
uuid |
Required The unique identifier of the list that contains the list item. |
parentCode |
string |
- | The long code of parent list item. |
parentId |
string |
uuid |
The unique identifier of parent list item. |
shortCode |
string |
- | Required List item short code. |
value |
string |
- | Required List item value. |
Name | Type | Format | Description |
---|---|---|---|
shortCode |
string |
- | Required List item short code. |
value |
string |
- | Required List item value. |
Name | Type | Format | Description |
---|---|---|---|
id |
string |
uuid |
The unique identifier of the list that contains the list item. |
hasChildren |
boolean |
true /false |
If true , the list item has children in this particular list. |
Name | Type | Format | Description |
---|---|---|---|
content |
array |
ListItem |
- |
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. |
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. |
Name | Type | Format | Description |
---|---|---|---|
message |
string |
- | The detailed message of the validation error. |
source |
string |
- | The type of validation that failed. |
Name | Type | Format | Description |
---|---|---|---|
message |
string |
- | The detailed error message. |
id |
string |
- | The identifier of the error. |
Name | Type | Format | Description |
---|---|---|---|
number |
integer |
int32 |
The page number. |
size |
integer |
int32 |
The number of items 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. |