Get form data relationships - Forms

Forms

get https://dev-api.bentley.com/forms/{id}/relationships

Retrieves a list of form data relationships that include the given instance.

A relationship links two form data instances together and includes metadata explaining the meaning of the relationship. For example, one form can be a subtask of another or be raised from another. Two forms may be related regardless of whether they were made from the same form definition or not. This endpoint returns a summary of each related form along with a link to retrieve the full form.

It is possible for the queried form to have no relationships, in which case this endpoint will return an empty array instead of throwing an error. If the queried form doesn't exist at all, a 404 Not Found error 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

Yes

ID of form to get relationships with.

Request headers

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

Indicates that the form was found and its relationships were retrieved. The relationship metadata and the forms that they relate to this form will be returned in the `relationships` array (this array can be empty, in case no relationships exist on the queried form).

json

{
    "relationships": [{
        "id": "EM30083GVABAB-CDE-_Rt4TjOQ4hNpFK2200WUcydG9.EM38003GVEFEF-GHI-_Rt4TjOQ40077KnbQnWUcyeH8",
        "type": "Escalation",
        "direction": "forward",
        "binding": "Road Survey",
        "form": {
            "id": "EM38003GVEFEF-GHI-_Rt4TjOQ40077KnbQnWUcyeH8",
            "displayName": "Urgent road deficiency",
            "type": "Inspection Failure",
            "discipline": "Issue",
            "state": "Open",
            "_links": {
                "self": {
                    "href": "https://api.bentley.com/forms/EM38003GVEFEF-GHI-_Rt4TjOQ40077KnbQnWUcyeH8"
                }
            }
        }
    }, {
        "id": "EM30083GVABAB-CDE-_Rt4TjOQ4hNpFK2200WUcydG9.EM49923GVzUzU_pqrs_Rt4TjOQ43399KNBqnWUcrf09",
        "type": "Related",
        "form": {
            "id": "EM49923GVzUzU_pqrs_Rt4TjOQ43399KNBqnWUcrf09",
            "displayName": "Inspection June 2026",
            "type": "Inspection",
            "discipline": "Inspection",
            "state": "Closed",
            "_links": {
                "self": {
                    "href": "https://api.bentley.com/forms/EM49923GVzUzU_pqrs_Rt4TjOQ43399KNBqnWUcrf09"
                }
            }
        }
    }]
}

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

{
    "$ref": "#/components/examples/401.HeaderNotFound.example"
}

Response 404 Not Found

This response indicates that the specified form data instance does not exist or is inaccessible.

json

{
    "error": {
        "code": "FormDataNotFound",
        "message": "Requested form data is not available.",
        "target": "id"
    }
}

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

link

href

String

json

{
    "type": "object",
    "properties": {
        "href": {
            "type": "string"
        }
    },
    "additionalProperties": false
}

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
}

Form Data Relationship type

The type of relationship this is. Related: generic relationship with no parent or child. Subtask: The child form is a subtask of the parent form. RaisedFrom: The child form was an issue raised from the current form. Escalation: The child form is a high-priority escalation of the parent form. Note that Escalation relationships, and the two forms they relate, cannot be deleted.

String

Subtask

String

RaisedFrom

String

Escalation

String

json

{
    "enum": [
        "Related",
        "Subtask",
        "RaisedFrom",
        "Escalation"
    ],
    "type": "string",
    "description": "The type of relationship this is. `Related`: generic relationship with no parent or child. `Subtask`: The child form is a subtask of the parent form. `RaisedFrom`: The child form was an issue raised from the current form. `Escalation`: The child form is a high-priority escalation of the parent form. Note that Escalation relationships, and the two forms they relate, cannot be deleted.",
    "title": "Form Data Relationship type"
}

Form Data Relationship direction

Indicates whether this is a parent or child relationship. forward means that the form queried for in the URL is the parent, and backward means that the form queried for is the child. Related relationships do not have a parent/child distinction.

forward

String

backward

String

null

String

json

{
    "enum": [
        "forward",
        "backward",
        null
    ],
    "type": "string",
    "nullable": true,
    "description": "Indicates whether this is a parent or child relationship. `forward` means that the form queried for in the URL is the parent, and `backward` means that the form queried for is the child. `Related` relationships do not have a parent/child distinction.",
    "title": "Form Data Relationship direction"
}

Form Data Relationship

String

An identifier for this relationship.

form.id

String

The form data instance's unique ID. Can be used to query for all of its properties using the 'Get form data details' endpoint.

form.type

String

Read-only. Describes which domain of work the form involves, which determines what applications will show it. This is automatically set based on the associated form definition referenced by the formId property.

form.state

String

Indicates whether the form's current workflow status is an Open, Closed, or Draft status.

form._links.self

link

form.discipline

String

Read-only. Describes the discipline to associate the form with.

form.displayName

String, null

Name that should be used to display this form to users.

Form Data Relationship type

form-data-relationship-type

binding

String, null

The property that the relationship is bound to, if applicable. For instance, if the relationship was created from a Survey control, this will be set to the property name that Survey control is bound to. If bound to a custom property e.g. foo, will include the path to the property, in this case properties.foo.

Form Data Relationship direction

form-data-relationship-direction, null

json

{
    "type": "object",
    "title": "Form Data Relationship",
    "properties": {
        "id": {
            "type": "string",
            "description": "An identifier for this relationship."
        },
        "form": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "description": "The form data instance's unique ID. Can be used to query for all of its properties using the 'Get form data details' endpoint."
                },
                "type": {
                    "type": "string",
                    "description": "Read-only. Describes which domain of work the form involves, which determines what applications will show it. This is automatically set based on the associated form definition referenced by the `formId` property."
                },
                "state": {
                    "enum": [
                        "Closed",
                        "Open",
                        "Draft"
                    ],
                    "type": "string",
                    "description": "Indicates whether the form's current workflow status is an Open, Closed, or Draft status."
                },
                "_links": {
                    "type": "object",
                    "properties": {
                        "self": {
                            "$ref": "#/components/schemas/link"
                        }
                    },
                    "description": "A link to retrieve this form data instance's details using the 'Get form data details' endpoint.",
                    "additionalProperties": false
                },
                "discipline": {
                    "type": "string",
                    "description": "Read-only. Describes the discipline to associate the form with."
                },
                "displayName": {
                    "type": "string",
                    "nullable": true,
                    "description": "Name that should be used to display this form to users."
                }
            },
            "additionalProperties": false
        },
        "type": {
            "enum": [
                "Related",
                "Subtask",
                "RaisedFrom",
                "Escalation"
            ],
            "type": "string",
            "description": "The type of relationship this is. `Related`: generic relationship with no parent or child. `Subtask`: The child form is a subtask of the parent form. `RaisedFrom`: The child form was an issue raised from the current form. `Escalation`: The child form is a high-priority escalation of the parent form. Note that Escalation relationships, and the two forms they relate, cannot be deleted.",
            "title": "Form Data Relationship type",
            "$ref": "#/components/schemas/form-data-relationship-type"
        },
        "binding": {
            "type": "string",
            "nullable": true,
            "description": "The property that the relationship is bound to, if applicable. For instance, if the relationship was created from a Survey control, this will be set to the property name that Survey control is bound to. If bound to a custom property e.g. `foo`, will include the path to the property, in this case `properties.foo`."
        },
        "direction": {
            "enum": [
                "forward",
                "backward",
                null
            ],
            "type": "string",
            "nullable": true,
            "description": "Indicates whether this is a parent or child relationship. `forward` means that the form queried for in the URL is the parent, and `backward` means that the form queried for is the child. `Related` relationships do not have a parent/child distinction.",
            "title": "Form Data Relationship direction",
            "$ref": "#/components/schemas/form-data-relationship-direction"
        }
    },
    "additionalProperties": false
}

Form Data Relationships List

relationships

form-data-relationship[]

json

{
    "type": "object",
    "title": "Form Data Relationships List",
    "properties": {
        "relationships": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/form-data-relationship"
            }
        }
    },
    "additionalProperties": false
}

Was this page helpful?