List Item v4

The 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

Access to this documentation does not provide access to the API.

Prior Versions

  • List Items v3 documentation is available here.
  • List Items v1 documentation is available here.

Process Flow

A process flow diagram of the List Item 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 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

Dependencies

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

Access Token Usage

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

Retrieve a List Item by ID

Retrieve a list item by ID.

Scopes

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

Request

URI

Template
GET /list/v4/items/{itemId}
Parameters
Name Type Description
Accept-Language string Language code. Default: Company defined default language
itemId string Required The unique identifier of the list item.

Headers

Response

Status Codes

Headers

Payload

Example

Request

GET https://us.api.concursolutions.com/list/v4/items/{itemId}
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}

Response

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

Create a list item with the provided request body.

List Item Code Naming Restrictions

Hyphens are not supported and should not be used in item names or item codes. When an item name or item code with a hyphen is created or saved, the hyphen might be interpreted as a delimiter (separator) which can have unpredictable results on the saved data including possible corruption of the item list.

Scopes

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

Request

URI

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

Headers

Payload

Response

Status Codes

Headers

Payload

Example

Request

POST https://us.api.concursolutions.com/list/v4/items
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"
}

Response

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

Update a list item with provided request body.

List Item Code Naming Restrictions

Hyphens are not supported and should not be used in item names or item codes. When an item name or item code with a hyphen is created or saved, the hyphen might be interpreted as a delimiter (separator) which can have unpredictable results on the saved data including possible corruption of the item list.

Scopes

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

Request

URI

Template
PUT /list/v4/items/{itemId}
Parameters
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.

Headers

Payload

Response

Status Codes

Headers

Payload

Example

Request

PUT 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"
}

Response

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

Delete a list item by list item ID. A list item shared between multiple lists will be deleted from all lists. In a connected list, when deleting a list item, all children of that list item are also deleted.

Scopes

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

Request

URI

Template
DELETE /list/v4/items/{itemId}
Parameters
Name Type Description
itemId string Required The unique identifier of the list item.

Headers

Response

Status Codes

Headers

Payload

Example

Request

DELETE https://us.api.concursolutions.com/list/v4/items/7c6d0435-c4d1-8b48-8492-7e7b625e148d
Accept: application/json
Authorization: Bearer {token}

Response

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 from a List

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.

Scopes

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

Request

URI

Template
DELETE /list/v4/lists/{listId}/items/{itemId}
Parameters
Name Type Description
listId string Required The unique identifier of the list.
itemId string Required The unique identifier of the list item.

Headers

Response

Status Codes

Headers

Payload

Example

Request

DELETE 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}

Response

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 Children of a List Item

Retrieve the direct children for a given list item.

Scopes

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

Request

URI

Template
GET /list/v4/items/{itemId}/children?page={page}&sortBy={sortBy}
Parameters
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.

Headers

Response

Status Codes

Headers

Payload

Example

Request

GET 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}

Response

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 Children of a List Item by List

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.

Scopes

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

Request

URI

Template
GET /list/v4/lists/{listId}/items/{itemId}/children?page={page}&sortBy={sortBy}
Parameters
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.

Headers

Response

Status Codes

Headers

Payload

Example

Request

GET 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}

Response

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 First Level Children Items of a List

Retrieves the first level list items for a given List ID.

Scopes

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

Request

URI

Template
GET /list/v4/lists/{listId}/children?page={page}&sortBy={sortBy}
Parameters
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.

Headers

Response

Status Codes

Headers

Payload

Example

Request

GET 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}

Response

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
  }
}

Filtering

Supported APIs

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.

Retrieve First Level Children Items of a List
GET /list/v4/lists/{listId}/children?value=test
GET /list/v4/lists/{listId}/children?shortCode=test
GET /list/v4/lists/{listId}/children?shortCodeOrValue=test
Retrieve Children of a List Item
GET /list/v4/items/{listId}/children?value=test
GET /list/v4/items/{listId}/children?shortCode=test
GET /list/v4/items/{listId}/children?shortCodeOrValue=test
Retrieve Children of a List Item by List
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

Query Syntax

The general format of a query syntax parameter is as follows:

/list/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:

/list/v4/lists/{listId}/children?value=PSO

/list/v4/lists/{listId}/children?shortCode=sw:British

/list/v4/lists/{listId}/children?value=ew:Airlines&shortCode=not:British+Airlines

/list/v4/lists/{listId}/children?value=sw:Question%3FMark

Conjunction Operators

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.

Comparison Operators

Equals

eq returns results where a field is equal to the supplied value. This is the default if no operator is specified.

/list/v4/lists/{listId}/children?value=test

/list/v4/items/{itemId}/children?value=eq:test

/list/v4/items/{itemId}/children?shortCodeOrValue=eq:test

Contains Pattern

cp returns results where the provided pattern exists in the specified field.

/list/v4/lists/{listId}/children?value=cp:test

Not

not returns results where a field is not equal to the supplied value.

/list/v4/items/{itemId}/children?shortCode=not:test

Starts With

sw returns results where a field startsWith the supplied value.

/list/v4/lists/{listId}/children?shortCode=sw:test

Ends With

ew returns results where a field endsWith the supplied value.

/list/v4/items/{itemId}/children?value=ew:test

Schema

List Item

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.

List Item Create

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.

List Item Update

Name Type Format Description
shortCode string - Required List item short code.
value string - Required List item value.

List Item Member List

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.

Paged Resources List Item

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.

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.

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 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.

On this page