Get list group - Issues | iTwin Platform

Issues

Download API definition:

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

get https://dev-api.bentley.com/issues/formDefinitions/{id}/listGroups/{listGroupId}

Use this request to look up a list group, which is a nested object structure that defines the options available in a chain of cascading list form controls. (Cascading lists are a set of <select> elements where only the first one is initially enabled until an option in it is selected, and then, depending on which option was selected, the available options in the next list can vary.) Each property in the structure represents an option in a select list, and its children represent options that become available in the next list in the chain if that option is selected.

Sample Explanation

The sample for the 200 response shows an example of a list group that could be assigned to 3 controls in a form to let the user pick an American football team by conference, division, and name. Since the result has two properties ("AFC" and "NFC") as direct children of the "optionsTree" property, the first list in the cascading list chain would have two options--"AFC" and "NFC". Whichever option is chosen, its child properties become available for selection in the second list, and so forth. For example, if "AFC" and "North" were chosen for the first two lists respectively, the third list would show the available options "Bengals", "Browns", "Ravens", and "Steelers". These four properties just have empty objects as their values because this particular list group only has three layers; these options are the final options in the chain and have no descendants.

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

Yes

The ID of the form definition this list group is used in.

listGroupId

Yes

The ID of the list group to get.

Request headers

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

{
    "listGroup": {
        "id": "1d49859f-0757-423a-b850-9b6ae0a088c6",
        "displayName": "Football Teams",
        "createdDateTime": "2024-08-21T15:44:09.0000000+00:00",
        "lists": ["Conference", "Division", "Team"],
        "optionsTree": {
            "AFC": {
                "North": {
                    "Steelers": {},
                    "Browns": {},
                    "Bengals": {},
                    "Ravens": {}
                },
                "East": {
                    "Patriots": {},
                    "Bills": {},
                    "Dolphins": {},
                    "Jets": {}
                },
                "South": {
                    "Titans": {},
                    "Jaguars": {},
                    "Texans": {},
                    "Colts": {}
                },
                "West": {
                    "Chiefs": {},
                    "Broncos": {},
                    "Raiders": {},
                    "Chargers": {}
                }
            },
            "NFC": {
                "North": {
                    "Vikings": {},
                    "Packers": {},
                    "Bears": {},
                    "Lions": {}
                },
                "East": {
                    "Eagles": {},
                    "Giants": {},
                    "Cowboys": {},
                    "Washington": {}
                },
                "South": {
                    "Saints": {},
                    "Buccaneers": {},
                    "Panthers": {},
                    "Falcons": {}
                },
                "West": {
                    "49ers": {},
                    "Seahawks": {},
                    "Rams": {},
                    "Cardinals": {}
                }
            }
        }
    }
}

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 list group or its associated form definition was not found.

json

{
    "error": {
        "code": "ListGroupNotFound",
        "message": "Requested list group is not available.",
        "target": "listGroupId"
    }
}

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 Details Response

listGroup

list-group-details

json

{
    "type": "object",
    "title": "List Group Details Response",
    "required": [
        "listGroup"
    ],
    "properties": {
        "listGroup": {
            "$ref": "#/components/schemas/list-group-details"
        }
    },
    "additionalProperties": false
}

Was this page helpful?