Managing an Ad Hoc Group

Ad hoc groups are useful for when you would like to send documents for signing where you want a specific group of recipients, and any member of that group can sign the document with their own signature for a single transaction only.

To enable Ad Hoc Groups, please contact our support team.

Adding an Ad Hoc Group

Ad Hoc Groups and members can be updated via the following POST calls:

• api/packages (part of the transaction creation call)

• api/packages/{packageId}/roles: Since this call allows creating a single recipient at a time, you will need to add the individual members as signers first and then add the ad hoc group with the member associations.

• api/packages/{packageId}/groups: This is a new call that allows adding an ad hoc group and its members in a single call.  To note that as part of the Beta, this call has no rollback functionality.

Although signerType is an optional property for all existing signers, it must be specified for the new Ad Hoc Group signer type. See Role Types and Signer Types for the full list of supported Role Types and Signer Types in the system.

Updating an Ad Hoc Group

Ad Hoc Groups and members can be updated via the following PUT calls:

• api/packages/{packageId}/roleId: Since this call allows updating a single recipient at a time, you will need to update the members and ad hoc group individually.

• api/packages/{packageId}/groups: This is a new call that allows updating an ad hoc group and its members in a single call.  

It will not be possible to update the ad hoc group or ad hoc group member information when an accepted signature exists for them.  An error will be thrown.

To note that when performing a PUT on the Role or on the Groups call, that a pre-processing logic is in place to prevent partial data from being created.  The following items are validated:

• The Ad Hoc Groups feature is enabled for the account

• The transaction/template is not a hosted type (in person, iPen, RON, Virtual Room)

• The Ad Hoc Group name is specified and is unique

• The number of allowed members (10) is not exceeded

Notes:

• A new signer type called AD_HOC_GROUP_SIGNER has been introduced.  This signer type will be used to identify the Ad Hoc Group recipient.

• A new group member type called AD_HOC_GROUP_MEMBER has been introduced. This member type will be used to identify a recipient that is only a member of an Ad Hoc Group and not individual signer in the transaction/template.

• A new group member type called SIGNER has been introduced. This member type will be used to identify a recipient that is both a member of an Ad Hoc Group and an individual signer in the transaction/template. This is supported only via the API for the Beta release.

• Once the Ad Hoc Group and its members are added as individual roles, you can then make the association between them via the Ad Hoc Group signer model using their IDs.

• Only a single member type can be defined for a given recipient. If you define different member types for a given recipient (e.g. member type "SIGNER" in Ad Hoc Group1 and member type "AD_HOC_GROUP_MEMBER" in Ad Hoc Group2, an error will be thrown.

Although signerType is an optional property for all existing signers, it must be specified for the new Ad Hoc Group signer type. See Role Types and Signer Types for the full list of supported Role Types and Signer Types in the system.

REST API

HTTP Request

POST /api/packages

HTTP Headers

Authorization: Basic api_key
Accept: application/json
Content-Type: application/json

Request Payload

 "roles": [
        {
            "type": "SIGNER", 
            "id": "member-role-1",
            "signers": [
                {
                    "email": "johndoe@gmail.com",
                    "firstName": "John",
                    "lastName": "Doe",
                    "title":"",
                    "company":""
                }
            ]
        },
        {
            "type": "SIGNER",
            "id": "member-role-2",
            "signers": [
                {
                    "email": "janedoe@gmail.com",
                    "firstName": "Jane",
                    "lastName": "Doe",
                    "title":"",
                    "company":"" 
                }
            ]
        },
        {
            "type": "SIGNER",
            "id": "member-signer-role-3",
            "signers": [
                {
                    "email": "jessycollins@gmail.com",
                    "firstName": "Jessy",
                    "lastName": "Collins",
                    "title":"",
                    "company":"" 
                }
            ]
        },          {
            "type": "SIGNER",   
            "id": "group-role-1",
            "signers": [
                {
                    "firstName": "Borrowers",
                    "signerType": "AD_HOC_GROUP_SIGNER",
                    "group": {
                        "members": [
                            {
                                "userId": "member-role-1",
								"memberType": "AD_HOC_GROUP_MEMBER"
                            },
                            {
                                "userId": "member-role-2",
								"memberType": "AD_HOC_GROUP_MEMBER"
                            },
                            {
                                "userId": "member-signer-role-3",
								"memberType": "SIGNER"
                            }                         
                        ]
                    }
                }
            ]
        }
    ]

Response Payload

{

"id": "9sKhW-h-qS9m6Ho3zRv3n2a-rkI="

}

HTTP Request

POST /api/packages/{packageId}/groups

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Request Payload

 [
    {
        "type": "SIGNER",
        "id": "member-role-1",
        "signers": [
            {
                "firstName": "John",
                "lastName": "Doe",
			    "email": "johndoe@gmail.com",
                "company": "",
                "title": ""
            }
        ]        
    },
    {
         "type": "SIGNER",  
         "id": "member-role-2",
         "signers": [
            {
                "firstName": "Jane",
                "lastName": "Doe",
                "email": "janedoe@gmail.com",
                "company": "",
                "title": ""
            }
        ]
    },
    {
        "type": "SIGNER",
        "id": "group-role-1",
        "name": "Borrowers Role",
        "signers": [
            {
                "firstName": "Borrowers",
                "signerType": "AD_HOC_GROUP_SIGNER",
                "group": {
                    "members": [
                        {
                            "userId": "member-role-1",
                            "memberType": "AD_HOC_GROUP_MEMBER"
                        },
                        {
                            "userId": "member-role-2",
                            "memberType": "AD_HOC_GROUP_MEMBER"
                        }
                    ]
                }
            }
        ]
    }
]

Response Payload

 {

}

Appendix

Role and Signer Types

The following table depicts existing and new recipient types with their associated role and signer types. New items are marked in bold.