Get iTwin list groups - Forms

Forms

Download API definition:

get https://dev-api.bentley.com/forms/itwins/{iTwinId}/list-groups[?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.

If specified, only list groups whose display names contain the given string will be returned in the results.

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.v2+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
}

Options Tree

A tree of nested options objects where a key at depth n represents a valid option in the nth dropdown list when the keys above it are selected in the prior lists. For example, if optionsTree.foo.bar.baz is not null or undefined, then baz is a valid option in the third list if foo and bar are selected in the first and second lists, respectively. Keys for the final list will have values equal to empty objects.

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
}

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

options-tree

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/options-tree"
        },
        "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?