--- title: "Managing Document Layouts" slug: "managing-document-layouts" updated: 2025-07-02T18:23:55Z published: 2025-07-02T18:23:55Z canonical: "docs.onespan.com/managing-document-layouts" --- > ## 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. # Managing Document Layouts [Java SDK](/v1/docs/managing-document-layouts#java-sdk) [.NET SDK](/v1/docs/managing-document-layouts#net-sdk) [REST API](/v1/docs/managing-document-layouts#rest-api) [APEX SDK](/v1/docs/managing-document-layouts#apex-sdk) ## Java SDK To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/creating-layouts-java-sdk/) site. Templates and Layouts fulfill the same goal of automating the e-signature process by shortening the time it takes to send documents that include several signature blocks and data fields. Templates are ideal to use at the transaction level – you can pre-define your signers, documents, signature locations and e-signature workflows to streamline the e-signature process. A Layout on the other hand, is a type of template that allows you to create pre-defined locations for your signature blocks and data fields within a document. It acts like a ‘marker’ where signature blocks and data fields will sit in the document. Layouts are helpful for users who frequently send forms that may be slightly different per recipient but signature blocks and data fields remain in the same location throughout the document. What’s more, you can use multiple Layouts per document, and apply them to individual pages within your transaction. ### Finding your Layouts in the UI When editing documents, you will find all of your saved layouts under the toolbar, as shown below. Note that layouts can only be applied when transaction are in a Draft status. ![](https://cdn.document360.io/038f59a7-abd0-4c14-9de7-3434d28b49fd/Images/Documentation/layout_1.png) ### Creating a New Layout In this example, document extraction is used to extract the fields and save them as a layout. For more information, see [Document Extraction](/v1/docs/document-extraction). After creating your transaction, use the OneSpan Sign LayoutService to create a layout from your transaction. It is important to note that the Layout ID is required to apply layouts to documents. The following code will do this: ```java String layoutId = eslClient.getLayoutService().createLayout(myPackage);   System.out.println(layoutId); ``` ### Retrieving a Layout The following code will retrieve a layout. The first step is to retrieve the layouts from the first page. In this example, five layouts are retrieved, but you can set this to any number. ```java List layouts = eslClient.getLayoutService().getLayouts(Direction.DESCENDING, new PageRequest(i, 5)); while (!layouts.isEmpty()) {    // Your logic here } ``` Next, you will create your iterator object. This will enable you to iterate through your list of layouts. ```java Iterator index = layouts.iterator(); while (index.hasNext()) {    DocumentPackage documentPackage = index.next();    // Your logic here } ``` Then, retrieve your layout name and id. ```java while (index.hasNext()) {    DocumentPackage myLayout = index.next();    System.out.println(myLayout.getName() + " " + myLayout.getId());    i++; } ``` Use the following code to retrieve layouts from each page in the transaction, repeating for every page: ```java layouts = eslClient.getLayoutService().getLayouts(Direction.DESCENDING, new PageRequest(i, 5)); ``` ### Applying Layouts Use the OneSpan Sign LayoutService to apply layouts, by either Layout ID, or by name. ```java eslClient.getLayoutService().applyLayout(packageId, "documentId", "layoutId");   eslClient.getLayoutService().applyLayoutByName(packageId, "documentId", "layoutName");   ``` ### Deleting a Layout To delete a layout, use the PackageService(). The following code will do this: ```java eslClient.getPackageService().deletePackage(new PackageId("layoutId")); ``` ### Results After running your code, you will see a list of all your layouts under the toolbar. Once your layout is saved, you can then apply it on subsequent documents. ## .NET SDK To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/creating-layouts-net-sdk/) site. Templates and Layouts fulfill the same goal of automating the e-signature process by shortening the time it takes to send documents that include several signature blocks and data fields. Templates are ideal to use at the transaction level – you can pre-define your signers, documents, signature locations and e-signature workflows to streamline the e-signature process. A Layout on the other hand, is a type of template that allows you to create pre-defined locations for your signature blocks and data fields within a document. It acts like a ‘marker’ where signature blocks and data fields will sit in the document. Layouts are helpful for users who frequently send forms that may be slightly different per recipient but signature blocks and data fields remain in the same location throughout the document. What’s more, you can use multiple Layouts per document, and apply them to individual pages within your transaction. ### Finding your Layouts in the UI When editing documents, you will find all of your saved layouts under the toolbar, as shown below. Note that layouts can only be applied when transaction are in a Draft status. ![](https://cdn.document360.io/038f59a7-abd0-4c14-9de7-3434d28b49fd/Images/Documentation/layout_1-1.png) ### Creating a New Layout In this example, document extraction is used to extract the fields and save them as a layout. For more information, see [Document Extraction](/v1/docs/document-extraction). After creating your transaction, use the OneSpan Sign LayoutService to create a layout from your transaction. It is important to note that the Layout ID is required to apply layouts to documents. The following code will do this: ```csharp string layoutId = eslClient.LayoutService.CreateLayout(packageFromLayout); Debug.WriteLine(layoutId); ``` ### Retrieving a Layout The following code will retrieve a layout. The first step is to retrieve the layouts from the first page. In this example, five layouts are retrieved, but you can set this to any number. ```csharp List layouts = eslClient.getLayoutService().getLayouts(Direction.DESCENDING, new PageRequest(i, 5)); while (!layouts.isEmpty()) {    // Your code here } ``` Next, you will create your iterator object. This will enable you to iterate through your list of layouts. ```csharp var index = layouts.GetEnumerator(); while (index.MoveNext()) {    DocumentPackage myLayout = index.Current;    // Your code here } ``` Then, retrieve your layout name and id. ```csharp DocumentPackage myLayout = index.Current; Console.WriteLine($"{myLayout.getName()} {myLayout.getId()}"); i++; } ``` Use the following code to retrieve layouts from each page in the transaction, repeating for every page: ### Applying Layouts Use the OneSpan Sign LayoutService to apply layouts, by either Layout ID, or by name. ```csharp eslClient.getLayoutService().applyLayout(packageId, "documentId", "layoutId");   eslClient.getLayoutService().applyLayoutByName(packageId, "documentId", "layoutName");   ``` ### Deleting a Layout To delete a layout, use the PackageService(). The following code will do this: ```csharp eslClient.PackageService.DeletePackage(new PackageId("layoutId")); ``` ### Results After running your code, you will see a list of all your layouts under the toolbar. Once your layout is saved, you can then apply it on subsequent documents. ## REST API To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/creating-layouts-rest-api/) site. Templates and Layouts fulfill the same goal of automating the e-signature process by shortening the time it takes to send documents that include several signature blocks and data fields. Templates are ideal to use at the transaction level – you can pre-define your signers, documents, signature locations and e-signature workflows to streamline the e-signature process. A Layout on the other hand, is a type of template that allows you to create pre-defined locations for your signature blocks and data fields within a document. It acts like a ‘marker’ where signature blocks and data fields will sit in the document. Layouts are helpful for users who frequently send forms that may be slightly different per recipient but signature blocks and data fields remain in the same location throughout the document. What’s more, you can use multiple Layouts per document, and apply them to individual pages within your transaction. ### Finding your Layouts in the UI When editing documents, you will find all of your saved layouts under the toolbar, as shown below. Note that layouts can only be applied when transaction are in a Draft status. ![](https://cdn.document360.io/038f59a7-abd0-4c14-9de7-3434d28b49fd/Images/Documentation/layout_1(1).png) ### Creating a New Layout In this example, document extraction is used to extract the fields and save them as a layout. For more information, see [Document Extraction](/v1/docs/document-extraction). Use the following code to create a layout from a document: #### HTTP Request ```http POST /api/layouts ``` #### HTTP Headers ```http Accept: application/json   Content-Type: application/json   Authorization: Basic api_key ``` #### Request Payload ```json {   "name":"Layout 02",   "type":"LAYOUT",   "id":"packageId",   "visibility":"SENDER",   "documents":[   {   "id":"documentId"   }   ]   } ``` For a complete description of each field, see the Request Payload table below. #### Response Payload ```json {    "name": "Layout 02",    "type": "LAYOUT",    "id": "packageId",    "visibility": "SENDER",    "documents": [        {            "id": "documentId"        }    ] } ``` It is important to note that theLayout ID is required to apply layouts to documents. ### Retrieving a Layout You can also retrieve all of your saved layouts. The following code will do this: #### HTTP Request ```http GET /api/layouts?from={fromPage}&to={toPage} ``` #### HTTP Headers ```http Accept: application/json   Content-Type: application/json   Authorization: Basic api_key ``` #### Response Payload ```json {    "results": [        {            "roles": [                {                    "id": "564fd009-7673-4a5f-9314-5c5b3d5f3869",                    "data": null,                    "emailMessage": {                        "content": ""                    },                    "attachmentRequirements": [],                    "locked": false,                    "reassign": false,                    "specialTypes": [],                    "type": "SIGNER",                    "index": 0,                    "signers": [],                    "name": "Signer2"                },                {                    "id": "a3bfe56c-da0a-4ff0-bfef-efe55fd28a0c",                    "data": null,                    "emailMessage": {                        "content": ""                    },                    "attachmentRequirements": [],                    "locked": false,                    "reassign": false,                    "specialTypes": [],                    "type": "SIGNER",                    "index": 0,                    "signers": [],                    "name": "Signer1"                },                {                    "id": "bjyxbrypiHw6",                    "data": null,                    "emailMessage": null,                    "attachmentRequirements": [],                    "locked": false,                    "reassign": false,                    "specialTypes": [],                    "type": "SENDER",                    "index": 0,                    "signers": [                        {                            "group": null,                            "language": "en",                            "signature": {                                "handdrawn": "AQAAADJI+a4cnf0t3Dlf0GqWJceCA+4AAwADAN8BAAADAAAAggPuAOgAAAACfyxAUkAlQCdAOUA6QDtAHEAtQBtACkAJQBVAFBIyfkA0QBVABkAYQCpAHEAtQC9ALkAtQDxAO0A6QEhAN0AlQCQyTjZAgEBwQIBAoFDSUOFQ8lDiUNJQ0lCiQHBAUCIXGVBSUCVQN1BJUDpQXVA9UE5QLlAuUDpQOVAkm1BhQLZAd0B7QFpAXUBPQTBAHkAdQAtAB2AmYBRgQmCAcJVwmHC5Mh42QFBAkECAQKBAsEDAQNBQ8VDyUPJQ81DTULRQg1ByUEGeIgQ6QDhAJ0AmQCZAFItwbHBtMhdBUCafUGJQcVCSUJFQoUDAQKBAsECBQHNAdEBEQDRABkAFYCdgR2BXYHhgd2CIYIVgdmBDYEJAUUBwQIFAkECwQLBA0EDAQLBAoEBwQGASG0xAc0BnQEhASkArQBxADEAKQAlABkAFMkVKUENQUVBBUGFQYVCRUKJQsVDCUNJQsUDQQKBAkEBwQFJAREAlIllVUHFQUVByUKFQslDSUNJQ9VDlUPZQ1lDWUKVQZVBEUCQyCxivr2BjYGRgdGB1YHZgZmBWYEdgRkAFQClAREBjQJNAk0CzQKNAs0CjQJNAQo9gRWBjYJNgs2DCYNRg1GCkYKRgY2Bkrg==",                                "textual": null                            },                            "id": "8ceWLxUo1Gg1",                            "delivery": {                                "provider": false,                                "email": true,                                "download": true                            },                            "knowledgeBasedAuthentication": null,                            "auth": {                                "scheme": "NONE",                                "challenges": []                            },                            "data": null,                            "title": "Silanis",                            "external": null,                            "updated": "2017-11-14T20:31:34Z",                            "phone": "",                            "professionalIdentityFields": [],                            "userCustomFields": [],                            "company": "Silanis",                            "email": "haris.haidary@gmail.com",                            "firstName": "Haris",                            "lastName": "Haidary",                            "name": "",                            "address": null,                            "created": "2017-11-14T20:31:34Z",                            "specialTypes": []                        }                    ],                    "name": "Owner"                }            ],            "status": "DRAFT",            "description": "",            "language": "en",            "id": "rr8lE3YwF-LaCNxSjntn2udM8hc=",    "data": {                "origin": "api"            },            "autocomplete": true,            "documents": [                {                    "status": "",                    "description": "",                    "id": "dfe8ac46006b31f6",                    "signedHash": null,                    "extractionTypes": [],                    "signerVerificationToken": null,                    "data": {},                    "approvals": [                        {                            "id": "akmT717La0YP",                            "role": "a3bfe56c-da0a-4ff0-bfef-efe55fd28a0c",                            "data": null,                            "signed": null,                            "accepted": null,                            "fields": [                                {                                    "binding": null,                                    "validation": null,                                    "id": "AooaSEwkp0oG",                                    "page": 0,                                    "data": null,                                    "subtype": "FULLNAME",                                    "height": 39.99995853281021,                                    "extract": false,                                    "width": 199.99979266405106,                                    "extractAnchor": null,                                    "left": 94.00000655210017,                                    "top": 752.0005724167823,                                    "type": "SIGNATURE",                                    "value": "",                                    "name": "AooaSEwkp0oG"                                }                            ],                            "name": ""                        },                        {                            "id": "anR9R3fLlQYE",                            "role": "564fd009-7673-4a5f-9314-5c5b3d5f3869",                            "data": null,                            "signed": null,                            "accepted": null,                            "fields": [                                {                                    "binding": null,                                    "validation": null,                                    "id": "AvqDbyKBeIoX",                                    "page": 0,                                    "data": null,                                    "subtype": "FULLNAME",                                    "height": 39.99995853281021,                                    "extract": false,                                    "width": 199.99979266405106,                                    "extractAnchor": null,                                    "left": 94.00000655210017,                                    "top": 832.999669445753,                                    "type": "SIGNATURE",                                    "value": "",                                    "name": "AvqDbyKBeIoX"                                }                            ],                            "name": ""                        }                    ],                    "pages": [                        {                            "id": "dfe8ac46006b31f6_0_-1_1.png",                            "height": 1030,                            "width": 796,                            "left": 0,                            "top": 0,                            "version": 0,                            "index": 0                        }                    ],                    "external": null,                    "extract": false,                    "fields": [],                    "index": 0,                    "name": "cleaning_contract",                    "size": 197171                }            ],            "sender": {                "status": "ACTIVE",                "language": "en",                "signature": {                    "handdrawn": "AQAAADJI+a4cnf0t3Dlf0GqWJceCA+4AAwADAN8BAAADAAAAggPuAOgAAAACfyxAUkAlQCdAOUA6QDtAHEAtQBtACkAJQBVAFBIyfkA0QBVABkAYQCpAHEAtQC9ALkAtQDxAO0A6QEhAN0AlQCQyTjZAgEBwQIBAoFDSUOFQ8lDiUNJQ0lCiQHBAUCIXGVBSUCVQN1BJUDpQXVA9UE5QLlAuUDpQOVAkm1BhQLZAd0B7QFpAXUBPQTBAHkAdQAtAB2AmYBRgQmCAcJVwmHC5Mh42QFBAkECAQKBAsEDAQNBQ8VDyUPJQ81DTULRQg1ByUEGeIgQ6QDhAJ0AmQCZAFItwbHBtMhdBUCafUGJQcVCSUJFQoUDAQKBAsECBQHNAdEBEQDRABkAFYCdgR2BXYHhgd2CIYIVgdmBDYEJAUUBwQIFAkECwQLBA0EDAQLBAoEBwQGASG0xAc0BnQEhASkArQBxADE ``` Similarly, to apply a layout, you will need the packageId, documentId, and layoutId/layoutName, to make your request: If using LayoutID: #### HTTP Request ```http POST /api/packages/{packageId}/documents/{documentId}/layout?layoutId={layoutId} ``` #### HTTP Headers ```http Accept: application/json   Content-Type: application/json   Authorization: Basic api_key ``` If using layout name: #### HTTP Request ```http POST /api/packages/{packageId}/documents/{documentId}/layout?layoutName={layoutName} ``` #### HTTP Headers ```http Accept: application/json   Content-Type: application/json   Authorization: Basic api_key ``` ### Deleting a Layout To delete a layout use the following code: #### HTTP Request ```http DELETE /api/packages/{layoutId} ``` #### HTTP Headers ```http Accept: application/json   Content-Type: application/json   Authorization: Basic api_key ``` ### Results After running your code, you will see a list of all your layouts under the toolbar. Once your layout is saved, you can then apply it on subsequent documents. ### Request Payload Table | Property | Type | Editable | Required | Default | Sample Values | | --- | --- | --- | --- | --- | --- | | type | string | Yes | No | PACKAGE | PACKAGE / TEMPLATE / LAYOUT | | name | string | Yes | Yes | n/a | Layout Example | | id | string | Yes | No | n/a | rr8lE3YwF-LaCNxSjntn2udM8hc= | | visibility | string | Yes | No | ACCOUNT | ACCOUNT / SENDER | | documents | | | | | | | id | string | Yes | No | n/a | sample-contract | ## APEX SDK To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/creating-layouts-apex-sdk/) site. Templates and Layouts fulfill the same goal of automating the e-signature process by shortening the time it takes to send documents that include several signature blocks and data fields. Templates are ideal to use at the transaction level – you can pre-define your signers, documents, signature locations and e-signature workflows to streamline the e-signature process. A Layout on the other hand, is a type of template that allows you to create pre-defined locations for your signature blocks and data fields within a document. It acts like a ‘marker’ where signature blocks and data fields will sit in the document. Layouts are helpful for users who frequently send forms that may be slightly different per recipient but signature blocks and data fields remain in the same location throughout the document. What’s more, you can use multiple Layouts per document, and apply them to individual pages within your transaction. ### Finding your Layouts in the UI When editing documents, you will find all of your saved layouts under the toolbar, as shown below. Note that layouts can only be applied when transaction are in a Draft status. ![](https://cdn.document360.io/038f59a7-abd0-4c14-9de7-3434d28b49fd/Images/Documentation/layout_1-1(2).png) ### Creating a New Layout In this example, document extraction is used to extract the fields and save them as a layout. For more information, see [Document Extraction](/v1/docs/document-extraction). After creating your package, use the following encapsulated function to create your layout from an existing package. ```plaintext public ESignLiveAPIObjects.package_x createLayout(String packageId, String documentId, String layoutName, TestLayout.Visibility visibility) {    // Your code here } ``` It is important to note that the Layout ID is required to apply layouts to documents. The following code will do this: ```plaintext ESignLiveAPIObjects.package_x createLayout = createLayout(pkgId, 'Sample_Document_Extraction', 'Layout Created from Apex SDK', TestLayout.Visibility.ACCOUNT); String layoutId = createLayout.id; ``` ### Retrieving a Layout The following code will retrieve a layout. ```plaintext // Retrieve all layouts Integer totalCount = getLayoutCount(); Integer index = 0; System.debug('Total layout count: ' + totalCount); while (index < totalCount) {    List layouts = getLayouts(index, index + 49);    for (ESignLiveAPIObjects.package_x layout : layouts) {        System.debug('Layout name: ' + layout.name + ' with id: ' + layout.id);    }    index += 50; } ``` Similarly, to creating layouts, use the following encapsulated functions to apply a layout to your document. This code will pass in your layout ID, target package ID and target Document ID. ```plaintext  public void applyLayout(String packageId, String documentId, String layoutId) ``` ### Deleting a Layout To delete a layout, use the following code: ```plaintext  //delete layout   ESignLiveSDK sdk = new ESignLiveSDK();   sdk.deletePackage(layoutId); ``` ### Results After running your code, you will see a list of all your layouts under the toolbar. Once your layout is saved, you can then apply it on subsequent documents.