To download the full code sample see our Code Share site.

Sometimes it's convenient to share requests for signatures among the members of a group. For example, it might be convenient to treat the pharmacists in a particular pharmacy as a group, so that any available member of the group can sign the paperwork for a patient's prescriptions.

In OneSpan Sign, a Signer Group is a set of OneSpan Sign users who can act as a single signer from the point of view of the package creator. Users who can become group members must already be members of the associated OneSpan Sign account.

OneSpan Sign group members receive an email invitation to sign a related document package. Among those members, signing is on a first-come, first-serve basis. When one member is signing, all other members are locked out.

Any member who signs does so on behalf of the group, but their name will be stamped on the documents they sign. Anyone verifying the document through the Audit Trail will see the individual member's signature information and identity.

All group members can monitor the progress of the group's transactions, which helps ensure that those transactions are completed on time.

Finding Your Groups in the UI

First, locate your Groups in the OneSpan Sign Web UI. To do this, log into your OneSpan Sign account and click Admin > Groups. After running your code, all your groups will appear here. If you do not see the Groups option in the toolbar, it could be because they have not been enabled on your account. To enable them, please contact our Support Team.

For more information, see Administering Groups.

Creating Groups

The sample code below will create a group called Java Developers, with two members. It is important to note that these members have to be Senders in your account. The withIndividualMemberEmailing() method will send emails to the members of the group instead of the specified group email. If you wish to send emails to the group email instead, use withoutIndividualEmailing().

Group group1 = GroupBuilder.newGroup( "Java Developers" )
            .withEmail( "[email protected]" )
            .withIndividualMemberEmailing()
            .withMember( GroupMemberBuilder.newGroupMember( "[email protected]" )
                .as( GroupMemberType.REGULAR ) )
            .withMember( GroupMemberBuilder.newGroupMember( "[email protected]" )
                    .as( GroupMemberType.REGULAR ) )
                .build();

Once you have done this, you can call on your OneSpan Sign GroupService to create your group.

Group createdGroup1 = eslClient.getGroupService().createGroup( group1 );

You can also create an empty group, and invite members to join your group at a later date.

esl.getGroupService().inviteMember( createdEmptyGroup.getId(),
            GroupMemberBuilder.newGroupMember( "[email protected]" )
                .as( GroupMemberType.REGULAR )
                .build() );

Retrieving Groups

Retrieving your groups can come in handy when you wish to invite members to your group. It is important to note that the group id is required when sending invitations. The first line in the sample code below will retrieve your groups as a list. Then, for each group object in the list, the group name, email, and id are retrieved. With your group ids, you can retrieve each member, along with their email, first name, and last name.

List<Group> allGroups = esl.getGroupService().getMyGroups();
for ( Group group : allGroups ) {
     System.out.println( group.getName() + " with email " + group.getEmail() + " and id " + group.getId() );
     List<GroupMember> allMembers = esl.getGroupService().getGroupMembers( group.getId() );
     for ( GroupMember member : allMembers ) {
          System.out.println( member.getGroupMemberType().toString() + " " + member.getFirstName() + " " + member.getLastName() + " with email " + member.getEmail());
     }
}

Adding a Group Signer

Once your group has been created, you can now then add a group signer to your package. The code below shows you how to edit the signer block in order to add a group signer.

If you need a comparison to a basic document object creation, or if this is the first time creating a package with the Java SDK, see this topic.

DocumentPackage myPackage = newPackageNamed( "My Package with Group Signers Java Developers" )
                .withSigner( SignerBuilder.newSignerFromGroup( myGroup.getId() )
                    .canChangeSigner()
                    .deliverSignedDocumentsByEmail() )
                .withDocument( newDocumentWithName( "My Document" )
                    .fromFile("DOCUMENT_FILE_PATH" )
                    .withSignature( signatureFor( myGroup.getId() )
                         .onPage( 0 )
                         .atPosition( 370, 680 ) ) )
                .build();
              
PackageId packageId = esl.createAndSendPackage( myPackage );

Results

After executing your code, you will find your newly created groups in your OneSpan Sign account.

Capture

If you used the sample code in this topic to retrieve your groups, here is the output:

list

You will also find your group signature in your document, as shown below.

Capture

To download the full code sample see our Code Share site.

Sometimes it's convenient to share requests for signatures among the members of a group. For example, it might be convenient to treat the pharmacists in a particular pharmacy as a group, so that any available member of the group can sign the paperwork for a patient's prescriptions.

In OneSpan Sign, a Signer Group is a set of OneSpan Sign users who can act as a single signer from the point of view of the package creator. Users who can become group members must already be members of the associated OneSpan Sign account.

OneSpan Sign group members receive an email invitation to sign a related document package. Among those members, signing is on a first-come, first-serve basis. When one member is signing, all other members are locked out.

Any member who signs does so on behalf of the group, but their name will be stamped on the documents they sign. Anyone verifying the document through the Audit Trail will see the individual member's signature information and identity.

All group members can monitor the progress of the group's transactions, which helps ensure that those transactions are completed on time.

Finding Your Groups in the UI

First, locate your Groups in the OneSpan Sign Web UI. To do this, log into your OneSpan Sign account and click Admin > Groups. After running your code, all your groups will appear here. If you do not see the Groups option in the toolbar, it could be because they have not been enabled on your account. To enable them, please contact our Support Team.

For more information, see Administering Groups.

Creating Groups

The sample code below will create a group called Java Developers, with two members. It is important to note that these members have to be Senders in your account. The withIndividualMemberEmailing() method will send emails to the members of the group instead of the specified group email. If you wish to send emails to the group email instead, use withoutIndividualEmailing().

Group group1 = GroupBuilder.NewGroup("My Group")
               .WithCustomId(new GroupId(Guid.NewGuid().ToString()))
               .WithMember(GroupMemberBuilder.NewGroupMember("[email protected]")
                    .AsMemberType(GroupMemberType.MANAGER))
               .WithMember(GroupMemberBuilder.NewGroupMember("[email protected]")
                    .AsMemberType(GroupMemberType.REGULAR))
               .WithEmail("[email protected]")
               .WithIndividualMemberEmailing()
               .Build();

Once you have done this, you can call on your OneSpan Sign GroupService to create your group.

Group createdGroup1 = eslClient.GroupService.CreateGroup(group1);

You can also create an empty group, and invite members to join your group at a later date.

eslClient.GroupService.InviteMember(createdEmptyGroup.Id, GroupMemberBuilder.NewGroupMember("[email protected]")
            .AsMemberType(GroupMemberType.REGULAR)
            .Build());

Retrieving Groups

Retrieving your groups can come in handy when you wish to invite members to your group. It is important to note that the group id is required when sending invitations. The first line in the sample code below will retrieve your groups as a list. Then, for each group object in the list, the group name, email, and id are retrieved. With your group ids, you can retrieve each member, along with their email, first name, and last name.

List<Group> allGroups = eslClient.GroupService.GetMyGroups();
        foreach (Group group in allGroups)
        {
            Debug.WriteLine(group.Name + " with email " + group.Email + " and id " + group.Id.Id);
            List<GroupMember> allMembers = eslClient.GroupService.GetGroupMembers(group.Id);
            foreach (GroupMember member in allMembers)
            {
                Debug.WriteLine(member.GroupMemberType.ToString() + " " + member.FirstName + " " + member.LastName + " with email " + member.Email);
            }
        }

Adding a Group Signer

Once your group has been created, you can now then add a group signer to your package. The code below shows you how to edit the signer block in order to add a group signer.

DocumentPackage superDuperPackage = PackageBuilder.NewPackageNamed("My Package with Group Signers .NET Developers")
            .WithSigner(SignerBuilder.NewSignerFromGroup(myGroup.Id)
                .CanChangeSigner()
                .DeliverSignedDocumentsByEmail())
            .WithDocument(DocumentBuilder.NewDocumentNamed("My Document")
                .FromFile("DOCUMENT_FILE_PATH")
                .WithSignature(SignatureBuilder.SignatureFor(myGroup.Id)
                  .OnPage(0)
                  .AtPosition(370, 680)))
            .Build();
 
PackageId packageId = eslClient.CreateAndSendPackage(superDuperPackage);

Results

After executing your code, you will find your newly created groups in your OneSpan Sign account.

Capture

If you used the sample code in this topic to retrieve your groups, here is the output:

list

You will also find your group signature in your document, as shown below.

Capture

To download the full code sample see our Code Share site.

Sometimes it's convenient to share requests for signatures among the members of a group. For example, it might be convenient to treat the pharmacists in a particular pharmacy as a group, so that any available member of the group can sign the paperwork for a patient's prescriptions.

In OneSpan Sign, a Signer Group is a set of OneSpan Sign users who can act as a single signer from the point of view of the package creator. Users who can become group members must already be members of the associated OneSpan Sign account.

OneSpan Sign group members receive an email invitation to sign a related document package. Among those members, signing is on a first-come, first-serve basis. When one member is signing, all other members are locked out.

Any member who signs does so on behalf of the group, but their name will be stamped on the documents they sign. Anyone verifying the document through the Audit Trail will see the individual member's signature information and identity.

All group members can monitor the progress of the group's transactions, which helps ensure that those transactions are completed on time.

Finding Your Groups in the UI

First, locate your Groups in the OneSpan Sign Web UI. To do this, log into your OneSpan Sign account and click Admin > Groups. After running your code, all your groups will appear here. If you do not see the Groups option in the toolbar, it could be because they have not been enabled on your account. To enable them, please contact our Support Team.

For more information, see Administering Groups.

Creating Groups

The sample code below will create a group with two members. It is important to note that these members have to be Senders in your account.

HTTP Request

POST /api/groups

HTTP Headers

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

Request Payload

{
  "email": "[email protected]",
  "name": "your_group_name",
        "members": [
    {
      "pending": true,
      "email": "[email protected]",
      "memberType": "REGULAR",
      "firstName": "Max",
      "lastName": "Domi"
    },
    {
      "pending": true,
      "email": "[email protected]",
      "memberType": "REGULAR",
      "firstName": "John",
      "lastName": "Smith"
    }
  ]
}

Response Payload

{
    "id": "bc65203e-99df-47b4-a51c-33e8082780c5",
    "members": [
        {
            "userId": "2q37oSloj5AD",
            "pending": false,
            "lastName": "Tango",
            "email": "[email protected]",
            "firstName": "Mike",
            "memberType": "REGULAR"
        },
        {
            "userId": "FxktNzFzmkIY",
            "pending": false,
            "lastName": "Domi",
            "email": "[email protected]",
            "firstName": "Max",
            "memberType": "REGULAR"
        }
    ],
    "emailMembers": false,
    "reciprocalDelegation": false,
    "data": null,
    "account": {
        "id": "3vD0Dc9Fh7wQ",
        "data": null,
        "updated": "2017-11-20T19:03:28Z",
        "company": {
            "id": "",
            "data": null,
            "address": null,
            "name": ""
        },
        "licenses": [],
        "logoUrl": "",
        "providers": null,
        "customFields": [],
        "created": "2017-11-20T19:03:28Z",
        "owner": "",
        "name": ""
    },
    "updated": "2017-11-20T19:03:28Z",
    "email": "[email protected]",
    "created": "2017-11-20T19:03:28Z",
    "name": "your_group_name"
}

You can also create an empty group, and invite members to join your group at a later date.

HTTP Request

POST /api/groups

HTTP Headers

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

Request Payload

{
    "email": "[email protected]",
    "name": "REST Developers"
}

Response Payload

{
    "id": "540b86f9-2d93-4498-bdb4-b7b320540bb6",
    "members": [],
    "emailMembers": false,
    "reciprocalDelegation": false,
    "data": null,
    "account": {
        "id": "3vD0Dc9Fh7wQ",
        "data": null,
        "updated": "2017-11-20T19:04:38Z",
        "company": {
            "id": "",
            "data": null,
            "address": null,
            "name": ""
        },
        "licenses": [],
        "logoUrl": "",
        "providers": null,
        "customFields": [],
        "created": "2017-11-20T19:04:38Z",
        "owner": "",
        "name": ""
    },
    "updated": "2017-11-20T19:04:38Z",
    "email": "[email protected]",
    "created": "2017-11-20T19:04:38Z",
    "name": "REST Developers"
}

Retrieving Groups

Retrieving your groups can come in handy when you wish to invite members to your group. It is important to note that the group id is required when sending invitations.

HTTP Request

GET /api/groups

HTTP Headers

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

Response Payload

{
  "count": 1,
  "results": [
    {
      "account": {
        "providers": null,
        "updated": "2016-01-07T18:49:19Z",
        "company": {
          "id": "",
          "address": null,
          "data": null,
          "name": ""
        },
        "licenses": [],
        "logoUrl": "",
        "customFields": [],
        "created": "2016-01-07T18:49:19Z",
        "owner": "",
        "id": "zRcJCHV3ztIB",
        "data": null,
        "name": ""
      },
      "updated": "2016-01-07T13:58:33Z",
      "email": "[email protected]",
      "members": [
        {
          "userId": "1XyqlkXM9uIX",
          "email": "[email protected]",
          "firstName": "John",
          "lastName": "Doe",
          "memberType": "REGULAR",
          "pending": false
        },
        {
          "userId": "kVooKpofKuUK",
          "email": "[email protected]",
          "firstName": "Mary",
          "lastName": "Doe",
          "memberType": "REGULAR",
          "pending": false
        }
      ],
      "emailMembers": false,
      "reciprocalDelegation": false,
      "created": "2016-01-07T13:58:33Z",
      "id": "4a8868d7-1968-4172-aedb-0a9dc8edb683",
      "data": null,
      "name": "REST Developers"
    }
  ]
}

Adding a Group signer

Once your group has been created, you can now then add a group signer to your package. The code below shows you how to edit the signer block in order to add a group signer.

If you need a comparison to the basic document object creation or if this is the first time creating a package with the REST API, see this guide.

HTTP Request

POST /api/packages

HTTP Headers

Accept: application/json
Content-Type: multipart/form-data
Authorization: Basic api_key

Request Payload

------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="file"; filename="testDocumentExtraction.pdf"
Content-Type: application/pdf
%PDF-1.5
%µµµµ
1 0 obj
<>>>
endobj.... 
------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="payload"
{
  "roles": [
    {
      "id": "1945f2e1-3390-4297-bc3b-89af3c92e567",
      "type": "SIGNER",
      "index": 0,
      "signers": [
        {
          "group": {
            "id": "540b86f9-2d93-4498-bdb4-b7b320540bb6",
            "email": "[email protected]",
            "name": "REST Developers"
          },
          "id": "98b9db64-39ca-4b5b-a1eb-629e49c46dec",
          "email": "[email protected]",
          "firstName": "REST Developers",
          "lastName": ""
        }
      ],
      "name": "Signer1"
    }
  ],
  "status": "DRAFT",
  "language": "en",
  "documents": [
    {
      "id": "90277a614bf73b783fe2a5e04b68a99d4badf449b33ecfbf",
      "approvals": [
        {
          "id": "cVvJzBDX7lwP",
          "role": "1945f2e1-3390-4297-bc3b-89af3c92e567",
          "fields": [
            {
              "subtype": "FULLNAME",
              "height": 52,
              "extract": false,
              "width": 235,
              "left": 217,
              "top": 512,
              "type": "SIGNATURE"
            }
          ]
        }
      ],
      "name": "sample_contract"
    }
  ],
  "visibility": "ACCOUNT",
  "type": "PACKAGE",
  "name": "Group Signature Example"
}
------WebKitFormBoundary1bNO60n7FqP5WO4t--

Response Payload

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

Results

After executing your code, you will find your newly created groups in your OneSpan Sign account.

You will also find your group signature in your document, as shown below.

Capture

Request Payload Table

PropertyTypeEditableRequiredDefaultSample Values
emailstringYesNon/a[email protected]
namestringYesNon/ayour_group_name
members
pendingbooleanNoNon/atrue / false
emailstringYesNon/a[email protected]
memberTypestringYesNoREGULARREGULAR / MANAGER
firstNamestringYesNon/aMax
lastNamestringYesNon/aDomi

After executing your code, you will find your newly created groups in your OneSpan Sign account.Capture