Managing Custom Fields

 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); 

 // Get the entire list of custom field from account   List<CustomField> retrieveCustomFieldList1 = eslClient.getCustomFieldService().getCustomFields(Direction.ASCENDING);   // Get the first custom field from account   CustomField retrieveCustomField = eslClient.getCustomFieldService().getCustomField(customFieldId1); 

 // Delete the second custom field from account   eslClient.getCustomFieldService().deleteCustomField(customFieldId1); 

 .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)))) 

To download the full code sample see our Code Share site.

A Custom Field A field that, at the time of signing, is automatically populated with data that is specific to the signer. 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 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.

 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:

 // Get the entire list of custom field from account   IList<CustomField> retrieveCustomFieldList1 = eslClient.GetCustomFieldService().GetCustomFields(Direction.ASCENDING);   // Get the first custom field from 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:

 // Delete the second custom field from 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.

 .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.

To download the full code sample see our Code Share site.

A Custom Field A field that, at the time of signing, is automatically populated with data that is specific to the signer. 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 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

POST /api/account/customfields

HTTP Headers

Accept: application/json   
Content-Type: application/json   
Authorization: Basic api_key 

Request Payload

 {   "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

 {   "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.

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}

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}

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.

 {   "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