During a Signing Ceremony, by default all recipients can view all documents in a transaction. However, the visibility of such documents can be configured to determine which recipients can view which documents. This can save recipients from having to process documents they don’t need to see, and it can ensure that documents with sensitive information are viewed only by their intended recipients.

This Document Visibility feature is disabled by default. To enable it for your account, you must contact our Support Team.

The Code

For this example, a transaction is setup such that recipient A is only required to sign document A and recipient B is only required to sign document B, as shown below:
DocumentPackage superDuperPackage = PackageBuilder.newPackageNamed("DocumentVisibilityExample " + new SimpleDateFormat("HH:mm:ss").format(new Date()))
        .describedAs("This is a package created using the OneSpan Sign SDK")
        .withSigner(SignerBuilder.newSignerWithEmail("[email protected]")
                        .withCustomId(SIGNER1_ID)
                        .withFirstName("John1")
                        .withLastName("Smith1"))
        .withSigner(SignerBuilder.newSignerWithEmail("[email protected]")
                        .withCustomId(SIGNER2_ID)
                        .withFirstName("John2")
                        .withLastName("Smith2"))
        .withDocument(DocumentBuilder.newDocumentWithName("Document1")
                          .withId(DOC1_ID)
                          .fromFile(DOC_FILE_PATH_1)
                          .withSignature(SignatureBuilder.signatureFor("[email protected]")
                                             .onPage(0)
                                             .atPosition(100, 100)))
        .withDocument(DocumentBuilder.newDocumentWithName("Document2")
                          .withId(DOC2_ID)
                          .fromFile(DOC_FILE_PATH_2)
                          .withSignature(SignatureBuilder.signatureFor("[email protected]")
                                             .onPage(0)
                                             .atPosition(100, 100)))
        .build();
You can configure each document's visibility such that during the signing ceremony, recipient A only views document A and recipient B only views document B, for example. After you've created your transaction, you will need to create your DocumentVisibility object using OneSpan Sign's DocumentVisibilityBuilder. You can add a configurations for each document's visibility using the custom ids set in the previous step (e.g. .withId(DOC1_ID)).
com.silanis.esl.sdk.DocumentVisibility visibility = DocumentVisibilityBuilder.newDocumentVisibility()
    .addConfiguration(DocumentVisibilityConfigurationBuilder.newDocumentVisibilityConfiguration(DOC1_ID)
    		.withSignerIds(signerIdsList1))
    .addConfiguration(DocumentVisibilityConfigurationBuilder.newDocumentVisibilityConfiguration(DOC2_ID)
    		.withSignerIds(signerIdsList2))
    .build();
Likewise, you can also configure a document visibility based on recipients/signers:
com.silanis.esl.sdk.DocumentVisibility visibility = newDocumentVisibilityBasedOnSigner()
            .addConfiguration(newDocumentVisibilityConfigurationBasedOnSigner(SIGNER1_ID)
                                  .withDocumentIds(Arrays.asList(DOC1_ID)))
            .addConfiguration(newDocumentVisibilityConfigurationBasedOnSigner(SIGNER2_ID)
                                  .withDocumentIds(Arrays.asList(DOC2_ID)))
            .build();
Once you've configured your document visibility, you can retrieve a list of recipients/signers who can view a document:
List<Signer> signersForDocument1 = eslClient.getSigners(packageId, DOC1_ID);
Similarly, you can retrieve a list of documents for which a recipient/signer can view:
List<Document> documentsForSigner1 = eslClient.getDocuments(packageId, SIGNER1_ID);
Finally, you set your documents' visibility and send your transaction using the OneSpan Sign client:
eslClient.configureDocumentVisibility(packageId, visibility);
eslClient.sendPackage(packageId);

Running Your Code

Below are screenshots of what both recipients see when they access the transaction. Recipient A:

CaptureRecipient B: Capture

As you can see, the first recipient only views the document which requires his/her signature. The same holds true for the second recipient.

Get the Code | See this feature in action in our Interactive Demo

During a Signing Ceremony, by default all recipients can view all documents in a transaction. However, the visibility of such documents can be configured to determine which recipients can view which documents. This can save recipients from having to process documents they don’t need to see, and it can ensure that documents with sensitive information are viewed only by their intended recipients.

This Document Visibility feature is disabled by default. To enable it for your account, you must contact our Support Team.

The Code

For this example, a transaction is setup such that recipient A is only required to sign document A and recipient B is only required to sign document B, as shown below:
DocumentPackage superDuperPackage = PackageBuilder.NewPackageNamed("DocumentVisibilityExample " + DateTime.Now)
        .DescribedAs("This is a package created using the OneSpan Sign SDK")
        .WithSigner(SignerBuilder.NewSignerWithEmail("[email protected]")
                        .WithCustomId(SIGNER1_ID)
                        .WithFirstName("John1")
                        .WithLastName("Smith1"))
        .WithSigner(SignerBuilder.NewSignerWithEmail("[email protected]")
                        .WithCustomId(SIGNER2_ID)
                        .WithFirstName("John2")
                        .WithLastName("Smith2"))
        .WithDocument(DocumentBuilder.NewDocumentNamed("Document1")
                          .WithId(DOC1_ID)
                          .FromFile("C:/Users/hhaidary/Desktop/PDFs/sample_contract.pdf")
                          .WithSignature(SignatureBuilder.SignatureFor("[email protected]")
                                             .OnPage(0)
                                             .AtPosition(100, 100)))
        .WithDocument(DocumentBuilder.NewDocumentNamed("Document2")
                          .WithId(DOC2_ID)
                          .FromFile("C:/Users/hhaidary/Desktop/PDFs/cleaning_contract.pdf")
                          .WithSignature(SignatureBuilder.SignatureFor("[email protected]")
                                             .OnPage(0)
                                             .AtPosition(100, 100)))
        .Build();
You can configure each document's visibility such that during the signing ceremony, recipient A only views document A and recipient B only views document B, for example. After you've created your transaction, you will need to create your DocumentVisibility object using OneSpan Sign's DocumentVisibilityBuilder. You can add a configurations for each document's visibility using the custom ids set in the previous step (e.g. .WithId(DOC1_ID)).
Silanis.ESL.SDK.DocumentVisibility visibility = DocumentVisibilityBuilder.NewDocumentVisibility()
        .AddConfiguration(DocumentVisibilityConfigurationBuilder.NewDocumentVisibilityConfiguration(DOC1_ID)
                .WithSignerIds(signerIdsList1))
        .AddConfiguration(DocumentVisibilityConfigurationBuilder.NewDocumentVisibilityConfiguration(DOC2_ID)
                .WithSignerIds(signerIdsList2))
        .Build();
Likewise, you can also configure a document visibility based on recipients/signers:
Silanis.ESL.SDK.DocumentVisibility visibility = DocumentVisibilityBuilder.newDocumentVisibilityBasedOnSigner()
            .AddConfiguration(DocumentVisibilityConfigurationBasedOnSignerBuilder.NewDocumentVisibilityConfigurationBasedOnSigner(SIGNER1_ID)
                                  .WithDocumentIds(new List{ DOC1_ID }))
            .AddConfiguration(DocumentVisibilityConfigurationBasedOnSignerBuilder.newDocumentVisibilityConfigurationBasedOnSigner(SIGNER2_ID)
                                  .WithDocumentIds(new List{ DOC2_ID }))
            .Build();
Once you've configured your document visibility, you can retrieve a list of recipients/signers who can view a document:
IList<Signer> signersForDocument1 = eslClient.GetSigners(packageId, DOC1_ID);
Similarly, you can retrieve a list of documents for which a recipient/signer can view:
IList<Document> documentsForSigner1 = eslClient.GetDocuments(packageId, SIGNER1_ID);
Finally, you set your documents' visibility and send your transaction using the OneSpan Sign client:
eslClient.ConfigureDocumentVisibility(packageId, visibility);
eslClient.SendPackage(packageId);

Running Your Code

Below are screenshots of what both recipients see when they access the transaction. Recipient A:

CaptureRecipient B: Capture

As you can see, the first recipient only views the document which requires his/her signature. The same holds true for the second recipient.

Get the Code | See this feature in action in our Interactive Demo

During a Signing Ceremony, by default all recipients can view all documents in a transaction. However, the visibility of such documents can be configured to determine which recipients can view which documents. This can save recipients from having to process documents they don’t need to see, and it can ensure that documents with sensitive information are viewed only by their intended recipients.

This Document Visibility feature is disabled by default. To enable it for your account, you must contact our Support Team.

The Code

For this example, a transaction is setup such that recipient A is only required to sign document A and recipient B is only required to sign document B. Below is a JSON payload for such a scenario:

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"
{
  "autocomplete": true,
  "description": "This is a package created using the OneSpan Sign REST API",
  "documents": [
    {
      "approvals": [
        {
          "fields": [
            {
              "extract": false,
              "height": 50,
              "left": 100,
              "page": 0,
              "subtype": "FULLNAME",
              "top": 100,
              "type": "SIGNATURE",
              "width": 200
            }
          ],
          "role": "Signer1"
        }
      ],
      "extract": false,
      "id": "doc1",
      "index": 0,
      "name": "Document1"
    },
    {
      "approvals": [
        {
          "fields": [
            {
              "extract": false,
              "height": 50,
              "left": 100,
              "page": 0,
              "subtype": "FULLNAME",
              "top": 100,
              "type": "SIGNATURE",
              "width": 200
            }
          ],
          "role": "Signer2"
        }
      ],
      "extract": false,
      "fields": [],
      "id": "doc2",
      "index": 0,
      "name": "Document2",
      "pages": []
    }
  ],
  "name": "DocumentVisibilityExample REST API",
  "roles": [
    {
      "id": "Signer1",
      "index": 0,
      "name": "Signer1",
      "signers": [
        {
          "email": "[email protected]",
          "firstName": "John1",
          "id": "Signer1",
          "lastName": "Smith1"
        }
      ]
    },
    {
      "id": "Signer2",
      "index": 0,
      "name": "Signer2",
      "signers": [
        {
          "email": "[email protected]",
          "firstName": "John2",
          "id": "Signer2",
          "lastName": "Smith2"
        }
      ]
    }
  ],
  "type": "PACKAGE",
  "visibility": "ACCOUNT"
}
------WebKitFormBoundary1bNO60n7FqP5WO4t--

For a complete description of each field, take a look at the Request Payload section below.

Response Payload

{
    "id": "9sKhW-h-qS9m6Ho3zRv3n2a-rkI="
}
You can configure each document's visibility such that during the signing ceremony, recipient A only views document A and recipient B only views document B, for example. After you've created your transaction, you will need to make a POST https://sandbox.esignlive.com/api/packages/{packageId}/documents/visibility with the following JSON payload:

HTTP Headers

Accept: application/json Content-Type: application/json Authorization: Basic api_key
{
  "configurations": [
    {
      "documentUid": "doc1",
      "roleUids": [
        "Signer1"
      ]
    },
    {
      "documentUid": "doc2",
      "roleUids": [
        "Signer2"
      ]
    }
  ]
}
You can add a configurations for each document's visibility using the custom ids set in the previous step (e.g. "id": "doc1"). Once you've configured your document visibility, you can retrieve your document visibility as such: GET https://sandbox.esignlive.com/api/packages/{packageId}/documents/visibility Finally, you send your transaction by making a PUT https://sandbox.esignlive.com/api/packages/{packageId} with the JSON payload below:
{
  "status": "SENT"
}

Running Your Code

Below are screenshots of what both recipients see when they access the transaction. Recipient A:

CaptureRecipient B: Capture

As you can see, the first recipient only views the document which requires his/her signature. The same holds true for the second recipient.

Get the Code | See this feature in action in our Interactive Demo

Request Payload

PropertyTypeEditableRequiredDefaultSample Value(s)
statusstringYesNoDRAFTDRAFT / SENT / COMPLETED / ARCHIVED / DECLINED / OPTED_OUT / EXPIRED
autoCompletebooleanYesNotruetrue / false
typestringYesNoPACKAGEPACKAGE / TEMPLATE / LAYOUT
namestringYesYesn/aDocumentVisibilityExample REST API
descriptionstringYesYesn/aThis is a package created using the OneSpan Sign REST API
trashedbooleanYesNofalsetrue / false
visibilitystringYesNoACCOUNTACCOUNT / SENDER
documents
idstringYesNon/adoc1
namestringYesNon/aDocument1
indexintegerYesNo00 / 1 / 2 ...
extractbooleanYesNofalsefalse / true
approvals
fields
subtypestringYesNon/aFULLNAME / INITIALS / CAPTURE / MOBILE_CAPTURE / LABEL / TEXTFIELD / TEXTAREA / CHECKBOX / DATE / RADIO / LIST
typestringYesNon/aSIGNATURE / INPUT
extractbooleanYesNofalsetrue / false
heightintegerYesNo5050 / 100 / 150 ...
leftintegerYesNo050 / 100 / 150 ...
pageintegerYesNo00 / 1 / 2 ...
topintegerYesNo050 / 100 / 150 ...
widthintegerYesNo20050 / 100 / 150 ...
rolestringYesNon/aSigner1
roles
idstringYesNon/aSigner1
indexintegerYesNo00 / 1 / 2 ...
namestringYesNon/aSigner1
typestringYesNoSIGNERSIGNER / SENDER
signers
emailstringYesYesn/a[email protected]
firstNamestringYesYesn/aJohn1
lastNamestringYesYesn/aSmith1
phonestringYesNon/a514-555-8888
idstringYesNon/aSigner1
companystringYesNon/aAcme Inc.
titlestringYesNon/aManaging Director
During a Signing Ceremony, by default all recipients can view all documents in a transaction. However, the visibility of such documents can be configured to determine which recipients can view which documents. This can save recipients from having to process documents they don’t need to see, and it can ensure that documents with sensitive information are viewed only by their intended recipients.

This Document Visibility feature is disabled by default. To enable it for your account, you must contact our Support Team.

The Code

To notice, some of the code is an extension of the APEX SDK and can be gotten through this code share. In this example, a transaction is setup such that recipient1 is only required to sign document1 and recipient2 is only required to sign document2, as shown below:
    	ESignLiveSDK sdk = new ESignLiveSDK();
         
        //Create package
        ESignLiveAPIObjects.Package_x pkg = new ESignLiveAPIObjects.Package_x();
        pkg.name = 'Test Document Visibility - ' + Datetime.now().format();
        pkg.status = ESignLiveAPIObjects.PackageStatus.DRAFT;
        
        //Create Roles
        String roleId1 = 'Signer1';
        ESignLiveAPIObjects.Role role1 = new ESignLiveAPIObjects.Role();
        role1.signers = sdk.createRolesSigner('sigenr1_firstname', 'signer1_lastname', '[email protected]', 'CEO', 'ABC Bank');
        role1.id = roleId1;
        role1.name = roleId1;
        
        String roleId2 = 'Signer2';
        ESignLiveAPIObjects.Role role2 = new ESignLiveAPIObjects.Role();
        role2.signers = sdk.createRolesSigner('sigenr2_firstname', 'signer2_lastname', '[email protected]', 'Applicant', 'ABC Company');
        role2.id = roleId2;
        role2.name = roleId2;
        
        pkg.roles = new List<ESignLiveAPIObjects.Role>{role1,role2};    //add role
        
        //Prepare Documents Blob
        //use single document twice, just for test
        String document1Name = 'document1';
        String document2Name = 'document2';
        StaticResource sr = [SELECT Id, Body FROM StaticResource WHERE Name = 'testdoc1' LIMIT 1];
        Map<String,Blob> documentBlobMap = new Map<String,Blob>();
        documentBlobMap.put(document1Name, sr.Body);
        documentBlobMap.put(document2Name, sr.Body);
         
        //Create Document Metadata
        ESignLiveAPIObjects.Document document1 = new ESignLiveAPIObjects.Document();
        document1.name = document1Name;
        document1.id = document1Name;
        ESignLiveAPIObjects.Document document2 = new ESignLiveAPIObjects.Document();
        document2.name = document2Name;
        document2.id = document2Name;
		
        pkg.documents = new List<ESignLiveAPIObjects.Document>{document1,document2};    //add document
        
    	//Send package One Step
        String packageId = sdk.createPackage(pkg,documentBlobMap);
        System.debug('PackageId: ' + packageId);
You can configure each document’s visibility such that during the signing ceremony, recipient1 only views document1 and recipient2 only views document 2, for example. After you’ve created your transaction, you will need to create your DocumentVisibility object and add configurations for each document’s visibility using the Role IDs set in the previous step (e.g. role1.id = roleId1).
    	//configure documentVisibility
    	DocumentVisibility documentVisibility = new DocumentVisibility()
    							.addConfiguration(new DocumentVisibilityConfiguration('document1')
    											.addRole('Signer1'))
    							.addConfiguration(new DocumentVisibilityConfiguration('document2')
    											.addRole('Signer2'));
Once you’ve configured your document visibility, you can retrieve a list of recipients/signers who can view a document by below encapsulated function:
    public List<ESignLiveAPIObjects.Role> getSigners(String packageId, String documentId)
Similarly, you can retrieve a list of documents for which a recipient/signer can view by below encapsulated function:
    public List<ESignLiveAPIObjects.Document> getDocuments(String packageId, String roleId)
Finally, you set your documents’ visibility and send your transaction using the OneSpan Sign client:
   	configureDocumentVisibility(packageId, documentVisibility);
   	sdk.setStatus(packageId , ESignLiveAPIObjects.PackageStatus.SENT);

Running Your Code

Below are screenshots of what both recipients see when they access the transaction. Recipient A:

CaptureRecipient B: Capture

As you can see, the first recipient only views the document which requires his/her signature. The same holds true for the second recipient.

Get the Code | See this feature in action in our Interactive Demo