---
title: "Adding Input Validations to an API Module"
slug: "adding-input-validations-to-an-api-module"
tags: ["module-builder", "security", "api", "guides"]
updated: 2026-09-15T15:18:22Z
published: 2026-09-15T15:18:22Z
canonical: "docs.unqork.io/adding-input-validations-to-an-api-module"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unqork.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Adding Input Validations to an API Module

While front-end validation improves the user experience by providing instant feedback, it shouldn't be relied upon as the sole line of defense for data quality or protection. Browser-side UI can be bypassed, manipulated, or simulated using API tools. Adding input validation to your API modules ensures that the backend only processes safe, well-formed, and expected data. This protects the quality and stability of your application.

This article covers example strategies for implementing server-side input validation in Unqork API modules.

> [!NOTE]
> Module configuration falls under Application Security in the shared security responsibility model. You are responsible for designing and building your applications securely. Consult your internal security experts to determine the appropriate validation approach for your use case. Learn more about input validation at the [OWASP Input Validation Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html).

## Recommendations

Always validate inputs in your server-side module. You cannot rely on the UI to pass valid inputs because the request can be modified between the client and server. Validate any inputs received from the client before using them. This is especially important when the module has **Act as super-user when server-side executing** enabled.

Server-side input validation works together with error handling. Consider how you will generate error messages and return them to the caller when an invalid input is received.

In the examples in this article, the module defaults to an error state at the beginning of execution. Any failure to validate an input results in the module returning an error.

## Considerations

The right validation approach depends on your application's requirements. Use the following questions to help guide your decisions.

**Who are the end-users of your application?**

- Is the module restricted to internal end-users only, or is it open to the public?

**How is each field used in the module?**

- A field intended to store a number might receive a string without visible issues if the value is only displayed. The unexpected type will cause failures if the value is used in downstream calculations.

**How sensitive is the data?**

- Unqork IDs and personally identifiable information (PII) require stricter validation than less sensitive fields.

**How is the data used and where does it go?**

- Does the field fire an action? An invalid value might fire the wrong action.
- Does the data reach downstream reporting systems where data cleanliness matters?

**Do you have a downstream system with its own validation requirements?**

- If a downstream system requires a minimum character length on a field, add the same check in your module to surface issues earlier.

**What is the risk if the field receives an invalid value?**

- The higher the risk, the more validation to apply. If an invalid ID can unintended actions, add extra controls for that field.

The right approach depends on your application's use cases and requirements. Use these questions as a starting point, not a checklist.

## Strategies

The following sections describe four example strategies for adding input validation to a server-side execute module.

### Data Type Validation

Check that inputs match the expected data type. For example, confirm that a field is a number instead of a string, or that its length falls in an expected range. This approach can protect both data quality and system security.

For example, a module that receives a `withdrawAmount` input could use `=LODASH('isNumber',A)` to confirm the value is numeric before passing it to downstream processing.

### REGEX Validation

Use a regular expression to check an input against a specific pattern. Many tools are available for building and testing regular expressions, like [regex101.com](https://regex101.com/).

For example, if a module accepts a `submissionId` input, you can validate that the value matches the expected Unqork ID format. Unqork IDs are 24-character hexadecimal values. The pattern for this format is:

```plaintext
^[0-9a-f]{24}$
```

This same pattern applies to other Unqork-specific IDs, like module IDs or workflow IDs.

### Allowlist Validation

Check inputs against a defined list of acceptable values (sometimes called an allowlist, static list, or ENUM). This follows the principle of least privilege: a value is rejected unless it is explicitly permitted.

For example, store the allowlist in a Data Collection and query it at runtime to check whether the input matches an allowed value. This is similar to a drop-down component in a UI module, which restricts values to a preset list of options.

### Custom Business Rules

Validate inputs against rules specific to your business logic.

For example, if a record with a `status` of `closed` must also have a `dateClosed` value populated, consider adding this check in your API module. Even if the UI enforces this rule, validating it server-side can protect against cases where the API is called directly, bypassing the UI entirely.

## Example Configuration

The following examples demonstrate each strategy using POC modules. Select each module link to open the configuration in the Unqork training environment.

### Data Type Validation

**Module**: [Input Validation for Numeric Data Type](https://training.unqork.io/app/designer#/display/module-builder?moduleId=6a7b5d0ae407be3e1cbc1257)

This example validates that a `withdrawAmount` input is a number greater than zero. Downstream logic only proceeds if the input is valid.

1. The **Initializer** component sets a default `sse['httpResponseCode']` of `500` and triggers the **dwfCheckIsValid** Data Workflow component.
2. The **dwfCheckIsValid** Data Workflow component runs two formulas against the `withdrawAmount` input:

The output is written to `withdrawAmountValidType` as `true` or `false`. On completion, it triggers the **ruleCheckInputValid** Decisions component.
  - `=IF(LODASH('isNumber',A),TRUE,FALSE)`, which checks that the value is numeric
  - `=IF(AND(A=TRUE,_arg>0),TRUE,FALSE)`, which checks that the value is greater than zero
3. The **ruleCheckInputValid** Decisions component reads `withdrawAmountValidType` and sets the response:
  - `false` → `sse['httpResponseCode']` = `400`, response body: `"withdrawAmount is required to be a numeric data type."`
  - `true` → `sse['httpResponseCode']` = `200`

### REGEX Validation

**Module**: [Input Validation Using REGEX](https://training.unqork.io/app/designer#/display/module-builder?moduleId=6a7b5df44db44012156d1186)

This example validates that a `moduleId` input matches the expected Unqork ID syntax before the module runs further logic.

1. The **Initializer** component sets a default `sse['httpResponseCode']` of `500` and triggers the **calcIfInputIsValid** Calculator component.
2. The **calcIfInputIsValid** Calculator component runs the formula `=IFREGEXMATCH(A, "^[0-9a-f]{24}$","yes","no")` against the `moduleId` input and writes the result to `moduleIdValid`.
3. A Decisions component evaluates the result and responds as follows:
  - `moduleIdValid` = `no` → `sse['httpResponseCode']` = `400`, response body: `"Invalid moduleId provided."`
  - `moduleIdValid` = `yes` → triggers a Plug-In component to execute the provided `moduleId`

### Allowlist Validation

**Module**: [Input Validation Using an Allowlist](https://training.unqork.io/app/designer#/display/module-builder?moduleId=6a7b5daf53c0639a4d745326)

This example checks that a `moduleId` input appears in a pre-approved list stored in a Data Collection.

1. The **Initializer** component sets a default `sse['httpResponseCode']` of `500` and triggers the **plugGetValidModuleIdList** Plug-In component.
2. The **plugGetValidModuleIdList** Plug-In component returns the list of valid module IDs. A Data Workflow component filters the list against the provided `moduleId` and outputs `yes` or `no` to `moduleIdValid`.
3. A Decisions component evaluates `moduleIdValid`:
  - `no` → `sse['httpResponseCode']` = `400`, response body: `"Invalid moduleId provided."`
  - `yes` → triggers a Plug-In component to execute the provided `moduleId`

### Custom Business Rules

**Module**: [Input Validation Using Custom Business Rules](https://training.unqork.io/app/designer#/display/module-builder?moduleId=6a7b5e314db44012156d11fe)

This example validates a `status` field against an allowlist and enforces a conditional requirement: when `status = 'closed'`, the `dateClosed` field must be populated. Valid status values are `new`, `inProgress`, and `closed`.

1. The **Initializer** component defaults `sse['httpResponseCode']` to `500` and triggers the **plugGetAllowList** Plug-In component to retrieve valid status values from a Data Collection.
2. Once **plugGetAllowList** resolves, a Data Workflow component (**dwfValidateInputs**) performs the following:
  - Checks that the provided `status` value is in the allowlist
  - When `status = 'closed'`, checks that `dateClosed` is populated
  - Based on the result, triggers either the **ruleHTTPResponses** Decisions component (sets `sse['httpResponseCode']` to `400` and returns `"request failed"`) or the **plugCreateSubmission** Plug-In component

---

**Changelog**

| Date | Change |
| --- | --- |
| 2026-08-11 | Initial publication (EN-8012). Documents four server-side input validation strategies with example configurations. |

The UI (user interface) is a device's end-user interaction and communication point. It can include display screens, keyboards, and mouse. It is also how a user interacts with your application.

APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services.

In Unqork an application is a program used to perform specific tasks. An application can be one of two types: workflow or module.

End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product.

A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.

Personal Identifiable Information (PII) is any representation of information that permits the identity of an individual to whom the information applies to be reasonably inferred by either direct or indirect means.

To execute or perform a a task. In the Operations builder, Events fire (execute) one, or multiple Operations.

Data types are a classification of data that determines how it is stored and interpreted.

A Data Collection is any static data referenced by your application.

A query lets you retrieve, access, manipulate, and delete data in a database.