Field Rules

Overview

Field Rules allow you to conditionally enable a field or field group based on the value of another field.

For example, you can configure an initials field to only become available when a signer selects a specific checkbox.

When using the API, Field Rules are configured as part of the document when creating a document pack through the V1 API.

Field Rules are added to the relevant document using the field_enabled_conditions array.

{
  "documents": [
    {
      "data_fields": [],
      "field_enabled_conditions": []
    }
  ]
}

The fields referenced by the rule must be included in the document's data_fields array.

Enabling Field Rules

Field Rules may need to be enabled for your QuicklySign account before they can be used.

If Field Rules are not currently enabled on your account, please email [email protected] and include the email address associated with your QuicklySign account. Our team will assist with enabling the feature for your account.

Creating Field Rules through the API

Field Rules do not require a separate API endpoint or authentication method.

They should be included when creating the document pack using:

POST /v1/document_packs

The request uses the normal access_token authentication used for other V1 API requests.

You should not use endpoints such as:

/app/documents/{document_key}/field_rules/{rule_id}/add_update_delete

Endpoints beginning with /app/ are internal QuicklySign front-end endpoints. They rely on an authenticated QuicklySign user session and are not intended for use by external API integrations.

Basic Structure

A Field Rule is defined alongside the document's data_fields.

For example:

{
  "documents": [
    {
      "data_fields": [
        {
          "type": "check",
          "custom_id": "Chk1"
        },
        {
          "type": "initial",
          "custom_id": "Initial_1",
          "field_group_id": "Initial_1"
        }
      ],
      "field_enabled_conditions": [
        {
          "field_or_group": "Initial_1",
          "field_rule_type": "field_group_enabled",
          "infix_logic": "(Chk1==\"checked\")",
          "json_logic": {
            "and": [
              {
                "==": [
                  {
                    "var": "Chk1"
                  },
                  "checked"
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}

In this example:

• Chk1 is the field controlling the rule.
• Initial_1 is the field group affected by the rule.
• The initials field group becomes enabled when Chk1 has a value of checked.

Field Rule Properties

The following properties are used when defining a Field Rule.

field_or_group

The field_or_group value identifies the field or field group that the rule applies to.

For example:

{
  "field_or_group": "Initial_1"
}

Referencing Fields in a Rule

Fields used within a rule should have identifiers that can be referenced by the condition.

The custom_id property can be used to assign an identifier to a field.

For example:

{
  "type": "check",
  "custom_id": "Chk1"
}

The same identifier can then be referenced in the rule:

Chk1=="checked"

The equivalent JSON logic references the same field using var:

{
  "==": [
    {
      "var": "Chk1"
    },
    "checked"
  ]
}

Using clear and unique custom_id values makes it easier to identify which fields are being referenced by your Field Rules.

Example: Enable an Initials Field Using a Checkbox

The following example contains two fields:

• A checkbox with the custom_id of Chk1.
• An initials field belonging to the Initial_1 field group.

The initials field is only enabled when the checkbox is checked.

Data Fields

{
  "data_fields": [
    {
      "type": "check",
      "custom_id": "Chk1",
      "checkbox_group_id": "declaration_choice",
      "mutually_exclusive": true
    },
    {
      "type": "initial",
      "custom_id": "Initial_1",
      "field_group_id": "Initial_1"
    }
  ]
}

Field Rule

The rule is added to the same document using field_enabled_conditions.

{
  "field_enabled_conditions": [
    {
      "field_or_group": "Initial_1",
      "field_rule_type": "field_group_enabled",
      "infix_logic": "(Chk1==\"checked\")",
      "json_logic": {
        "and": [
          {
            "==": [
              {
                "var": "Chk1"
              },
              "checked"
            ]
          }
        ]
      }
    }
  ]
}

When Chk1 is checked, the Initial_1 field group becomes enabled.

Complete Example

The following example shows the data fields and Field Rule together within a document.

{
  "documents": [
    {
      "data_fields": [
        {
          "type": "check",
          "custom_id": "Chk1",
          "checkbox_group_id": "declaration_choice",
          "mutually_exclusive": true
        },
        {
          "type": "initial",
          "custom_id": "Initial_1",
          "field_group_id": "Initial_1"
        }
      ],
      "field_enabled_conditions": [
        {
          "field_or_group": "Initial_1",
          "field_rule_type": "field_group_enabled",
          "infix_logic": "(Chk1==\"checked\")",
          "json_logic": {
            "and": [
              {
                "==": [
                  {
                    "var": "Chk1"
                  },
                  "checked"
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}

In this example, the document contains a checkbox and an initials field.

The checkbox has the identifier:

Chk1

The initials field belongs to the field group:

Initial_1

The Field Rule checks whether Chk1 has been checked. When the condition is met, the Initial_1 field group becomes enabled.

Important Considerations

Field Rules are configured at document level.

When working with a document pack containing multiple documents, add the field_enabled_conditions array to the specific document containing the fields referenced by the rule.

For example:

{
  "documents": [
    {
      "data_fields": [],
      "field_enabled_conditions": []
    },
    {
      "data_fields": [],
      "field_enabled_conditions": []
    }
  ]
}

Each document can therefore define its own fields and Field Rules.

The fields referenced by a rule must exist on the relevant document and should use consistent identifiers.

Field Rules should be configured when creating the document pack rather than by calling internal /app/ endpoints after the document has been created.