--- title: "Configuring Document Visibility" slug: "configuring-document-visibility" updated: 2025-07-02T18:30:12Z published: 2025-07-02T18:30:12Z canonical: "docs.onespan.com/configuring-document-visibility" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.onespan.com/llms.txt > Use this file to discover all available pages before exploring further. # Configuring Document Visibility [Java SDK](/v1/docs/configuring-document-visibility#java-sdk) [.NET SDK](/v1/docs/configuring-document-visibility#net-sdk) [REST API](/v1/docs/configuring-document-visibility#rest-api) [APEX SDK](/v1/docs/configuring-document-visibility#apex-sdk) ## Java SDK To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/set-document-visibility-java-sdk/) site. You can also see this feature in our [Interactive Demo.](https://secure.onespan.com/interactive-demo.html) During a [Signer Experience](/v1/docs/using-the-signer-experience), by default all recipients can view all documents in a transaction. However, you can configure your transactions so that certain documents can only be seen by specific recipients. 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. By default, adding a recipient to a transaction will give that recipient visibility to all documents. As a best practice, we recommend that you set document visibility after all documents and recipients have been added to the transaction. If you need to add a recipient after you have set document visibility, be sure to verify the document visibility of the recipient you have just added. ### Defining Document Signing By Recipient For this example, a transaction is setup such that Signer1 is only required to sign Document 1 and Signer2 is only required to sign Document 2, as shown below: ```java 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@example.com")        .withCustomId(SIGNER1_ID)        .withFirstName("John1")        .withLastName("Smith1"))    .withSigner(SignerBuilder.newSignerWithEmail("mail32@example.com")        .withCustomId(SIGNER2_ID)        .withFirstName("John2")        .withLastName("Smith2"))    .withDocument(DocumentBuilder.newDocumentWithName("Document1")        .withId(DOC1_ID)        .fromFile(DOC_FILE_PATH_1)        .withSignature(SignatureBuilder.signatureFor("mail31@example.com")            .onPage(0)            .atPosition(100, 100)))    .withDocument(DocumentBuilder.newDocumentWithName("Document2")        .withId(DOC2_ID)        .fromFile(DOC_FILE_PATH_2)        .withSignature(SignatureBuilder.signatureFor("mail32@example.com")            .onPage(0)            .atPosition(100, 100)))    .build(); ``` ### Defining Document Visibility By Recipient You can configure each document so that only a specified signer can see that document.This can ensure that documents with sensitive information are viewed only by their intended recipients. After you have created your transaction, you will need to create your DocumentVisibility object and add configurations for the visibility of each After you've created your transaction, you will need to create your DocumentVisibility object using the OneSpan Sign DocumentVisibilityBuilder.Then you add configurations for the visibility of each document using the custom ids set in the previous section.For example, withId(DOC1_ID). ```java com.silanis.esl.sdk.DocumentVisibility visibility = DocumentVisibilityBuilder.newDocumentVisibility()    .addConfiguration(        DocumentVisibilityConfigurationBuilder.newDocumentVisibilityConfiguration(DOC1_ID)            .withSignerIds(signerIdsList1)    )    .addConfiguration(        DocumentVisibilityConfigurationBuilder.newDocumentVisibilityConfiguration(DOC2_ID)            .withSignerIds(signerIdsList2)    )    .build(); ``` You can also configure document visibility based on specific signers: ```java 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(); ``` #### Retrieving a List of Signers Per Document Once you have set these configurations, you can then retrieve a list of signers who can view a document: ```java List signersForDocument1 = eslClient.getSigners(packageId, DOC1_ID); ``` Similarly, you can retrieve a list of documents for which a signer can view: ```java List documentsForSigner1 = eslClient.getDocuments(packageId, SIGNER1_ID); ``` ### Setting Visibility and Sending the Transaction Finally, you set the visibility of your documents and send your transaction using the OneSpan Sign client: ```java eslClient.configureDocumentVisibility(packageId, visibility); eslClient.sendPackage(packageId); ``` ### Results Each recipient will only see the document assigned to them. ## .NET SDK To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/set-document-visibility-net-sdk/) site. You can also see this feature in our [Interactive Demo.](https://secure.onespan.com/interactive-demo.html) During a [Signer Experience](/v1/docs/using-the-signer-experience), by default all recipients can view all documents in a transaction. However, you can configure your transactions so that certain documents can only be seen by specific recipients. 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. By default, adding a recipient to a transaction will give that recipient visibility to all documents. As a best practice, we recommend that you set document visibility after all documents and recipients have been added to the transaction. If you need to add a recipient after you have set document visibility, be sure to verify the document visibility of the recipient you have just added. ### Defining Document Signing By Recipient For this example, a transaction is setup such that Signer1 is only required to sign Document 1 and Signer2 is only required to sign Document 2, as shown below: ```csharp DocumentPackage superDuperPackage = PackageBuilder.NewPackageNamed("DocumentVisibilityExample " + DateTime.Now)    .DescribedAs("This is a package created using the OneSpan Sign SDK")    .WithSigner(SignerBuilder.NewSignerWithEmail("mail31@example.com")        .WithCustomId(SIGNER1_ID)        .WithFirstName("John1")        .WithLastName("Smith1"))    .WithSigner(SignerBuilder.NewSignerWithEmail("mail32@example.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@example.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@example.com")            .OnPage(0)            .AtPosition(100, 100)))    .Build(); ``` ### Defining Document Visibility By Recipient You can configure each document so that only a specified signer can see that document.This can ensure that documents with sensitive information are viewed only by their intended recipients. After you've created your transaction, you will need to create your DocumentVisibility object using the OneSpan Sign DocumentVisibilityBuilder.Then you would set the visibility for each document using the custom ids set in the previous section.For example, withId(DOC1_ID). ```csharp Silanis.ESL.SDK.DocumentVisibility visibility = DocumentVisibilityBuilder.NewDocumentVisibility()    .AddConfiguration(        DocumentVisibilityConfigurationBuilder.NewDocumentVisibilityConfiguration(DOC1_ID)            .WithSignerIds(signerIdsList1)    )    .AddConfiguration(        DocumentVisibilityConfigurationBuilder.NewDocumentVisibilityConfiguration(DOC2_ID)            .WithSignerIds(signerIdsList2)    )    .Build(); ``` You can also configure document visibility based on specific signers: ```csharp 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(); ``` #### Retrieving a List of Signers Per Document Once you have set these configurations, you can then retrieve a list of signers who can view a document: ```csharp IList signersForDocument1 = eslClient.GetSigners(packageId, DOC1_ID); ``` Similarly, you can retrieve a list of documents for which a signer can view: ```csharp IList documentsForSigner1 = eslClient.GetDocuments(packageId, SIGNER1_ID); ``` ### Setting Visibility and Sending the Transaction Finally, you set the visibility of your documents and send your transaction using the OneSpan Sign client: ```csharp eslClient.ConfigureDocumentVisibility(packageId, visibility); eslClient.SendPackage(packageId); ``` ### Results Each recipient will only see the document assigned to them. ## REST API To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/set-document-visibility-java-sdk/) site. You can also see this feature in our [Interactive Demo.](https://secure.onespan.com/interactive-demo.html) During a [Signer Experience](/v1/docs/using-the-signer-experience), by default all recipients can view all documents in a transaction. However, you can configure your transactions so that certain documents can only be seen by specific recipients. 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. By default, adding a recipient to a transaction will give that recipient visibility to all documents. As a best practice, we recommend that you set document visibility after all documents and recipients have been added to the transaction. If you need to add a recipient after you have set document visibility, be sure to verify the document visibility of the recipient you have just added. ### Defining Document Signing By Recipient For this example, a transaction is setup such that Signer1 is only required to sign Document 1 and Signer2 is only required to sign Document 2, as shown below: #### HTTP Request ```http POST /api/packages ``` #### HTTP Headers ```http Accept: application/json   Content-Type: multipart/form-data   Authorization: Basic api_key ``` #### Request Payload ```json ------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": "DocumentA"        },        {            "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": "DocumentB",            "pages": []        }    ],    "name": "DocumentVisibilityExample REST API",    "roles": [        {            "id": "Signer1",            "index": 0,            "name": "Signer1",            "signers": [                {                    "email": "mail31@example.com",                    "firstName": "John1",                    "id": "Signer1",                    "lastName": "Smith1"                }            ]        },        {            "id": "Signer2",            "index": 0,            "name": "Signer2",            "signers": [                {                    "email": "mail32@example.com",                    "firstName": "John2",                    "id": "Signer2",                    "lastName": "Smith2"                }            ]        }    ],    "type": "PACKAGE",    "visibility": "ACCOUNT" } ------WebKitFormBoundary1bNO60n7FqP5WO4t-- ``` For a complete description of each field, see the Request Payload table below. #### Response Payload ```json {    "id": "9sKhW-h-qS9m6Ho3zRv3n2a-rkI=" } ``` ### Defining Document Visibility By Recipient You can configure each document so that only a specified signer can see that document.This can ensure that documents with sensitive information are viewed only by their intended recipients. 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 ```http Accept: application/json   Content-Type: application/json   Authorization: Basic api_key ``` ```json {  "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` ### Setting Visibility and Sending the Transaction Finally, you set the visibility of your documents and send your transaction using the OneSpan Sign client: ```json {  "status": "SENT" } ``` ### Results Each recipient will only see the document assigned to them. **Request Payload Table** | Property | Type | Editable | Required | Default | Sample Values | | --- | --- | --- | --- | --- | --- | | 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@example.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 | ## APEX SDK To download the full code sample see our [](https://community.onespan.com/documentation/onespan-sign/codeshare/document-operations-example-java-sdk/)[Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/set-document-visibility-apex-sdk/) site. You can also see this feature in our [Interactive Demo.](https://secure.onespan.com/interactive-demo.html) During a [Signer Experience](/v1/docs/using-the-signer-experience), by default all recipients can view all documents in a transaction. However, you can configure your transactions so that certain documents can only be seen by specific recipients. 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. By default, adding a recipient to a transaction will give that recipient visibility to all documents. As a best practice, we recommend that you set document visibility after all documents and recipients have been added to the transaction. If you need to add a recipient after you have set document visibility, be sure to verify the document visibility of the recipient you have just added. ### Defining Document Signing By Recipient For this example, a transaction is setup such that Signer1 is only required to sign Document 1 and Signer2 is only required to sign Document 2, as shown below: ```plaintext 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', 'signer1@example.com', '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', 'signer2@example.com', 'Applicant', 'ABC Company'); role2.id = roleId2; role2.name = roleId2; pkg.roles = new List{role1, role2}; // add role // Prepare Documents Blob // use single document twice, just for test String document1Name = 'documentA'; String document2Name = 'documentB'; StaticResource sr = [SELECT Id, Body FROM StaticResource WHERE Name = 'testdoc1' LIMIT 1]; Map documentBlobMap = new Map(); 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{document1, document2}; // add document // Send package One Step String packageId = sdk.createPackage(pkg, documentBlobMap); System.debug('PackageId: ' + packageId); ``` ### Defining Document Visibility By Recipient You can configure each document so that only a specified signer can see that document.This can ensure that documents with sensitive information are viewed only by their intended recipients. After you have created your transaction, you will need to create your DocumentVisibility object and add configurations for the visibility of each using the Role IDs set in the previous section.For example, role1.id = roleId1. ```plaintext // Configure documentVisibility DocumentVisibility documentVisibility = new DocumentVisibility()    .addConfiguration(new DocumentVisibilityConfiguration('document1')        .addRole('Signer1'))    .addConfiguration(new DocumentVisibilityConfiguration('document2')        .addRole('Signer2')); ``` #### Retrieving a List of Signers Per Document Once you have set these configurations, you can then retrieve a list of signers who can view a document: ```plaintext public List getSigners(String packageId, String documentId) {    // Initialize the list to hold the roles    List signers = new List();    // Fetch the package using the packageId    ESignLiveAPIObjects.Package_x pkg = sdk.getPackage(packageId);    // Iterate through the roles in the package    for (ESignLiveAPIObjects.Role role : pkg.roles) {        // Check if the role is associated with the specified document        for (ESignLiveAPIObjects.Document doc : role.documents) {            if (doc.id == documentId) {                signers.add(role);                break;            }        }    }    return signers; } ``` Similarly, you can retrieve a list of documents for which a signer can view: ```plaintext public List getDocuments(String packageId, String roleId) {    // Initialize the list to hold the documents    List documents = new List();    // Fetch the package using the packageId    ESignLiveAPIObjects.Package_x pkg = sdk.getPackage(packageId);    // Iterate through the roles in the package    for (ESignLiveAPIObjects.Role role : pkg.roles) {        // Check if the role matches the specified roleId        if (role.id == roleId) {            // Add all documents associated with the role to the list            documents.addAll(role.documents);            break;        }    }    return documents; } ``` ### Setting Visibility and Sending the Transaction Finally, you set the visibility of your documents and send your transaction using the OneSpan Sign client: ```plaintext // Configure document visibility configureDocumentVisibility(packageId, documentVisibility); // Set the package status to SENT sdk.setStatus(packageId, ESignLiveAPIObjects.PackageStatus.SENT); ``` ### Results Each recipient will only see the document assigned to them.