Screendragon API Integration Use Cases - Forms

Modified on Fri, 21 Nov at 11:52 AM

Create a Form
Reade a specific Form
Search a Form for specific data
Retrieve List of forms

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"
}