Document Visibility

The following guide shows you how to configure the Document Visibility feature.

By default, during a signing ceremony all recipients can view all documents in a transaction. Documents’ visibility can be configured to allow control which recipients can view specific documents in a transaction during a signing ceremony.

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.

The Document Visibility feature is disabled by default. It must be enabled for your account through support before you will be able to use it (sign.support@onespan.com).

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("mail31@mailinator.com")
                        .withCustomId(SIGNER1_ID)
                        .withFirstName("John1")
                        .withLastName("Smith1"))
        .withSigner(SignerBuilder.newSignerWithEmail("mail32@mailinator.com")
                        .withCustomId(SIGNER2_ID)
                        .withFirstName("John2")
                        .withLastName("Smith2"))
        .withDocument(DocumentBuilder.newDocumentWithName("Document1")
                          .withId(DOC1_ID)
                          .fromFile(DOC_FILE_PATH_1)
                          .withSignature(SignatureBuilder.signatureFor("mail31@mailinator.com")
                                             .onPage(0)
                                             .atPosition(100, 100)))
        .withDocument(DocumentBuilder.newDocumentWithName("Document2")
                          .withId(DOC2_ID)
                          .fromFile(DOC_FILE_PATH_2)
                          .withSignature(SignatureBuilder.signatureFor("mail32@mailinator.com")
                                             .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:

Capture

Recipient 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

By default, during a signing ceremony all recipients can view all documents in a transaction. Documents’ visibility can be configured to allow control which recipients can view specific documents in a transaction during a signing ceremony.

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.

The Document Visibility feature is disabled by default. It must be enabled for your account through support before you will be able to use it (sign.support@onespan.com).

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("mail31@mailinator.com")
                        .WithCustomId(SIGNER1_ID)
                        .WithFirstName("John1")
                        .WithLastName("Smith1"))
        .WithSigner(SignerBuilder.NewSignerWithEmail("mail32@mailinator.com")
                        .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("mail31@mailinator.com")
                                             .OnPage(0)
                                             .AtPosition(100, 100)))
        .WithDocument(DocumentBuilder.NewDocumentNamed("Document2")
                          .WithId(DOC2_ID)
                          .FromFile("C:/Users/hhaidary/Desktop/PDFs/cleaning_contract.pdf")
                          .WithSignature(SignatureBuilder.SignatureFor("mail32@mailinator.com")
                                             .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:

Capture

Recipient 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

By default, during a signing ceremony all recipients can view all documents in a transaction. Documents’ visibility can be configured to allow control which recipients can view specific documents in a transaction during a signing ceremony.

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.

The Document Visibility feature is disabled by default. It must be enabled for your account through support before you will be able to use it (sign.support@onespan.com).

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": "mail31@mailinator.com",
          "firstName": "John1",
          "id": "Signer1",
          "lastName": "Smith1"
        }
      ]
    },
    {
      "id": "Signer2",
      "index": 0,
      "name": "Signer2",
      "signers": [
        {
          "email": "mail32@mailinator.com",
          "firstName": "John2",
          "id": "Signer2",
          "lastName": "Smith2"
        }
      ]
    }
  ],
  "type": "PACKAGE",
  "visibility": "ACCOUNT"
}

------WebKitFormBoundary1bNO60n7FqP5WO4t--

For a complete description of each field, take a look at the JSON Properties 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:

Capture

Recipient 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

JSON Properties

Property Type Editable Required Default Sample Value(s)
status string Yes No DRAFT DRAFT / SENT / COMPLETED / ARCHIVED / DECLINED / OPTED_OUT / EXPIRED
autoComplete boolean Yes No true true / false
type string Yes No PACKAGE PACKAGE / TEMPLATE / LAYOUT
name string Yes Yes n/a DocumentVisibilityExample REST API
description string Yes Yes n/a This is a package created using the OneSpan Sign REST API
trashed boolean Yes No false true / false
visibility string Yes No ACCOUNT ACCOUNT / SENDER
documents
id string Yes No n/a doc1
name string Yes No n/a Document1
index integer Yes No 0 0 / 1 / 2 …
extract boolean Yes No false false / true
approvals
fields
subtype string Yes No n/a FULLNAME / INITIALS / CAPTURE / MOBILE_CAPTURE / LABEL / TEXTFIELD / TEXTAREA / CHECKBOX / DATE / RADIO / LIST
type string Yes No n/a SIGNATURE / INPUT
extract boolean Yes No false true / false
height integer Yes No 50 50 / 100 / 150 …
left integer Yes No 0 50 / 100 / 150 …
page integer Yes No 0 0 / 1 / 2 …
top integer Yes No 0 50 / 100 / 150 …
width integer Yes No 200 50 / 100 / 150 …
role string Yes No n/a Signer1
roles
id string Yes No n/a Signer1
index integer Yes No 0 0 / 1 / 2 …
name string Yes No n/a Signer1
type string Yes No SIGNER SIGNER / SENDER
signers
email string Yes Yes n/a mail31@mailinator.com
firstName string Yes Yes n/a John1
lastName string Yes Yes n/a Smith1
phone string Yes No n/a 514-555-8888
id string Yes No n/a Signer1
company string Yes No n/a Acme Inc.
title string Yes No n/a Managing Director