Get iTwin list groups - Issues

Issues

Download API definition:

This API is deprecated. Please upgrade to the current version of this API as soon as possible.

This operation is a Technical Preview and is available for testing purposes only. Do not use in production.

get https://dev-api.bentley.com/issues/iTwins/{iTwinId}/listGroups[?search]

Retrieves the list of list groups in the chosen iTwin. List groups govern the options that appear for the user to select in cascading list controls. These are a series of dropdown list controls in a form definition where the options available in each control beyond the first vary depending on which options were selected in the preceding controls.

By default, this endpoint gets all list groups in the iTwin. If search is specified, only list groups whose names include the given search string (case-insensitive) will be returned.

Authentication

Requires Authorization header with valid Bearer token for scope itwin-platform.

For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.

Request

Request parameters

iTwinId

Yes

The ID of the iTwin to get list groups for.

Optionally provide a string to filter by. List groups will only be returned in the results if their display name contains the string.

Request headers

Prefer

Indicates a level of details in the response.

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

Setting to application/vnd.bentley.itwin-platform.v1+json is recommended.

Response

Response 200 OK

json

{
    "listGroups": [{
        "id": "876f3da1-ae96-4ab5-84b4-9fa059b6e2d4",
        "displayName": "Sample AB",
        "createdDateTime": "2024-08-21T15:44:09.0000000+00:00",
        "lists": ["Letter", "Number"]
    }, {
        "id": "c2b67110-f1f1-4c72-9d89-18a5d666dcd8",
        "displayName": "Football Teams",
        "createdDateTime": "2024-07-25T21:18:09.0000000+00:00",
        "lists": ["Conference", "Division", "Team"]
    }]
}

Response 401 Unauthorized

This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.

json

{
    "error": {
        "code": "HeaderNotFound",
        "message": "Header Authorization was not found in the request. Access denied."
    }
}

Response 404 Not Found

This response indicates that the iTwin with the specified ID does not exist or is inaccessible to the user due to insufficient permissions. (For security reasons, the response will not differ between inaccessible and missing projects.)

json

{
    "error": {
        "code": "iTwinNotFound",
        "message": "Requested iTwin is not available.",
        "target": "iTwinId"
    }
}

Response 429 Too many requests

This response indicates that the client sent more requests than allowed by this API for the current tier of the client.

json

{
    "error": {
        "code": "RateLimitExceeded",
        "message": "The client sent more requests than allowed by this API for the current tier of the client."
    }
}

Response headers

retry-after

Number of seconds to wait until client is allowed to make more requests.

Definitions

Error

Contains error information.

code

String

One of a server-defined set of error codes.

target

String, null

The target of the error.

message

String

A human-readable representation of the error.

json

{
    "type": "object",
    "required": [
        "code",
        "message"
    ],
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "target": {
            "type": "string",
            "nullable": true,
            "description": "The target of the error."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        }
    },
    "description": "Contains error information.",
    "additionalProperties": true
}

Error Response

Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.

error

Error

Error information.

json

{
    "type": "object",
    "title": "Error Response",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "$ref": "#/components/schemas/Error",
            "description": "Error information."
        }
    },
    "description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.",
    "additionalProperties": false
}

Dynamic Object

An object whose properties can vary depending on user customization within the project.

Property values can be:

String: Simple text values, dates (ISO 8601 format), or GUIDs. Examples:
- "Simple text"
- "2026-02-03T00:00:00Z"
- "c7d2ea1b-fad8-4fea-9268-f261232b28d1"
String (Multi-select fields): For multi-select fields, the value should be a string consisting of all of the selected options, separated by commas with no additional spaces between them. Example:
- "Option1,Option2,Option3"
Number: Numeric values (integers or decimals).
Boolean: true or false. Boolean values are used for Checkbox controls.
Array of objects (Grid controls): Arrays are used exclusively for Grid controls, where each element is an object representing a row in the grid. Example:
- [{"Column1": "Value1", "Column2": 123}, {"Column1": "Value2", "Column2": 456}]
Object (Survey Response): An object with a required 'Response' property and optional 'Explanation' property. Example:
- {"Response": "Yes", "Explanation": "Additional details here"}
Object (Weather): An object with weather information. Example:
- {"MaxTemp": 76, "MinTemp": 41, "Temperature": 47, "Description": "Sunny", "WindSpeed": 1, "TimeTaken": "2026-02-06T16:46:52Z", "Units": "e", "Icon": "sun"}

List Group Summary

String

The unique ID of this list group.

lists

String[], null

The names of the lists defined by this list group, from outermost (first) to innermost (last).

displayName

String

The name of this list group, as entered by its creator.

optionsTree

dynamic-object

createdDateTime

Date-time, null

The date and time (UTC) when this list group's file was uploaded.

json

{
    "type": "object",
    "title": "List Group Summary",
    "required": [
        "id",
        "displayName"
    ],
    "properties": {
        "id": {
            "type": "string",
            "description": "The unique ID of this list group."
        },
        "lists": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "nullable": true,
            "description": "The names of the lists defined by this list group, from outermost (first) to innermost (last)."
        },
        "displayName": {
            "type": "string",
            "description": "The name of this list group, as entered by its creator."
        },
        "optionsTree": {
            "$ref": "#/components/schemas/dynamic-object"
        },
        "createdDateTime": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "The date and time (UTC) when this list group's file was uploaded."
        }
    },
    "additionalProperties": false
}

List Group Summary

String

The unique ID of this list group.

lists

String[], null

The names of the lists defined by this list group, from outermost (first) to innermost (last).

displayName

String

The name of this list group, as entered by its creator.

createdDateTime

Date-time, null

The date and time (UTC) when this list group's file was uploaded.

json

{
    "type": "object",
    "title": "List Group Summary",
    "required": [
        "id",
        "displayName"
    ],
    "properties": {
        "id": {
            "type": "string",
            "description": "The unique ID of this list group."
        },
        "lists": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "nullable": true,
            "description": "The names of the lists defined by this list group, from outermost (first) to innermost (last)."
        },
        "displayName": {
            "type": "string",
            "description": "The name of this list group, as entered by its creator."
        },
        "createdDateTime": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "The date and time (UTC) when this list group's file was uploaded."
        }
    },
    "additionalProperties": false
}

List Groups Minimal Response

listGroups

list-group-summary[]

json

{
    "type": "object",
    "title": "List Groups Minimal Response",
    "required": [
        "listGroups"
    ],
    "properties": {
        "listGroups": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/list-group-summary"
            }
        }
    },
    "additionalProperties": false
}

List Groups Representation Response

listGroups

list-group-details[]

json

{
    "type": "object",
    "title": "List Groups Representation Response",
    "required": [
        "listGroups"
    ],
    "properties": {
        "listGroups": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/list-group-details"
            }
        }
    },
    "additionalProperties": false
}

Was this page helpful?