--- title: "Forms" slug: "forms-3" updated: 2023-05-24T18:48:00Z published: 2023-05-24T18:48:00Z canonical: "docs.visualvault.com/forms-3" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.visualvault.com/llms.txt > Use this file to discover all available pages before exploring further. # Forms #### **GET **/Forms/{id}**** --- > **Returns a form instance by form ID.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form instance id. | ##### ****Query Parameters**** | Parameter | Type | Description | | --- | --- | --- | | acquirelock | String | ----- | | rollbacklock | String | ----- | | masterid | Guid | ----- | ##### ****Response Codes**** | Code | Description | | --- | --- | | 200 | OK | #### **POST **/Forms/{id}**** --- > **Updates a form instance.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form instance id. | ##### ****Query Parameters**** | Parameter | Type | Description | | --- | --- | --- | | pageId | Guid | ID of the page. | ##### ****Body Parameters**** | Parameter | Type | Description | | --- | --- | --- | | fields | {FormControlListExample} | List of form controls to update and their values. | ##### ****Response Codes**** | Code | Description | | --- | --- | | 200 | OK | | 400 | Bad Request | #### **POST **/Forms**** --- > **Creates a new form data instance.** ##### ****Body Parameters**** | Parameter | Type | Description | | --- | --- | --- | | masterId | string | The master ID. | | rrControlId | string | RRC ID. | | data | {FieldList} | The form control data. | | fillinMapping | {FillinMapping} | The fillin mapping data. | ##### ****Response Codes**** | Code | Description | | --- | --- | | 200 | OK | #### **POST **/Forms/{id}/NewInstance**** --- > **Creates a new form data instance.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form template id. | ##### ****Body Parameters**** | Parameter | Type | Description | | --- | --- | --- | | fields | {FormControlListExample} | List of form controls to update and their values. | ##### ****Response Codes**** | Code | Description | | --- | --- | | 201 | Created | #### **PUT **/Forms/{id}**** --- > **Saves an existing form instance.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form instance id. | ##### ****Body Parameters**** | Parameter | Type | Description | | --- | --- | --- | | masterId | String | The master form ID. | | rrControlId | String | RRC ID. | | dataId | String | The data ID. | | data | {FieldList} | The form data. | | fillinMapping | {FillinMapping} | The fillin mapping data. | ##### ****Response Codes**** | Code | Description | | --- | --- | | 200 | OK | #### **DELETE **/Forms/{id}**** --- > **Deletes a form instance.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form instance id. | ##### ****Query Parameters**** | Parameter | Type | Description | | --- | --- | --- | | masterid | Guid | ----- | | rrcontrolid | String | Repeating Row Control ID. | #### **PUT **/Forms/FillinRelateInfo**** --- > **Updates fill-in and relate information.** ##### ****Body Parameters**** | Parameter | Type | Description | | --- | --- | --- | | fillinRelateKey | String | Unique key. | | formValues | String | List of form values to fill-in. | | dhDocId* | Guid | Id of the related form. | | formId | Guid | The form ID if this call originates from an Upload Button form control. | #### **GET **/Forms/FillinRelateInfo**** --- > **Retrieves fill-in and relate information.** ##### ****Query Parameters**** | Parameter | Type | Description | | --- | --- | --- | | lookupKey | Guid | ----- | | lookupMappings | Guid | ----- | | referFieldId | Guid | ----- | #### **GET **/Forms/{id}/RepeatingRowControlData**** --- > **Retrieve data for a Repeating Row Control.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form instance id. | ##### ****Query Parameters**** | Parameter | Type | Description | | --- | --- | --- | | rrcId | Guid | Repeating Row Control ID. | | formTemplateId | Guid | Form template ID. | | masterTemplateId | Guid | Master template ID. Allows retrieval of specific RRC revisions. | | checkNeedsUpgrade | Bool | Do we need to upgrade the form template? | #### **POST **/Forms/RepeatingRowControlData**** --- > **Get all Repeating Row Control data.** ##### ****Body Parameters**** | Parameter | Type | Description | | --- | --- | --- | | formInstanceId | Guid | The form instance ID. | | rrcId | Guid | The repeating row control ID. | | formTemplateId | Guid | The form template ID. | | masterTemplateId | Guid | The master template ID. | | checkNeedsUpgrade | Bool | Check if the form template needs to upgrade. | #### **GET **/Forms/{id}/DocumentCount**** --- > **Returns the number of documents associated with the form instance.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form instance id. | ##### ****Query Parameters**** | Parameter | Type | Description | | --- | --- | --- | | formControlId | Guid | Id of the form control requesting the index fields if called from a form. | | folderPath | String | Folder path tied to the control. | | byFolder | Bool | Get upload counts by folder instead of overall? | #### **GET **/Forms/{id}/Documents**** --- > **Get the document count of a specific control or the form instance if no control provided.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form instance id. | ##### ****Query Parameters**** | Parameter | Type | Description | | --- | --- | --- | | folderId | Guid | ID of the folder to check. | | formControlId | Guid | Id of the form control requesting the index fields if called from a form. | | q | String | A VisualVault REST API Data Query. | #### **POST **/Forms/{id}/documents**** --- > **Relate a new form document.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form instance id. | ##### ****Body Parameters**** | Parameter | Type | Description | | --- | --- | --- | | documentName* | String | Name of the document. | | description* | String | Document description. | | fileName* | String | The name of the file. | | revision* | String | Document revision number. | | docState* | String | State of the document. - Unreleased (0) - Released (1) - Pending (2) | | fileData* | String | File data as a base64 string. | | folderId | Guid | The folder ID. | | formControlId | Guid | ID of the upload button. | | indexFields* | {IndexField} | Index field names and values as a JSON array or object string. | ##### ****Response Codes**** | Code | Description | | --- | --- | | 500 | Internal Server Error | #### **DELETE **/Forms/{id}/documents**** --- > **Remove a related form document if user is Owner.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form instance id. | ##### ****Query Parameters**** | Parameter | Type | Description | | --- | --- | --- | | deleteId* | Guid | ----- | | formDocId* | Guid | Name of the form to delete. | #### **GET **/Forms/Menu/{id}/MenuTabs**** --- > **Get the menu tabs of a form instance.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form instance id. | #### **GET **/Forms/Menu/{id}/ChangeLog**** --- > **Get the change log data for a form instance.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form instance id. | #### **GET **/Forms/Menu/{id}/Workflow**** --- > **Get the form workflow data of a form instance.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form instance id. | #### **GET **/Forms/Menu/{id}/Documents**** --- > **Get the documents associated with a form instance.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form instance id. | ##### ****Query Parameters**** | Parameter | Type | Description | | --- | --- | --- | | q | String | A VisualVault REST API Data Query. | #### **GET **/Forms/Menu/DocumentContextMenu**** --- > **Get the context menu properties for a form instance.** ##### ****Query Parameters**** | Parameter | Type | Description | | --- | --- | --- | | dhId | Guid | ID of the form. | | documentId | Guid | The document ID. | #### **GET **/SearchCriteria**** --- > **Retrive the form related data search criteria.** ##### ****Query Parameters**** | Parameter | Type | Description | | --- | --- | --- | | fieldList | String | List of form fields. | | relatedFormName | String | Name of the related form. | | listType | String | Type of dropdown list query. - UserQuery - GroupQuery - CustomQuery | | defaultValue | String | Default value. | | enumeratedItem | Bool | ----- | #### **GET **/Forms/Menu/{id}/Forms**** --- > **Get the related forms of a form instance.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form instance id. | ##### ****Query Parameters**** | Parameter | Type | Description | | --- | --- | --- | | q | String | A VisualVault REST API Data Query. | | formTemplateName | String | Name of the form template. | #### **GET **/Forms/Menu/{id}/Revisions**** --- > **Get the revision information for a form instance.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form instance id. | ##### ****Query Parameters**** | Parameter | Type | Description | | --- | --- | --- | | q | String | A VisualVault REST API Data Query. | #### **GET **/Forms/Menu/{id}/History**** --- > **Retrieve the history data of a form template.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form template id. | ##### ****Query Parameters**** | Parameter | Type | Description | | --- | --- | --- | | q | String | A VisualVault REST API Data Query. | #### **GET **/Forms/Menu/{id}/DashboardByFormId**** --- > **Get form data dashboard information by form ID.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form template id. | #### **GET **/Forms/Menu/{dashboardId}/DashboardById**** --- > **Get form data dashboard information by dashboard ID.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | dashboardId* | Guid | The dashboard id. | ##### ****Query Parameters**** | Parameter | Type | Description | | --- | --- | --- | | joinTable | String | Name of the table to join. | | joinLeftColumnId | Guid | Left column ID. | | joinOperator | String | Operator comparison type. - Equals - NotEqual | | joinRightColumnName | String | Right column name. | | joinType | String | Join type. - Inner - Full - Left - Right | | includeData | Bool | Include the query data? | | includeJoinTableList | Bool | Include the list of tables and views? | #### **GET **/Forms/Menu/Dashboards**** --- > **Get the names and IDs of all form dashboards.** No Parameters. #### **PUT **/Forms/Menu/{dashboardId}/DashboardById**** --- > **Get form data dashboard information by dashboard ID.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | dashboardId* | Guid | The dashboard id. | ##### ****Body Parameters**** | Parameter | Type | Description | | --- | --- | --- | | joinDefinitionList | String | List of join definitions. | | queryFields | String | A list of query fields. | | queryFilter | String | A query filter. | | orderBy | String | The column to order by. | | pageSize | Int | The number of results per page. | | startPage | Int | The page number to start from. | | endPage | Int | The page number to finish with. | #### **GET **/FormDashboard/{dashboardId}/QueryData**** --- > **Get the form dashboard query data.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | dashboardId* | Guid | The dashboard id. | ##### ****Query Parameters**** | Parameter | Type | Description | | --- | --- | --- | | fields | String | List of fields to include. | | q | String | A VisualVault REST API Data Query. | | orderby | String | Column to order by. | | pageSize* | String | Number of entries for each dashboard page. Default = 15. | | startPage* | String | Page to start the search. | | endPage* | String | Page to end the search. | #### **POST **/FormDashboard/QueryData**** --- > **Get all form dashboard query data.** ##### ****Body Parameters**** | Parameter | Type | Description | | --- | --- | --- | | controlId | Guid | The control ID. | | dashboardId | Guid | The form dashboard ID. | | fields | String | The field names to retrieve. | | q | String | The query. | | orderBy | String | Column to order by. | | pageSize | Int | Size of the page results. | | startPage | Int | Page to start. | | endPage | Int | Page to end. | #### **GET **/FormDashboard/{templateName}/fields**** --- > **Get the field information for a form dashboard.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | templateName* | string | The form template name. | #### **POST **/FormDashboard/{formTemplateId}/NewDashboard**** --- > **Create a new form data dashboard.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | formTemplateId* | Guid | The form template ID. | ##### ****Body Parameters**** | Parameter | Type | Description | | --- | --- | --- | | reportName* | String | Report name. | | reportOptions | {reportOptionWrapper} | Report options. | | columnList | Array | List of columns. | | criteriaList | Array | List of search criteria. | #### **PUT **/FormDashboard/{dashboardId}/UpdateDashboard**** --- > **Update a form data dashboard.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | dashboardId* | Guid | The dashboard id. | ##### ****Body Parameters**** | Parameter | Type | Description | | --- | --- | --- | | reportName | String | The name of the report. | | reportOptions | {reportOptionWrapper} | The options for the report. | | columnList | Array | The list of columns to update. | | criteriaList | Array | The search criteria. | #### **GET **/Forms/Menu/{mtiId}/CustomDocumentsList**** --- > **Returns a list of custom filtered documents.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | mtiId* | Guid | The menu tab item id. | ##### ****Query Parameters**** | Parameter | Type | Description | | --- | --- | --- | | q | String | A VisualVault REST API Data Query. | | sortField | String | Field name to sort by. | | sortDir | String | Sort direction. - asc: Ascending order - desc: Descending order | | pageSize* | String | Number of entries for each dashboard page. Default = 15. | | startPage* | String | Page to start the search. | | endPage* | String | Page to end the search. | #### **GET **/Forms/Menu/{queryId}/QueryReportGrid**** --- > **Get report data by ID.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | queryId* | Guid | The query id. | ##### ****Query Parameters**** | Parameter | Type | Description | | --- | --- | --- | | q | String | A VisualVault REST API Data Query. | #### **GET **/FormEntity/{id}**** --- > **Get form entity by ID.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form id. | #### **GET **/FormEntity/{id}/page/{pageId}/fieldlist**** --- > **Get the form entity properties for a provided page.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form id. | | pageId* | Guid | The page id. | ##### ****Query Parameters**** | Parameter | Type | Description | | --- | --- | --- | | getlatest | Bool | Get data from the latest form revision? | #### **GET **/FormEntity/{id}/basefieldlist**** --- > **Returns the base form field list.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form id. | #### **GET **/FormEntity/{id}/page/{pageId}/fieldlistproperties**** --- > **Get the field list properties of a page.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form id. | | pageId* | Guid | The page id. | #### **GET **/FormEntity/{id}/getSignatureStamp/{fieldId}**** --- > **Returns a user signature from a signing canvas.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form id. | | fieldId* | Guid | The signature canvas id. | #### **PUT **/FormEntity/{id}/signSignatureStamp**** --- > **Signs a signature canvas.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form id. | ##### ****Body Parameters**** | Parameter | Type | Description | | --- | --- | --- | | dhDocId | String | The form ID. | | fieldId | String | The ID of the signature stamp. | | isChecked | Bool | The checked status of the stamp. | | signatureImageData | String | The image data of the signature. | | userpw | String | The user password if required. | #### **PUT **/FormEntity/{id}/evaluateGroupsAndConditions**** --- > **Triggers an evaluation of groups and conditions for a form instance.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form id. | ##### ****Body Parameters**** | Parameter | Type | Description | | --- | --- | --- | | fields | Object | The fields to evaluate. | | wizardStep | Object | Wizard Step information. | | requestId | String | The ID of the request. | | useLatestTemplate | Bool | Use the latest revision of the form template? | #### **PUT **/FormEntity/{id}/setFieldImage**** --- > **Set the image of a form field.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | id* | Guid | The form id. | ##### ****Body Parameters**** | Parameter | Type | Description | | --- | --- | --- | | fieldId | String | The ID of the field to set. | | imageID | String | The ID of the image to apply. | #### **GET **/Comments/{conversationId}/Form**** --- > **Get the comments of a Conversation control.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | conversationId* | Guid | The conversation form control id. | #### **PUT **/Comments/{conversationId}/Form**** --- > **Add a comment to an existing Conversation control.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | conversationId* | Guid | The conversation form control id. | ##### ****Body Parameters**** | Parameter | Type | Description | | --- | --- | --- | | commentSubject | String | The text to appear as the comment subject. | | commentBody | String | The text to appear inside the comment body. | #### **DELETE **/Comments/{parentId}/Form/{commentDetailID}**** --- > **Delete a comment from a Conversation control.** ##### ****Route Parameters**** | Parameter | Type | Description | | --- | --- | --- | | parentId* | Guid | The conversation form control id. | | commentDetailID* | Guid | The comment id. |