Create a Form
Endpoint
POST /api/forms/create
Description
This endpoint validates and creates a form based on the provided layout and field data. It checks for mandatory fields, user permissions and form structure before inserting the form into the system.
Body Parameters
| Name | Type | Required | Description |
|---|---|---|---|
location | Int32 | ✅ | ID of the location where the form is to be created. |
formLayout | String | ✅ | Identifier for the form layout. |
creator | String | ❌ | Username of the form creator. Defaults to empty string. |
isDraft | Boolean | ❌ | Indicates if the form is a draft. Defaults to false. |
enforceMandatory | Boolean | ❌ | Enforces mandatory field validation. Defaults to false. |
Error Handling
| Status Code | Message |
|---|---|
| 400 | "No parent (f_node) was specified." |
| 400 | "No form layout specified." |
| 400 | "No form metadata values provided." |
| 400 | "No such parent item exists." |
| 400 | "Parent item has been deleted." |
| 400 | "No such user exists." |
| 400 | "The specified creator account has been deleted." |
| 400 | "The specified creator does not have write permission to the parent item." |
| 400 | "The specified form layout does not exist." |
| 400 | "No values for the mandatory fields: FirstName, LastName" |
| 400 | "No Data" |
Notes
- Ensure the user has the correct permissions to create forms at the specified location.
- If 'enforceMandatory' is true, all mandatory fields must be provided.
- The endpoint uses internal user credentials extracted from the request context
Sample Request
POST /api/forms/create?location=101
&formLayout=employeeForm
&creator=jdoe
&isDraft=false
&enforceMandatory=true
Content-Type: application/json
Authorization: Bearer <token>
[
{
"FieldName": "FirstName",
"Value": "John"
},
{
"FieldName": "LastName",
"Value": "Doe"
}
]
Sample Response (Success)
{
"inode" : 123456
}
Sample Response (Error)
{
"error": "No values for the mandatory fields:
FirstName, LastName"
}
Read a Form
Endpoint
GET /api/forms/formdetails/{formID}Description
This endpoint fetches detailed metadata about a specific form, including its parent item and associated workflow. This is useful for displaying form context and hierarchy in client applications.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
formID | Int32 | ✅ | Unique identifier of the form. |
Error Handling
| Status Code | Message |
|---|---|
| 400 | "No Data" |
Notes
- The endpoint uses internal user credentials to validate access.
- If the form ID is invalid or the user lacks access, the response will be a 400 error with "No Data".
- The SQL query joins the form with its parent and workflow to provide a complete context.
- The workflowTitle is localized using the default language setting.
Sample Request
GET /api/forms/formdetails/12345
Authorization: Bearer <token>
Sample Response (Success)
[
{
"accessLevel": 0,
"i_node": 124704,
"f_node": 124890,
"item": "Global - Projects",
"creator": "Screendragon Admin",
"wfStatus": "Project Live"
}
]Sample Response (Error)
{
"error": "No data"
}Search a Form for specific data
Endpoint
GET /api/forms/search/{formType}/{formField}/value/{value}Description
This endpoint searches for forms of a specific type where a given field contains a specified value. This is useful for locating forms based on user input or metadata values.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
formType | String | ✅ | The identifier(GUID or name) of the form type to search within. |
formField | String | ✅ | The name or GUID of the form field to search. |
value | String | ✅ | The value to search for in the specified field. |
Error Handling
| Status Code | Message |
|---|---|
| 400 | "No form type specified". |
| 400 | "No form field specified". |
| 400 | "No value specified". |
| 400 | "No data" |
Notes
- All parameters are required and passed via query string.
- If any parameter is missing or empty, a specific error message is returned.
- Internal errors are logged and return a generic "No data" message.
Sample Request
GET /api/forms/search/123/FirstName/value/25
Authorization: Bearer <token>
Sample Response (Success)
[12345, 12346, 12347]
Sample Response (Error)
{
"error": "No form type specified."
}Retrieve List of forms
Endpoint
GET /api/forms
Description
This endpoint retrieves a list of forms filtered by location, metadata, status, and other criteria. Supports pagination, sorting, and custom field inclusions. Ideal for building dashboards, search interfaces, and filtered views.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
f_node | Int32 | ❌ | ID of the location(folder/node) to search for forms |
start | Int32 | ❌ | Start index for pagination |
count | Int32 | ❌ | Number of forms to return. If 0, return all. |
includeAccessLevel | Boolean | ❌ | Includes the user's access level for each form. |
orderBy | String | ❌ | Field to sort by: "item", "createdTime", "startDate", "endDate". |
filterText | String | ❌ | Text to search for form names. |
filterBy | String | ❌ | Field to apply filterText to. Can be "name" or a field GUID. |
filterExact | Boolean | ❌ | If true, performs exact match on filterText. |
filterStatus | String | ❌ | Filter by form status (e.g. "draft", "submitted"). |
viewID | Int32 | ❌ | ID of a predefined view to determine which columns to return. |
customFields | String | ❌ | JSON-formatted list of additional custom fields to include. |
includeSubs | Boolean | ❌ | Includes forms from subfolders of f_node. |
metaFilters | String | ❌ | JSON-formatted metadata filters |
formTypes | String | ❌ | Comma-separated list of form type GUIDs to include. |
Error Handling
| Status Code | Message |
|---|---|
| 400 | "No data" |
Notes
- metaFilters and customFields must be in a valid JSON format.
- If count = 0, all matching forms are returned (no pagination).
- This endpoint is optimized for flexibility and can support complex filtering scenarios.
Sample Request
GET /api/forms?f_node=101
&start=0
&count=10
&orderBy=createdTime
&filterText=onboarding
&filterStatus=submitted
&includeSubs=true
&includeAccessLevel=true
Authorization: Bearer <token>
Sample Response (Success)
[
[
{
"accessLevel": 0,
"i_node": 124704,
"f_node": 124890,
"item": "Global - Projects",
"creator": "Screendragon Admin",
"wfStatus": "Project Live"
},
...
]Sample Response (Error)
{
"error": "No data"
}Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article