Background

Customers often have a need to generate forms for households, such that when generating bundles of forms, certain family members’ information prefills one form, and not the other. Similarly, customers often have a need to generate multiple copies of the same form in a single bundle, and prefill different people's data onto the same “role” on each copy.

Form group instances make it easier to logically separate forms according to transactions (e.g. open 3 accounts), whereas form instances are really meant to add duplicate forms into a bundle (e.g. adding extra beneficiaries).

In order to add from group instances in the same generated bundle, there is a method called AddFormIDsGroup.

Method Name	Argument	Description

Method Name	Argument	Description
AddFormIDsGroup	forms	A string representing a CSV of formIDs. The order in which the group is added is the same in which will be displayed when generated.

Field Names with Form Group Instances

Using the example scenario above:

For the first group of forms, fields are built normally without the field instance extension. If, within the first group, FormIDs are duplicated (e.g. form group 1 has forms "1,2,2" where form ID 2 is repeated) then the field instance will be "-1".
- “1own.FName” for the first instance of FormID 1 in this first group of forms.
- “1own.FName-1” for the second instance of FormID 2 in this first group of forms.
For the second group of forms, fields will be built with a field instance extension. The extension number will start at 1000 (e.g. "1own.FName-1000") and grow as duplicate forms are included in the same package (e.g. the second copy of the same form could have a field named "1own.FName-1001").
- “1own.FName-1000” for the first instance
- “1own.FName-1001” for the second instance
Subsequent groups of forms will increase the instance number by 1000. For example, the third form group will have a field instance number starting with "2000" and increments by 1 for each copy of the same form within that group (e.g. if the group contains FormIDs "1,1,1,1" then the instance numbers would be "2000", "2001", "2002" and "2003"
- “1own.FName-2000”
- “1own.FName-2001”
- “1own.FName-2002”
- “1own.FName-2003”

These field name extensions result in unique field names on every form in a bundle, so that different people can be prefilled in desired sections of a form without their information "flowing" to the same section on other copies or forms.

Using Form Groups Instances in SOAP & REST

How To Specify FormIDs in Form Group Instances

When building Form Group instances with a JSON for REST or with an XML for SOAP web services, a dash ( - ) is used to separate form group instances.

Let's say you want to create a package of 3 separate groups of forms (e.g. a household with 3 accounts) using FormIDs 6996, 2 and 12. You want the paperwork for accounts A, B and C to be specified as follows:

account A gets form IDs 6996, 2, and a second copy of Form ID 2
account B gets Form IDs 6996 and 12
and account C gets Form IDs 2 and 12

Thus, you would set the QuikFormID property as follows:

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

See below for sample code:

JSON

{
  "HostFormOnQuik": true,
  "FormFields": [
    {
      "FieldName": "1own.FName",
      "FieldValue": "Stephen"
    },
    {
      "FieldName": "1own.FName-1",
      "FieldValue": "Draymond"
    },
    {
      "FieldName": "1own.FName-1000",
      "FieldValue": "Klay"
    },
    {
      "FieldName": "1own.FName-2000",
      "FieldValue": "Andre"
    }
  ],
  "QuikFormID": "6996,2,2-6996,12-2,12"
}

The above example will generate the following form group instances:

account A gets form IDs 6996, 2, and a second copy of Form ID 2
account B gets Form IDs 6996 and 12
and account C gets Form IDs 2 and 12

Quik! recommends that customers copy and paste the above JSON into the HTMLSettings parameter of the Execute endpoint on Swagger, then open the returned HTML link to see how the first name fields prefill on the forms to aid with understanding how to prefill form group instances. Note: Ensure your account is subscribed to the American Funds form library to test with these forms.

Docusign Configurations for Signers and ExtraRecipients

How to Configure Signers with Form Group Instances

In the following scenario, let’s say you have two form groups, both consisting of Form ID 12.

In the first Form Group, John is Owner 1 and Sally is Owner 2.
In the second Form Group, Sally is Owner 1 and John is Owner 2.

Since John and Sally are each assigned multiple roles within the form bundle, we want to ensure that they each receive only one signing event in Docusign. This can be accomplished by configuring the Signers tab within the Recipients section.

See below for sample code:

JSON

{
    "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", // Second Form Group
            "FieldValue": "Sally"
        },
        {
            "FieldName": "2own.FName-1000", // Second Form Group
            "FieldValue": "John"
        },
        {
            "FieldName": "1own.H.Email-1000", // Second Form Group
            "FieldValue": "sally@email.com"
        },
        {
            "FieldName": "2own.H.Email-1000", // Second Form Group
            "FieldValue": "john@email.com"
        }
    ],
    "ESignType": {
        "Type": "docusign",
        "AuthUserID": "<AuthUserID>",
        "SignCallBackURL": "<CallBackURL>",
        "SignEnvironmentID": 2, 
        "Recipients": {
            "Signers": [
                {
                    "Instance": 0,
                    "Order": 1,
                    "Role": "1own",
                    "SendType": "EmailToSign",
                    "AuthTypes": "SMS"
                },
                {
                    "Instance": 0,
                    "Order": 2,
                    "Role": "2own",
                    "SendType": "EmailToSign",
                    "AuthTypes": "SMS"
                },
                {
                    "Instance": 1000, // Second Form Group
                    "Order": 2, // Update to match the Order of this recipient on the other form(s)
                    "Role": "1own",
                    "SendType": "EmailToSign",
                    "AuthTypes": "SMS"
                },
                {
                    "Instance": 1000, // Second Form Group
                    "Order": 1, // Update to match the Order of this recipient on the other form(s)
                    "Role": "2own",
                    "SendType": "EmailToSign",
                    "AuthTypes": "SMS"
                }
            ]
        }
    }
}

The above code does the following:

Duplicate the Signers and update the following on the second group of Signers:
- Instance: Update to match the suffix used for the Form Group (“1000” in the example above)
- Order: Update to match the Order that is needed from the first Form Group in order to achieve one signing event per recipient

The result of this is that the E-Sign pop-up will prefill with the following:

Note: In order for the recipient to receive one signing event, their Name, Email, and Order must all match in the E-Sign pop-up.

How to Configure ExtraRecipients with Form Group Instances

When sending an envelope containing multiple Broker Dealer forms where each Broker Dealer should only receive their respective forms, you can configure ExtraRecipients. For instructions on how to configure this, visit this page: Configuring Document Visibility | Configuring Document Visibility with Form Group Instances

DEPRECATED - Using Form Groups Instances with the Quik! Forms Engine DLL

Example: There is a need to bundle the forms for 3 accounts together but with differing forms. Let's say account A gets form IDs 1,2,2, account B gets Form IDs 1,3 and account C gets Form IDs 2,3.

The example below will generate 3 group of forms.

C#

QuikFormsEngine qfe = new QuikFormsEngine();

qfe.QuikCustID = "1000123";
qfe.QuikUsername = "myUserName";
qfe.QuikPassword = "myPassword";

qfe.AddFormIDsGroup("1,2,2");
qfe.AddFormIDsGroup("1,3");
qfe.AddFormIDsGroup("2,3");
qfe.Execute();

Quik! API Guide

Configuring Form Group Instances

Background

Field Names with Form Group Instances

Using Form Groups Instances in SOAP & REST

How To Specify FormIDs in Form Group Instances

JSON

Docusign Configurations for Signers and ExtraRecipients

How to Configure Signers with Form Group Instances

JSON

How to Configure ExtraRecipients with Form Group Instances

DEPRECATED - Using Form Groups Instances with the Quik! Forms Engine DLL

C#

Related pages