--- title: "Adding Fields" slug: "adding-fields" updated: 2024-10-15T13:12:38Z published: 2024-10-15T13:12:38Z canonical: "docs.onespan.com/adding-fields" --- > ## 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. # Adding Fields [Java SDK](/v1/docs/adding-fields#java-sdk) [.NET SDK](/v1/docs/adding-fields#net-sdk) [REST API](/v1/docs/adding-fields#rest-api) [APEX SDK](/v1/docs/adding-fields#apex-sdk) ## Java SDK To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/fields-example-java-sdk/) site. Fields enable the placement of additional data in a document at the time of signing. Like signature fields, non-signature fields can be placed anywhere inside a document. Nonetheless, each field is linked to a particular signature. Only the signer of that signature can assign or change the field's value. Once the signature is signed, however, the value of the field cannot be changed by anyone. You cannot add fields to: (1) documents that are Accept Only; (2) the Electronic Consent form; (3) documents in an accessible transaction. ### Adding a Field to a Document To add a field on a document, you will first need to create your Field object using the OneSpan Sign FieldBuilder. The following code will do this: ```java Field field = FieldBuilder.label()    .withId(new FieldId("myLabelField"))    .withValue("Example label field value")    .atPosition(100, 200)    .onPage(0)    .build(); ``` Then, using the OneSpan SignApprovalService, add your field to your document. Use the Field object, PackageID, SignatureID, and documentID as parameters. The following code will do this: ```java String labelFieldId = client.getApprovalService().addField(    packageId,    "sample-contract",    signatureid,    field ); ``` ### Updating a Field in a Document It is important to note that when updating a field, your new Field object must have the same id as the field you want to update. The following code will do this: ```java Field updatedField = FieldBuilder.signatureDate()    .onPage(0)    .withId(new FieldId("myLabelField"))    .atPosition(100, 200)    .build(); client.getApprovalService().updateField(    packageId,    "sample-contract",    new SignatureId("ExampleSignatureId"),    updatedField ); ``` ### Deleting a Field in a Document To delete a field, use the OneSpan SignApprovalService. Use the Field object, PackageID, SignatureID, and documentID as parameters. The following code will do this: ```java client.getApprovalService().deleteField(    packageId,    "sample-contract",    new SignatureId("ExampleSignatureId"),    new FieldId("myLabelField") ); ``` ### Results Once you have run your code, your fields will appear in your transaction's documents. ## .NET SDK To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/fields-example-net-sdk/) site. Fields enable the placement of additional data in a document at the time of signing. Like signature fields, non-signature fields can be placed anywhere inside a document. Nonetheless, each field is linked to a particular signature. Only the signer of that signature can assign or change the field's value. Once the signature is signed, however, the value of the field cannot be changed by anyone. You cannot add fields to: (1) documents that are Accept Only; (2) the Electronic Consent form; (3) documents in an accessible transaction. ### Adding a Field to a Document To add a field on a document, you will first need to create your Field object using the OneSpan Sign FieldBuilder, as shown below. ```csharp Field field = FieldBuilder.Label()    .WithId("myLabelField")    .WithValue("Example label field value")    .AtPosition(100, 200)    .OnPage(0)    .Build(); ``` Then, using the OneSpan SignApprovalService, add your field to your document. Use the Field object, PackageID, SignatureID, and documentID as parameters. The following code will do this: ```csharp string labelFieldId = client.ApprovalService.AddField(    packageId,    "sample-contract",    signatureid,    field ); ``` ### Updating a Field in a Document It is important to note that when updating a field, your new Field object must have the same id as the field you want to update. The following code will do this: ```csharp Field updatedField = FieldBuilder.SignatureDate()    .OnPage(0)    .WithId("myLabelField")    .AtPosition(100, 200)    .Build(); client.ApprovalService.ModifyField(    packageId,    "sample-contract",    new SignatureId("ExampleSignatureId"),    updatedField ); ``` ### Deleting a Field in a Document To delete a field, use the OneSpan SignApprovalService. Use the Field object, PackageID, SignatureID, and documentID as parameters. The following code will do this: ```csharp client.ApprovalService.DeleteField(    packageId,    "sample-contract",    new SignatureId("ExampleSignatureId"),    "myLabelField" ); ``` ### Results Once you have run your code, your fields will appear in your transaction's documents. ## REST API To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/fields-example-rest-api/) site. Fields enable the placement of additional data in a document at the time of signing. Like signature fields, non-signature fields can be placed anywhere inside a document. Nonetheless, each field is linked to a particular signature. Only the signer of that signature can assign or change the field's value. Once the signature is signed, however, the value of the field cannot be changed by anyone. You cannot add fields to: (1) documents that are Accept Only; (2) the Electronic Consent form; (3) documents in an accessible transaction. ### Adding a Field to a Document The sample request below shows you how to add a field to an existing document: #### HTTP Request ```http POST /api/packages/{packageId}/documents/{documentId}/approvals/{approvalId}/fields ``` #### HTTP Headers ```http Accept: application/json; esl-api-version=11.21   Content-Type: application/json   Authorization: Basic api_key ``` #### Request Payload ```json {    "name": "Signer Name",    "top": 500,    "left": 300,    "width": 100,    "height": 30,    "page": 0,    "type": "INPUT",    "value": null,    "binding": "{signer.name}",    "subtype": "LABEL" } ``` #### Response Payload ```json {    "binding": "{signer.name}",    "validation": null,    "id": "BsZv3XvmpsMH",    "page": 0,    "data": null,    "subtype": "LABEL",    "top": 500,    "height": 30,    "extractAnchor": null,    "width": 100,    "extract": false,    "left": 300,    "type": "INPUT",    "value": "{signer.name}",    "name": "Signer Name" } ``` ### Updating a Field in a Document It is important to note that when updating a field, your new Field object must have the same id as the field you want to update. To update a field, you will need to make a PUT request to: ```plaintext https://sandbox.esignlive.com/api/packages/{packageId}/documents/{documentId}/approvals/{signatureId}/fields/{fieldId} ``` With the updated field parameters: ```json {    "id": "myLabelField",    "top": 200,    "left": 100,    "width": 250,    "height": 50,    "page": 0,    "type": "INPUT",    "binding": "{approval.signed}",    "subtype": "LABEL" } ``` ### Deleting a Field in a Document Deleting a field is done by making a DELETE request to: ```plaintext https://sandbox.esignlive.com/api/packages/{packageId}/documents/{documentId}/approvals/{signatureId}/fields/{fieldId} ``` ### Results Once you have run your code, your fields will appear in your transaction's documents. ### Form-Building Fields The following describe the parameters and JSON code that can be used to add fields to a document. #### Signature Fields | **Field** | **Usage** | **JSON** | | --- | --- | --- | | Signature | Used to collect a signature from a recipient. | ```json { "type": "SIGNATURE", "subtype": "FULLNAME", "id": "signer1_signature1", "name": "signer1_signature1", "width": 185.5958549222798, "height": 41.24352331606218, "left": 305.2020725388601, "top": 357.5083117443869, "page": 0 } ``` | #### Input Fields | **Field** | **Usage** | **JSON** | | --- | --- | --- | | Text Field | This field accepts any text entered by the signer prior to signing. | ```json { "type": "INPUT", "subtype": "TEXTFIELD", "id": "signer1_textfield1", "name": "signer1_textfield1", "validation": { "required": false, "maxLength": null, "errorMessage": "", "minLength": null, "pattern": "" }, "value": "default value", "width": 185.5958549222798, "height": 41.24352331606218, "left": 305.2020725388601, "top": 425, "page": 0 } ``` | | Text Area | This is a multi-line area that accepts any text entered by the signer prior to signing. | ```json { "type": "INPUT", "subtype": "TEXTAREA", "id": "signer1_textarea1", "name": "signer1_textarea1", "validation": { "required": false, "maxLength": null, "errorMessage": "", "minLength": null, "pattern": "" }, "value": "line1\nline2\nline3", "width": 185.5958549222798, "height": 41.24352331606218, "left": 305.2020725388601, "top": 476, "page": 0 } ``` | | Checkbox (with checkbox group) | This is a check box that the signer can either select or clear. Use check boxes when you want to enable signers to choose more than one option in a list. Use Checkbox Group to place selected checkboxes in a group of associated boxes. If the sender sets any box in a group as required, then during signing the signer must select at least one member of the group. | ```json { "type": "INPUT", "subtype": "CHECKBOX", "id": "signer1_checkbox1", "name": "signer1_checkbox1", "validation": { "required": false, "group": "CheckboxGroup1", "minimumRequired": 1, "maximumRequired": null }, "value": "X", "tooltip": "field tooltip", "width": 20, "height": 20, "left": 453, "top": 789, "page": 0 } ``` | | Checkbox (without checkbox group) | | ```json { "type": "INPUT", "subtype": "CHECKBOX", "id": "signer1_checkbox2", "name": "signer1_checkbox2", "value": "X", "tooltip": "field tooltip", "width": 20, "height": 20, "left": 453, "top": 789, "page": 0 } ``` | | Radio | Radio buttons enable signers to select one of many predefined options. Use radio buttons when you want signers to choose only one option. Use Radio Group to place selected radio buttons in a group of associated buttons. You can identify one button in the group as the Default, thus ensuring that it will be pre-selected. | ```json { "type": "INPUT", "subtype": "RADIO", "id": "signer1_radio1", "name": "signer1_radio1", "validation": { "required": true, "enum": [ "RadioGroup1" ] }, "value": "X", "tooltip": "field tooltip", "width": 18.0, "height": 18.0, "left": 389.0, "top": 785.0, "page": 0 } } ``` | | List | This is a drop-down list that offers recipients multiple predefined options. The signer can choose one option from the list. Once that option is selected, only that option is displayed, thus minimizing the amount of space this element occupies on the screen. | ```json { "type": "INPUT", "subtype": "LIST", "id": "signer1_list1", "name": "signer1_list1", "validation": { "required": false, "enum": [ "option1", "option2", "option3" ] }, "value": "option1", "tooltip": "field tooltip", "width": 249.0, "height": 55.0, "left": 274.0, "top": 813.0, "page": 0 } ``` | | Label | This is a read only label that will be stamped on the PDF. | ```json { "type": "INPUT", "subtype": "LABEL", "id": "signer1_label1", "name": "signer1_label1", "value": "label value", "width": 185.5958549222798, "height": 41.24352331606218, "left": 305.2020725388601, "top": 626, "page": 0 } ``` | #### Binding Fields | **Field** | **Usage** | **JSON** | | --- | --- | --- | | Signing Date | This autofield stamps the document with the date and time of the signature . | ```json { "type": "INPUT", "subtype": "LABEL", "id": "signer1_signingdate1", "name": "signer1_signingdate1", "binding": "{approval.signed}", "width": 185.5958549222798, "height": 41.24352331606218, "left": 305.2020725388601, "top": 357.5083117443869, "page": 0 } ``` | | Signer Name | This autofield stamps the document with the signer's name as it was entered on the transaction. | ```json { "type": "INPUT", "subtype": "LABEL", "id": "signer1_signername", "name": "signer1_signername", "binding": "{signer.name}", "width": 185.5958549222798, "height": 41.24352331606218, "left": 305.2020725388601, "top": 562, "page": 0 } ``` | | Signer Title | This autofield stamps the document with the title of the signer as it was entered on the transaction. | ```json { "type": "INPUT", "subtype": "LABEL", "id": "signer1_signertitle", "name": "signer1_signertitle", "binding": "{signer.title}", "width": 185.5958549222798, "height": 41.24352331606218, "left": 305.2020725388601, "top": 613, "page": 0 } ``` | | Signer Company | This autofield stamps the document with the name of the signer's company as it was entered on the transaction. | ```json { "type": "INPUT", "subtype": "LABEL", "id": "signer1_signercompany", "name": "signer1_signercompany", "binding": "{signer.company}", "width": 185.5958549222798, "height": 41.24352331606218, "left": 305.2020725388601, "top": 664, "page": 0 } ``` | #### **Imprint Fields** | **Field** | **Usage** | **JSON** | | --- | --- | --- | | Imprint Label | A type of field that can be placed on documents during the transaction creation, which is not tied to any signer or signature. This ensures that the information the sender places in these fields is visible to all recipients and remains unchanged throughout the signing process. | ```json { "type": "INPUT", "subtype": "LABEL", "id": "imprintlabel1", "name": "imprintlabel1", "value": "imprint field value", "width": 185.5958549222798, "height": 41.24352331606218, "left": 305.2020725388601, "top": 357.5083117443869, "page": 0 } ``` | | Document ID | The document identifier. | ```json { "type": "INPUT", "subtype": "LABEL", "id": "documentid1", "name": "documentid1", "binding": "{document.id}", "width": 185.5958549222798, "height": 41.24352331606218, "left": 305.2020725388601, "top": 409, "page": 0 } ``` | | Transaction ID | The transaction identifier. | ```json { "type": "INPUT", "subtype": "LABEL", "id": "transactionid1", "name": "transactionid1", "binding": "{transaction.id}", "width": 185.5958549222798, "height": 41.24352331606218, "left": 305.2020725388601, "top": 460, "page": 0 } ``` | ## APEX SDK To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/fields-example-apex-sdk/) site. Fields enable the placement of additional data in a document at the time of signing. Like signature fields, non-signature fields can be placed anywhere inside a document. Nonetheless, each field is linked to a particular signature. Only the signer of that signature can assign or change the field's value. Once the signature is signed, however, the value of the field cannot be changed by anyone. You cannot add fields to: (1) documents that are Accept Only; (2) the Electronic Consent form; (3) documents in an accessible transaction. ### Adding a Field to a Document To add a field on a document, you will first need to build your Field object as shown below. ```plaintext // Create field to an existing approval ESignLiveAPIObjects.Field label_field = new ESignLiveAPIObjects.Field(); label_field.id = 'label_field'; label_field.type = 'INPUT'; label_field.subtype = 'LABEL'; label_field.value = 'old label value'; label_field.page = 0; label_field.top = 100.0; label_field.left = 50.0; label_field.width = 150.0; label_field.height = 50.0; ``` Then, using the addField function, add your field to your document. Use the Field object, PackageID, ApprovalID, and documentID as parameters. The following code will do this: ```plaintext // String packageId, String documentId, String approvalId, ESignLiveAPIObjects.Field fieldToCreate String label_field_response = sdk.addField(    'yjn7R9GyKU_BRhUjvLrWFp5vUEA=',    'f3e381eec45b4df851bd28087ad12104c620814bccca6b76',    '8ELNXeOxMHsD',    label_field ); label_field = (ESignLiveAPIObjects.Field)JSON.deserialize(    label_field_response,    ESignLiveAPIObjects.Field.class ); ``` ### Updating a Field in a Document It is important to note that when updating a field, your new Field object must have the same id as the field you want to update. The following code will do this: ```plaintext // Update field // String packageId, String documentId, String approvalId, String fieldId, ESignLiveAPIObjects.Field fieldToUpdate label_field.value = 'changed label value'; sdk.updateField(    'yjn7R9GyKU_BRhUjvLrWFp5vUEA=',    'f3e381eec45b4df851bd28087ad12104c620814bccca6b76',    '8ELNXeOxMHsD',    label_field.id,    label_field ); ``` ### Deleting a Field in a Document To delete a field, use the OneSpan SignApprovalService. Use the Field object, PackageID, SignatureID, and documentID as parameters. The following code will do this: ```plaintext // Delete field // String packageId, String documentId, String approvalId, String fieldId sdk.deleteField(    'yjn7R9GyKU_BRhUjvLrWFp5vUEA=',    'f3e381eec45b4df851bd28087ad12104c620814bccca6b76',    '8ELNXeOxMHsD',    label_field.id ); ``` ### Results Once you have run your code, your fields will appear in your transaction's documents.