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

Prior Versions

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

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

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

Headers

• RFC 7231 Accept
• RFC 7231 Accept-Language
• RFC 7235 Authorization
• RFC 7232 If-None-Match

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

• List Item
• Error Message

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.

Scopes

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

Request

URI

Template

POST /list/v4/items

Parameters

Headers

• RFC 7231 Accept
• RFC 7231 Accept-Language
• RFC 7231 Content-Type
• RFC 7235 Authorization

Payload

• List Item Create

Response

Status Codes

• 201 Created
• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 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 7231 Location
• RFC 7234 Cache-Control

Payload

• List Item
• Error Message

Example

Request

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

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.

Scopes

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

Request

URI

Template

PUT /list/v4/items/{itemId}

Parameters

Headers

• RFC 7231 Accept
• RFC 7231 Accept-Language
• RFC 7231 Content-Type
• RFC 7235 Authorization

Payload

• List Item Update

Response

Status Codes

• 200 OK
• 400 Bad Request - Company does not exist
• 401 Unauthorized
• 403 Forbidden
• 404 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

• List Item
• Error Message

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.

Scopes

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

Request

URI

Template

DELETE /list/v4/items/{itemId}

Parameters

Headers

• RFC 7231 Accept
• RFC 7235 Authorization

Response

Status Codes

• 204 No Content
• 400 Bad Request - Company does not exist
• 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

• Error Message

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

Headers

• RFC 7231 Accept
• RFC 7235 Authorization

Response

Status Codes

• 204 No Content
• 400 Bad Request - Company does not exist
• 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

• Error Message

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

Headers

• RFC 7231 Accept
• RFC 7231 Accept-Language
• RFC 7232 If-None-Match
• RFC 7235 Authorization

Response

Status Codes

• 200 OK
• 400 Bad Request
• 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

• Paged Resources List Item
• Error Message

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

Headers

• RFC 7231 Accept
• RFC 7231 Accept-Language
• RFC 7232 If-None-Match
• RFC 7235 Authorization

Response

Status Codes

• 200 OK
• 400 Bad Request
• 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

• Paged Resources List Item
• Error Message

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

Headers

• RFC 7231 Accept
• RFC 7231 Accept-Language
• RFC 7232 If-None-Match
• RFC 7235 Authorization

Response

Status Codes

• 200 OK
• 400 Bad Request
• 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

• Paged Resources List Item
• Error Message

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

List Item Create

List Item Update

List Item Member List

Paged Resources List Item

Error Message

Validation Error

Message

Page Metadata

Link