Forms Service

View, create, and edit details of forms that have been filled out for an iTwin/project, as well as their comments, attached files, and change history.  Full CRUD functionality is available for form data, with form definitions being available in a read-only context.

Note that throughout this API the terms "form" (by itself) and "form data" both refer to the same thing: data collected from users (generally entered into controls of a UI, or programmatically generated). By contrast, a "form definition" is a piece of metadata connected to form data instances. It determines the "type" of form that is filled out, and in applications that support custom form layouts, it determines how the controls are placed in the user interface.

Form definitions should be added, imported, and customized by project administrators through the Bentley Form Manager web application; they cannot be modified using this API. The app can be found at https://connect-formmanager.bentley.com/designer/#/your-itwin-id (replace `your-itwin-id` with the ID of the actual iTwin or project whose form definitions you want to customize).

## Limits

All API calls that return a list of results will return a maximum of 50 results. Some endpoints support a `$top` parameter to specify a number of results to retrieve (up to the maximum) and a `continuationToken` parameter to continue paging through results, allowing access to results beyond the first 50. These parameters will be included in the documentation for those endpoints.

Clients with a Developer, Partner, or Integrator subscription will be limited to 5000 requests per minute. Clients with a Trial subscription will be limited to 500 requests per minute.

forms

This information is included in every event the webhook will receive.

base-event

content

object

eventType

string

enqueuedDateTime

iTwinId

messageId

webhookId

Base Event

Event that gets triggered when an attachment instance became attached (related) to a form data instance.

forms.attachmentAttached.v1-event

The globally unique identifier of the attachment.

attachmentId

The globally unique identifier of the form data the attachment became attached to.

formId

The discipline of the data instance the attachment became unattached to.

discipline

forms.attachmentAttached.v1

Event that gets triggered when an attachment is unattached from a form.

forms.attachmentUnattached.v1-event

The globally unique identifier of the form data the attachment was unattached from.

The discipline of the data instance the attachment became unattached from.

forms.attachmentUnattached.v1

Event that gets triggered when a comment was created for a particular form data instance.

forms.commentCreated.v1-event

The globally unique identifier of the comment.

commentId

The globally unique identifier of the form data the comment was created for.

The discipline of the data instance the comment was created for.

forms.commentCreated.v1

Event that gets triggered when a form data instance was created.

forms.formCreated.v1-event

Denotes what file or iModel element the data instance was created about. Will be null if not applicable.

sourceEntityId

The globally unique identifier of the form data that was created.

forms.formCreated.v1

Event that gets triggered when a form data instance was deleted.

forms.formDeleted.v1-event

The globally unique identifier of the form data that was deleted.

forms.formDeleted.v1

Event that gets triggered when a form data instance was modified.

forms.formUpdated.v1-event

The globally unique identifier of the form data that was updated.

forms.formUpdated.v1

Event that gets triggered when an external file instance became linked (related) to a form data instance .

forms.externalFileLinked.v1-event

The globally unique identifier of the external file instance that was linked. Will generally consist of `ES_` followed by a GUID.

fileId

The globally unique identifier of the form data the external file was linked to.

The discipline of the data instance the external file was linked to.

forms.externalFileLinked.v1

Event that gets triggered when an external file instance became unlinked from a form data instance . (This means the relationship between the two was deleted, but the external file itself may or may not have been deleted).

forms.externalFileUnlinked.v1-event

The globally unique identifier of the external file instance that was unlinked. Will generally consist of `ES_` followed by a GUID.

The globally unique identifier of the form data the external file was unlinked from.

The discipline of the data instance the external file was unlinked from.

forms.externalFileUnlinked.v1

Event that gets triggered when a form metadata instance (that is, a `Forms_EC_Mapping/Form` instance which groups together one or more FormDefinitions) was deleted.

forms.metadataDeleted.v1-event

The globally unique identifier of the form metadata instance.

metadataId

The discipline of the related data instance.

forms.metadataDeleted.v1

---

Adds a new attachment to the specified form data instance. This only creates the attachment metadata; the file will need to be uploaded through a subsequent PUT call to the URL returned in the Location header of this endpoint's response.

### Permissions

To use this endpoint, the user is required to have the Forms **Comment** (`Forms_CommentAccess`) permission for the iTwin, or for the form's definition if form definition security is specified. (Having **Create/Modify**, **Assign**, **Approve**, or **Full** permission automatically grants the **Comment** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

add-attachment-to-form

The ID of the form data instance to add an attachment to.

OAuth access token with `itwin-platform` scope

Authorization

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

Accept

default

Indicates that the attachment metadata was created successfully. The file should then be uploaded via PUT to the URL in the Location header.

The URL where the attachment file should be uploaded.

Location

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.

HeaderNotFound

InvalidAuthorizationScheme

InvalidHeaderValue

RequiredScopeMissing

Unauthorized

InvalidApplicationTier

This response indicates that the user attempted to add an attachment to a form data instance that does not exist or is inaccessible to the user.

This response indicates that there is a problem with the format of the request body. Most likely causes: The body is not valid JSON, or the 'fileName' property is missing or not a string.

This response indicates that the user has sent too many requests in a given amount of time.

The number of requests exceeds the rate-limit for the client subscription.

retry-after

---

Deletes the specified attachment (including both its metadata and file) from the specified form.

### Permissions

To use this endpoint, the user is required to have the Forms **Comment** (`Forms_CommentAccess`) permission for the iTwin, or for the form's definition if form definition security is specified. (Having **Create/Modify**, **Assign**, **Approve**, or **Full** permission automatically grants the **Comment** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

delete-attachment

The ID of the form data instance from which to delete an attachment.

Indicates that the attachment was successfully deleted. There is no response body in this case.

This response indicates that the attachment with the specified ID does not exist or is inaccessible to the user.

---

Retrieves the actual file contents for the attachment with the given ID. This API will attempt to infer the MIME type to return from the file's extension, but will return the default value of `application/octet-stream` if it does not recognize the extension.

### Permissions

To use this endpoint, the user is required to have the Forms **View** (`Forms_ViewAccess`) permission for the iTwin, or for the form's definition if form definition security is specified. (Having any other Forms permission automatically grants the **View** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-attachment-file-by-id

The ID of the form data instance for which to get an attachment.

The ID of the attachment whose file to retrieve.

This response indicates that the specified attachment does not exist (code = 'AttachmentNotFound') or that the attachment metadata instance exists but does not have an associated file (code = 'FileNotFound').

---

Retrieves the metadata for all files attached to the given form data. In order to get the contents of a file itself, use the `Get attachment file by ID` endpoint, passing the `id` from the metadata object returned by this request as the `attachmentId` parameter of that request.

### Permissions

To use this endpoint, the user is required to have the Forms **View** (`Forms_ViewAccess`) permission for the iTwin, or for the form's definition if form definition security is specified. (Having any other Forms permission automatically grants the **View** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-form-data-attachments

The ID of the form data instance for which to retrieve attachments

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

---

Uploads a file's contents, associating it with the attachment metadata instance with the given ID. The request body is simply the file's bytes. If a file was already uploaded for the attachment with the given ID, that file will be overwritten.

### Permissions

To use this endpoint, the user is required to have the Forms **Comment** permission (`Forms_CommentAccess`) for the iTwin, or for the form's definition if form definition security is specified. (Having **Create/Modify**, **Assign**, **Approve**, or **Full** permission automatically grants the **Comment** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

upload-attachment-file

The ID of the form data instance for which to upload an attachment file.

The ID of the previously created attachment metadata instance for which this file is being uploaded.

Indicates that the attachment file was successfully uploaded

This response indicates that the specified attachment metadata instance does not exist or is inaccessible to the user.

Indicates that the file the user attempted to upload is above the maximum size.

---

Retrieves a reverse-chronologically-ordered list of all changes that have been made to this form data instance, including authors, dates, and old vs. new property values.

### Permissions

To use this endpoint, the user is required to have the Forms **View** (`Forms_ViewAccess`) permission for the iTwin, or for the form's definition if form definition security is specified. (Having any other Forms permission automatically grants the **View** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-audit-trail-for-form-data

The ID of the form data instance for which to retrieve the audit trail.

---

Adds a new comment to the specified form data instance. Only the comment text is needed; the author and creation time will be automatically set by the server.

### Permissions

To use this endpoint, the user is required to have the Forms **Comment** (`Forms_CommentAccess`) permission for the iTwin, or for the form's definition if form definition security is specified. (Having **Create/Modify**, **Assign**, **Approve**, or **Full** permission automatically grants the **Comment** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

add-comment-to-form

The ID of the form data instance to add a comment to.

Indicates that the comment was created successfully

This response indicates that the form data instance the user attempted to add a comment to does not exist or is inaccessible to the user.

This response indicates that there is a problem with the format of the request body. Most likely causes: The body is not valid JSON, or the 'text' property is missing or not a string.

---

Deletes the specified comment from the specified form.

### Permissions

To use this endpoint, the user is required to have the Forms **Comment** (`Forms_CommentAccess`) permission for the iTwin, or for the form's definition if form definition security is specified. (Having **Create/Modify**, **Assign**, **Approve**, or **Full** permission automatically grants the **Comment** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

delete-comment

The ID of the form data instance from which to delete a comment.

Indicates that the comment was successfully deleted. There is no response body in this case.

This response indicates that the comment with the specified ID does not exist or is inaccessible to the user.

---

Retrieves the text and metadata for all comments that have been posted to the given form data instance. If the Prefer header was specified with the value "return=representation", the response will include the email address of each comment author, though this may incur additional processing time.  If there is an extraordinarily large number of comments, only 50 distinct user email addresses will be retrieved and shown. Regardless of the Prefer header value, the "_links" object associated with each comment will provide a link to additional information about the comment author.

### Permissions

To use this endpoint, the user is required to have the Forms **View** (`Forms_ViewAccess`) permission for the iTwin, or for the form's definition if form definition security is specified. (Having any other Forms permission automatically grants the **View** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-form-data-comments

The ID of the form data instance for which to get comments

Sets the level of detail to return. For this endpoint, setting 'return=representation' will add the comment authors' email addresses to the response.

Prefer

minimal

representation

---

Gets the specified form exported to the specified file format. Currently, the default--and only supported format--is PDF. The form with the specified ID will be laid out in the PDF according to its associated form definition.

The generated PDF will have a header at the top of each page with metadata about the form (such as its name and creation date) unless the 'includeHeader' query parameter is set to false.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

download-form-as-file

The type of file to download the form as. Currently the default, and only supported value, is 'PDF'.

fileType

If downloading as PDF, sets whether to include form metadata on the top of each page. Default is true.

includeHeader

Indicates that the file was successfully generated in the requested format. The response body consists of the generated file.

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

This response indicates that there is a problem with the format of the URL. Most likely problem: The 'fileType' parameter is set to an unsupported file type, or the 'includeHeader' parameter is set to a non-boolean value.

---

Requests that anywhere from 1 to 5 forms be exported to a file and saved in cloud-based storage for this iTwin (accessible through the Storage API). Currently 'pdf' is the only supported file type. The IDs of the forms must be specified in a query string parameter named "ids", separated by commas if there is more than one. A sample request URL that exports 3 forms to a PDF is as follows--

https://api.bentley.com/forms/exportPdfToStorage?fileType=pdf&ids=abab23524535,89458jjlij,32636wtewtwt&folderId=090909877987&includeHeader=true

Note that unlike most GET requests, this is not an idempotent operation; each time it is called, a new file will be generated. The response will not contain the file itself, but links to download it from Storage.

All forms specified in the request must come from the same iTwin, or the request will fail. The client may also specify the ID of a destination folder where the file should be saved; otherwise, it will be saved in the iTwin's root folder.  They can also specify whether to include a textual header with form metadata at the top of each page (default) or exclude it.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

export-form-to-storage

Instance IDs of forms to export. Must include at least 1, but no more than 5, IDs, separated by commas, and they all must come from the same project.

If exporting to PDF, indicates whether to include metadata on top of each page.  Default is true.

Indicates the type of file to create. Right now PDF is the only valid option, and is the default if not specified.

The ID, as retrieved from the Storage API, of the folder where the produced file should be saved. If not set, will default to the project's root folder.

folderId

Indicates that the file was generated successfully. The response includes the generated file's filename as well as links for using the Storage API to retrieve it.

Either one of the forms specified does not exist (code = 'FormDataNotFound') or the destination folder does not exist (code = 'FolderNotFound').

This response indicates that there is a problem with the request parameters. Depending on the problem, the 'details' array may include specific errors.

---

Creates a new form data instance. The user must specify the ID of a form definition to associate the instance with; that will set the instance's form type as well as determine how clients such as the CONNECT Forms web app will display it. The form definition ID should be obtained by calling the 'Get iTwin form definitions' endpoint.

### Permissions

To use this endpoint, the user is required to have the Forms **Create** (`Forms_CreateAccess`) permission for the project, or for the form's definition if form definition security is specified.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

create-form-data

Design Meeting 2021-02-07

LinkedElement

LinkedFile

NoLink

Indicates that the form data instance was successfully created. The response body contains the form data after creation, including its id.

This response indicates that the specified form definition does not exist (or is inaccessible due to insufficient permissions).

This response indicates that there is a problem with the format of the request body. Most likely causes: The 'formId' property is missing, an unrecognized standard or custom property was added, a standard property was set in the 'properties' object instead of the top-level object, the body is invalid JSON, or a property was set to a value of the wrong type.

---

Deletes the form data instance with the specified ID.

### Permissions

To use this endpoint, the user is required to have the Forms **Delete** (`Forms_DeleteForms`) permission for the iTwin.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

delete-form-data

The ID of the form data instance to delete.

Indicates that the form data instance was successfully deleted. There is no response body in this case.

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

---

Retrieves all properties of the specified form data instance.

Known, common properties will be returned directly on the 'formData' object, whereas custom properties unique to the form's type will be returned on the 'properties' sub-object.

Note that many properties in the schema are described as 'Origin info.' This means that they are metadata about where the form data came from and what business domain object(s) it is related to, such as a PDF file or a 3D model. Their meanings can differ from application to application. Many applications will use only a subset of these properties, and in general applications SHOULD NOT use or set these values unless they have a good reason to do so. Other properties, not marked 'Origin info', are defined for all form types, but clients SHOULD NOT assume that all of them are set.

### Permissions

To use this endpoint, the user is required to have the Forms **View** (`Forms_ViewAccess`) permission for the iTwin, or for the form's definition if form definition security is specified. (Having any other Forms permission automatically grants the **View** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-form-data-details

The ID of the form data instance to retrieve.

This response indicates that the specified instance does not exist, or the user doesn't have permission to view it.

---

Retrieves a list of form data instances for the iTwin with the given ID. If the Prefer header is omitted, or set to "return=minimal", this only returns basic info about each form--its ID, display name, type, and whether it is in an Open, Closed, or Draft state. Setting the Prefer header to "return=representation" will return more data. Use the "Get Form Data Details" endpoint to see full information about a particular form.

Note that the 'iTwinId' query string parameter is required. It must be a valid iTwin or project GUID to get forms from. Old clients can continue to use the 'projectId' parameter as an alias for 'iTwinId'.

### Permissions

To use this endpoint, the user is required to have the Forms **View** permission (`Forms_ViewAccess`) for the iTwin, or for some forms' definitions if form definition security is specified. (Having any other ProjectWise Forms permission automatically grants the **View** permission as well. If a user does not have permission to view a particular form, it will be silently excluded from the list.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-project-form-data

The GUID of the iTwin or project to get forms for. (Note: projectId is also accepted as an alias for this parameter.)

The number of form data instances to get in each page. Max 50, which is also the default if this parameter is not included.

$top

Parameter that enables continuing to the next page of the previous paged query. This must be passed exactly as it is in the response body's _links.next property. If this is specified and $top is omitted, the next page will be the same size as the previous page.

continuationToken

The type of form data to get. Omit to get all types.

type

Set this to only get form data for a particular workflow state (Open, Draft, or Closed).

state

Gets whether to return only a summary of each item (return=minimal) or full properties of each item (return=representation).  Default is return=minimal

This response indicates that the form data instance 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 forms.)

This response indicates that there is a problem with the format of the URL. Most likely problem: The 'projectId' parameter is missing or not a valid GUID.

---

Modifies the provided properties of the specified form to match the values provided in the request.

Setting a property value to null in the request will set the corresponding property value to null on the form. However, omitting a property from the request body entirely will leave that property's current value on the form unchanged.  Also, setting an object (other than "properties") to null will have the same effect as setting each individual property in that object to null.

### Permissions

To use this endpoint, the user is required to have different Forms permission levels (for the iTwin, or for the form's definition if form definition security is specified) based on the changes being made:

- Change to the `status` property: **Approve** (`Forms_ApproveAccess`) permission
- Change to the `assignee` or `assignees` property: **Assign** (`Forms_AssignAccess`) or **Approve** permission
- Changes to other properties: **Create/Modify** (`Forms_CreateAccess`) permission

**Full Access** (`Forms_FullAccess`) will satisfy all of these requirements.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

update-form-data

The ID of the form data instance to update.

Meeting minutes, now includes questions asked after the presentations

Design Meeting 2021-02-07 - Amended

Indicates that the changes were successfully made. The response body contains the form's data after modification, including both changed and unchanged properties. Note: If a workflow transition occurred, some properties may have been automatically changed in addition to the properties the client specified to change in the request.

This response indicates that the form the user attempted to update does not exist (or is inaccessible due to insufficient permissions).

This response indicates that there is a problem with the format of the request body. Most likely causes: An unrecognized standard or custom property was added, a standard property was set in the 'properties' object instead of the top-level object, the body is invalid JSON, or a property was set to a value of the wrong type.

---

Gets the full form definition with the specified ID.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-form-definition-by-id

This response indicates that the form definition with the specified ID does not exist or is inaccessible to the user.

---

Retrieves a list of Approved form definitions for the iTwin with the given ID.  This only returns the definition's name, type, and ID. The full definitions will be returned in the 'Get form definition by ID' endpoint.

Note that in order to create a form data instance, it must be associated with the ID of one of these form definitions (through the 'formId' property in the 'Create form data' request body). This API cannot be used to create or edit form definitions. They can only be created/edited/imported by iTwin administrators through the Bentley Form Manager webapp, which is accessible at https://connect-formmanager.bentley.com/designer/#/your-itwin-id (replace `your-itwin-id` with your actual project or iTwin ID).

Note that the 'iTwinId' query string parameter is required. It must be a valid iTwin or project GUID to get form definitions from.  Existing clients can continue to use the 'projectId' parameter as an alias for 'iTwinId'.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-project-form-definitions

The GUID of the iTwin or project to get form definitions for. (Note: projectId is also accepted as an alias for this parameter.)

The form type to get form definitions for.  Omit to get all form definitions in the project.

This response indicates that the project 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.)

---

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 &lt;select&gt; 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

Samples