Concepts

Form Groups and Instances

What it is

Three related ideas, often confused with each other:

  • A Form Group is a named collection of forms an administrator saves in the Quik! Forms Enterprise Manager. It is essentially a saved search ("Pershing IRA Opening Package," "Annuity Application Set"). Users can pull up the whole group at once instead of searching for each form individually.
  • A Form Group Instance is a separate set of data within a single generated package. Each instance has its own copies of the forms and its own prefill values. Use instances when one package needs to handle separate transactions or people (a household with three accounts, two beneficiaries with different paperwork, and so on).
  • A duplicate form is the same form added twice inside a single instance. Use this when one transaction needs two copies of the same form (multiple transfers into one new account, for example).

Why it matters

Most prefill scenarios involve one form (or several different forms) for one person or transaction. Form Groups make that case faster to manage. Instances solve the harder case: when a single generated package needs to keep multiple sets of people or transactions separate without their data bleeding together across forms.

Without instances, a household with three accounts opening at once would either need three separate API calls (slow, harder to manage signatures) or would collapse all three accounts onto the same fields (wrong data on wrong forms). Instances let you generate the entire household in a single call and keep each account's data on its own forms.

How it works

Form Groups (administration)

Administrators create Form Groups in the Quik! Forms Enterprise Manager. The workflow:

  1. Search for the forms to include (by company, form name, lit number, state, category, or Form ID).
  2. Select the forms with checkboxes.
  3. Either add them to an existing group or create a new group.
  4. Save.

You can only add subscribed forms to a group. Groups can be edited, renamed, or deleted from the Form Groups page. Once a group exists, every user in the account can pull it up by name.

Generating multiple forms at once (one instance, one set of people)

When you generate a package of forms in one API call, the default behavior is that any role prefix refers to the same person across every form. If you prefill 1own.FName with "Margaret," every form in the package will show Margaret as Owner 1.

If you add the same form twice in this package (a duplicate form), Quik! renames the fields on the duplicate so its data does not bleed into the original.

Position in package

Field name pattern

Example

First copy of a form

Normal field name

1own.FName

Second copy of the same form

Append -1

1own.FName-1

Third copy

Append -2

1own.FName-2

Fourth copy

Append -3

1own.FName-3

Generating multiple sets of forms at once (Form Group Instances)

When one package needs to cover several separate transactions or people, use Form Group Instances. Each instance is a separate set of forms with its own prefill data. Instances are separated by a dash in the QuikFormID value.

Example: a household opens three accounts at the same firm. The household needs three sets of forms in one package.

"QuikFormID": "6996,2,2-6996,12-2,12"

This generates three instances:

  • Instance 1: Form IDs 6996, 2, 2 (form 2 included twice)
  • Instance 2: Form IDs 6996, 12
  • Instance 3: Form IDs 2, 12

Inside each instance, Quik! renames the fields so the three instances do not collide.

Instance

Field name pattern

Example

First instance

Normal field name

1own.FName

Duplicate within first instance

Append -1, -2, etc.

1own.FName-1

Second instance

Append -1000, -1001, etc.

1own.FName-1000

Third instance

Append -2000, -2001, etc.

1own.FName-2000

Fourth instance

Append -3000, -3001, etc.

1own.FName-3000

Each new instance jumps the suffix by 1000. Duplicates within an instance increment by 1 from the instance's base number.

Quick reference: when to use which

Scenario

Use

One transaction, one or more different forms, one set of people

Default behavior. Just list the Form IDs.

One transaction needs two copies of the same form (e.g., two transfers)

Duplicate form. Add the same Form ID twice in the list.

Multiple transactions or households in one package, each with its own people

Form Group Instances. Separate instances with dashes in QuikFormID.

Recurring form selection that users pull up regularly

Form Group. Set up in the Forms Enterprise Manager.

For developers: where this shows up in the API

This section is for the technical reader implementing the integration.

  • QuikFormID property in the request body. Comma-separated Form IDs within an instance. Dash-separated between instances. Example: "QuikFormID": "6996,2,2-6996,12-2,12".
  • FormFields array with field instance suffixes. Use -1, -2 for duplicates within an instance. Use -1000, -2000, -3000 for subsequent instance groups.
  • /forms/fields endpoint returns the field names for a list of Form IDs but does not encode instance suffixes. Add the suffixes yourself based on your instance structure.
  • Recipients.Signers in the ESignType object: when using Form Group Instances with DocuSign, each instance signer needs its own entry with the matching Instance value (0 for the first group, 1000 for the second, and so on) and Role (e.g., 1own, 2own). If the same person is a signer across instances, set their Order to the same value across all their entries so they receive one consolidated signing event.

JSON example: household with two instances

Joint account in instance 1 (John = Owner 1, Sally = Owner 2). Joint account in instance 2 with the same people in swapped roles (Sally = Owner 1, John = Owner 2):

{
  "HostFormOnQuik": true,
  "QuikFormID": "12-12",
  "FormFields": [
    { "FieldName": "1own.FName", "FieldValue": "John" },
    { "FieldName": "2own.FName", "FieldValue": "Sally" },
    { "FieldName": "1own.H.Email", "FieldValue": "john@email.com" },
    { "FieldName": "2own.H.Email", "FieldValue": "sally@email.com" },
    { "FieldName": "1own.FName-1000", "FieldValue": "Sally" },
    { "FieldName": "2own.FName-1000", "FieldValue": "John" },
    { "FieldName": "1own.H.Email-1000", "FieldValue": "sally@email.com" },
    { "FieldName": "2own.H.Email-1000", "FieldValue": "john@email.com" }
  ]
}

Pitfalls

  • Form Groups and Form Group Instances are different things. A Form Group is an administrative grouping of forms (a saved search). A Form Group Instance is a runtime grouping of data within one generated package. They share the word "group" but solve different problems.
  • The first instance has no suffix. Field names for the first instance are written as normal (1own.FName). Only the second instance and beyond use suffixes (-1000, -2000, and so on). Adding a suffix to the first instance will not match any field on the form.
  • Duplicate suffixes (-1, -2) and instance suffixes (-1000, -2000) are not interchangeable. -1 means "second copy of the same form within this instance." -1000 means "first copy of the form in the second instance." If you mix them up, the wrong person's data lands on the wrong form.
  • When the same person signs across instances, configure DocuSign signers explicitly to avoid duplicate signing events. Without explicit signer configuration, DocuSign will treat the same person in different instances as separate signers and email them twice. The signer needs matching Name, Email, and Order values across instances to be treated as one event.
  • Only subscribed forms can be added to a Form Group. If a form is not in your library, an administrator must request library access before the form can be grouped.

Related articles

Continue with these articles to understand the related concepts and workflows:

Previous
Roles and Role Prefixes
Next
Sessions and UNIDs