--- title: "Managing Custom Fields" slug: "managing-custom-fields" updated: 2025-07-02T18:53:01Z published: 2025-07-02T18:53:01Z canonical: "docs.onespan.com/managing-custom-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. # Managing Custom Fields [Java SDK](/v1/docs/managing-custom-fields#java-sdk) [.NET SDK](/v1/docs/managing-custom-fields#net-sdk) [REST API](/v1/docs/managing-custom-fields#rest-api) ## Java SDK To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/creating-custom-fields-java-sdk/) site. A Custom Field is one that, at the time of signing, is automatically populated with data that is specific to the signer. For instance, a signer might have an Agent Number, and that number may need to appear in the final document next to their signature. By using a custom field, the signer can specify their Agent Number, and that number will automatically appear in any other field that has been configured to receive it. The Custom Fields page enables you to manage the custom fields in your account. This functionality is available only if custom fields are enabled at the account level. Please contact our [Support Team](https://www.onespan.com/support) to have them enabled. ### Creating a Custom Field To create a custom field, you will need to build a CustomField object. Every custom field you create is identified by the unique id you set during this process. The following code will do this: > Creating another custom field with the same id will overwrite the original custom field. Also, note that every custom field you create is done so for the entire account. ```java String customFieldId1 = "policy_number_id"; CustomField customField = CustomFieldBuilder.customFieldWithId(customFieldId1)    .withDefaultValue("123-456-789-0")    .withTranslation(newTranslation("en")        .withName("Policy Number")        .withDescription("Car Insurance Policy Number."))    .build(); eslClient.getCustomFieldService().createCustomField(customField); ``` The withDefaultValue() is the value that appears after your signer has signed the document. This method is required when creating a custom field. Custom fields also contain a collection of translations which are used when displaying the custom field to account members. This tip is for accounts that support multiple languages. As a best practice, every custom field you need should be replicated for every language supported in your account. The system will only display the custom field in the language selected by the active user. If a custom field is not mapped to a language, it will default to English, regardless of the language selected by the active user. At least one translation is required when building your CustomField object. Use the OneSpan Sign CustomFieldService to create your custom field. ### Retrieving Custom Fields You can retrieve your custom fields with the OneSpan Sign CustomFieldService. You can either retrieve all custom fields, which are returned to you as a list, or retrieve a specific one using the custom field id. The following code will do this: ```java // Get the entire list of custom fields from the account List retrieveCustomFieldList1 = eslClient.getCustomFieldService().getCustomFields(Direction.ASCENDING); // Get the first custom field from the account CustomField retrieveCustomField = eslClient.getCustomFieldService().getCustomField(customFieldId1); ``` ### Deleting a Custom Field Deleting a custom field from your account is also done with the OneSpan Sign CustomFieldService. The following code will do this: ```java // Delete the second custom field from the account eslClient.getCustomFieldService().deleteCustomField(customFieldId1); ``` ### Editing a Signature Block to Add Custom Fields To edit signature block to add custom codes, use the following code. In this example, text anchors are used to position both signature and custom fields. For more information, see [Text Anchors](/v1/docs/managing-custom-fields). ```java .withSignature(signatureFor(email1)    .withPositionAnchor(TextAnchorBuilder.newTextAnchor("Client Signature")        .atPosition(TextAnchorPosition.TOPLEFT)        .withOccurence(0)        .withCharacter(16)        .withSize(250, 70)        .withOffset(20, -58))    .withField(FieldBuilder.customField(customField.getId())        .withPositionAnchor(TextAnchorBuilder.newTextAnchor("Policy Number")            .atPosition(TextAnchorPosition.TOPLEFT)            .withOccurence(0)            .withCharacter(13)            .withSize(250, 25)            .withOffset(20, -10)))) ``` ### Results Once you have run your code, you will find your custom fields can be seen in your OneSpan Sign account. These custom fields will also be available for use in transactions. For more information, see Custom Fields. ## .NET SDK To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/create-custom-fields-net-sdk/) site. A Custom Field is one that, at the time of signing, is automatically populated with data that is specific to the signer. For instance, a signer might have an Agent Number, and that number may need to appear in the final document next to their signature. By using a custom field, the signer can specify their Agent Number, and that number will automatically appear in any other field that has been configured to receive it. The Custom Fields page enables you to manage the custom fields in your account. This functionality is available only if custom fields are enabled at the account level. Please contact our [Support Team](https://www.onespan.com/support) to have them enabled. ### Creating a Custom Field To create a custom field, you will need to build a CustomField object. Every custom field you create is identified by the unique id you set during this process. The following code will do this: > Creating another custom field with the same id will overwrite the original custom field. Also, note that every custom field you create is done so for the entire account. ```csharp String customFieldId1 = "policy_number_id"; CustomField customField = CustomFieldBuilder.CustomFieldWithId(customFieldId1)    .WithDefaultValue("123-456-789-0")    .WithTranslation(TranslationBuilder.NewTranslation("en")        .WithName("Policy Number")        .WithDescription("Car Insurance Policy Number."))    .Build(); eslClient.GetCustomFieldService().CreateCustomField(customField); ``` The withDefaultValue() is the value that appears after your signer has signed the document. This method is required when creating a custom field. Custom fields also contain a collection of translations which are used when displaying the custom field to account members. This tip is for accounts that support multiple languages. As a best practice, every custom field you need should be replicated for every language supported in your account. The system will only display the custom field in the language selected by the active user. If a custom field is not mapped to a language, it will default to English, regardless of the language selected by the active user. At least one translation is required when building your CustomField object. Use the OneSpan Sign CustomFieldService to create your custom field. ### Retrieving Custom Fields You can retrieve your custom fields with theOneSpan Sign CustomFieldService. You can either retrieve all custom fields, which are returned to you as a list, or retrieve a specific one using the custom field id. The following code will do this: ```csharp // Get the entire list of custom fields from the account IList retrieveCustomFieldList1 = eslClient.GetCustomFieldService().GetCustomFields(Direction.ASCENDING); // Get the first custom field from the account CustomField retrieveCustomField = eslClient.GetCustomFieldService().GetCustomField(customFieldId1); ``` ### Deleting a Custom Field Deleting a custom field from your account is also done with the OneSpan Sign CustomFieldService. The following code will do this: ```csharp // Delete the second custom field from the account eslClient.GetCustomFieldService().DeleteCustomField(customFieldId1); ``` ### Editing a Signature Block to Add Custom Fields To edit signature block to add custom codes, use the following code. In this example, text anchors are used to position both signature and custom fields. For more information, see [Text Anchors](/v1/docs/using-text-anchors). ```csharp .WithSignature(SignatureBuilder.SignatureFor(email1)    .WithPositionAnchor(TextAnchorBuilder.NewTextAnchor("Client Signature")        .AtPosition(TextAnchorPosition.TOPLEFT)        .WithOccurrence(0)        .WithCharacter(16)        .WithSize(250, 70)        .WithOffset(20, -58))    .WithField(FieldBuilder.CustomField(customField.Id)        .WithPositionAnchor(TextAnchorBuilder.NewTextAnchor("Policy Number")            .AtPosition(TextAnchorPosition.TOPLEFT)            .WithOccurrence(0)            .WithCharacter(13)            .WithSize(250, 25)            .WithOffset(20, -10)))) ``` ### Results Once you have run your code, you will find your custom fields can be seen in your OneSpan Sign account. These custom fields will also be available for use in transactions. For more information, see Custom Fields. ## REST API To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/apply-custom-field-document-rest-api/) site. A Custom Field is one that, at the time of signing, is automatically populated with data that is specific to the signer. For instance, a signer might have an Agent Number, and that number may need to appear in the final document next to their signature. By using a custom field, the signer can specify their Agent Number, and that number will automatically appear in any other field that has been configured to receive it. The Custom Fields page enables you to manage the custom fields in your account. This functionality is available only if custom fields are enabled at the account level. Please contact our [Support Team](https://www.onespan.com/support) to have them enabled. ### Creating a Custom Field Every custom field you create is identified by the unique id you set during this process. In the JSON below, the value object is the value that appears after your signer has signed the document. This field is required when creating a custom field. > Creating another custom field with the same id will overwrite the original custom field. Also, note that every custom field you create is done so for the entire account. To create a custom field, you will need to make the following request: #### HTTP Request ```http POST /api/account/customfields ``` #### HTTP Headers ```http Accept: application/json   Content-Type: application/json   Authorization: Basic api_key ``` #### Request Payload ```json {  "id": "policy_number_id",  "value": "123-456-789-0",  "required": false,  "translations": [    {      "language": "en",      "name": "Policy Number",      "description": "Car Insurance Policy Number."    }  ] } ``` For a complete description of each field, see the Request Payload table below. #### Response Payload ```json {  "dirtyFields": [    "translations",    "id",    "value",    "required"  ],  "required": false,  "id": "policy_number_id",  "data": null,  "translations": [    {      "dirtyFields": [        "name",        "description",        "language"      ],      "description": "Car Insurance Policy Number.",      "language": "en",      "id": "",      "data": null,      "name": "Policy Number"    }  ],  "value": "123-456-789-0",  "name": "" } ``` Custom fields also contain a collection of translations which are used when displaying the custom field to account members. This tip is for accounts that support multiple languages. As a best practice, every custom field you need should be replicated for every language supported in your account. The system will only display the custom field in the language selected by the active user. If a custom field is not mapped to a language, it will default to English, regardless of the language selected by the active user. ### Retrieving Custom Fields You can either retrieve all your custom fields by making a GET request to: [https://sandbox.esignlive.com/api/account/customfields.](https://sandbox.esignlive.com/api/account/customfields) Or, you can retrieve a specific custom fields by using it's custom ID in your GET request: [https://sandbox.esignlive.com/api/account/customfields/{customFieldId}](https://sandbox.esignlive.com/api/account/customfields/{customFieldId}) ### Deleting a Custom Field Deleting a custom field from your account is done by making a DELETE request to: [https://sandbox.esignlive.com/api/account/customfields/{customFieldId}](https://sandbox.esignlive.com/api/account/customfields/{customFieldId}) ### Editing a Signature Block to Add Custom Fields To edit signature block to add custom codes, use the following code. In this example, text anchors are used to position both signature and custom fields. For more information, see [Text Anchors](/v1/docs/using-text-anchors). ```json {  "approvals": [    {      "fields": [        {          "type": "SIGNATURE",          "extract": true,          "extractAnchor": {            "text": "Client Signature",            "index": 0,            "width": 250,            "height": 70,            "anchorPoint": "TOPLEFT",            "characterIndex": 16,            "leftOffset": 20,            "topOffset": -58          },          "subtype": "FULLNAME"        },        {          "type": "INPUT",          "extract": true,          "extractAnchor": {            "text": "Policy Number",            "index": 0,            "width": 250,            "height": 25,            "anchorPoint": "TOPLEFT",            "characterIndex": 13,            "leftOffset": 20,            "topOffset": -10          },          "subtype": "CUSTOMFIELD",          "name": "policy_number_id"        }      ],      "role": "Signer1"    },    {      "fields": [        {          "type": "SIGNATURE",          "extract": true,          "extractAnchor": {            "text": "Manager Signature",            "width": 250,            "height": 70,            "index": 0,            "anchorPoint": "TOPLEFT",            "characterIndex": 17,            "leftOffset": 20,            "topOffset": -58          },          "subtype": "FULLNAME"        },        {          "type": "INPUT",          "top": 50,          "left": 50,          "height": 50,          "width": 250,          "subtype": "CUSTOMFIELD",          "name": "agent_number_id"        }      ],      "role": "Signer2"    }  ] } ``` ### Results Once you have run your code, you will find your custom fields can be seen in your OneSpan Sign account. These custom fields will also be available for use in transactions. For more information, see Custom Fields. ### Request Payload Table | Property | Type | Editable | Required | Default | Sample Values | | --- | --- | --- | --- | --- | --- | | id | string | yes | no | n/a | policy_number_id | | value | string | yes | no | n/a | 123-456-789-0 | | required | boolean | yes | no | false | false / true | | translations | | | | | | | language | string | yes | no | en | en / fr / es ... | | name | string | yes | no | n/a | Policy Number | | description | string | yes | no | n/a | Car Insurance Policy Number |