Fields

This guide shows you how to add, update, and delete fields.

Fields enable the placement of additional data in a document at the time of signing. Like signatures, they can be placed anywhere inside a document. Each field is linked to a particular signature.

The Code

You can download the complete example code from the Developer Community Code Share, here.

To add a field on a document, you will first need to create your Field object using the OneSpan Sign FieldBuilder, as shown below.

Field field = FieldBuilder.label()
        .withId(new FieldId("myLabelField"))
	.withValue("Example label field value")
	.atPosition(100, 200)
	.onPage(0)
	.build();

Once you have built your Field object, you call on OneSpan Sign’s ApprovalService to add your field on your document and pass the PackageId, SignatureId, and Field objects along with the document id String as parameters.

String labelFieldId = client.getApprovalService().addField(packageId, "sample-contract", signatureid, field);

Updating a field is also done in a similar fashion.

Field updatedField = FieldBuilder.signatureDate()
		.onPage(0)
		.withId(new FieldId("myLabelField"))
		.atPosition(100, 200)
		.build();
		
client.getApprovalService().updateField(packageId, "sample-contract", new SignatureId("ExampleSignatureId"), updatedField);

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. Finally, deleting a field is also done with the ApprovalService. You will need to pass the PackageId, SignatureId, FieldId objects along with the document id String as parameters.

client.getApprovalService().deleteField(packageId, "sample-contract", new SignatureId("ExampleSignatureId"), new FieldId("myLabelField"));

Running Your Code

Once you’ve run your code, if you login to OneSpan Sign and head over to the document view of your package, you can view the added signing date field.

Capture

Get The Code

Fields enable the placement of additional data in a document at the time of signing. Like signatures, they can be placed anywhere inside a document. Each field is linked to a particular signature.

The Code

You can download the complete example code from the Developer Community Code Share, here.

To add a field on a document, you will first need to create your Field object using the OneSpan Sign FieldBuilder, as shown below.

Field field = FieldBuilder.Label()
	.WithId("myLabelField")
	.WithValue("Example label field value")
	.AtPosition(100, 200)
        .OnPage(0)
	.Build();

Once you have built your Field object, you call on OneSpan Sign’s ApprovalService to add your field on your document and pass the PackageId, SignatureId, and Field objects along with the document id String as parameters.

string labelFieldId = client.ApprovalService.AddField(packageId, "sample-contract", signatureid, field);

Updating a field is also done in a similar fashion.

Field updatedField = FieldBuilder.SignatureDate()
	.OnPage(0)
	.WithId("myLabelField")
	.AtPosition(100, 200)
	.Build();
		
client.ApprovalService.ModifyField(packageId, "sample-contract", new SignatureId("ExampleSignatureId"), updatedField);

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. Finally, deleting a field is also done with the ApprovalService. You will need to pass the PackageId, SignatureId, FieldId objects along with the document id String as parameters.

client.ApprovalService.DeleteField(packageId, "sample-contract", new SignatureId("ExampleSignatureId"), "myLabelField");

Running Your Code

Once you’ve run your code, if you login to OneSpan Sign and head over to the document view of your package, you can view the added signing date field.

Capture

Get The Code

Fields enable the placement of additional data in a document at the time of signing. Like signatures, they can be placed anywhere inside a document. Each field is linked to a particular signature.

The Code

You can download the complete example code from the Developer Community Code Share, here.

The sample request below shows you how to add a field to an existing approval/signature:

HTTP Request
POST /api/packages/{packageId}/documents/{documentId}/approvals/{approvalId}/fields

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

Request Payload

{
  "name":"Signer Name",
  "top":500,
  "left":300,
  "width":100,
  "height":30,
  "page":0,
  "type":"INPUT",
  "value":null,
  "binding":"{signer.name}",
  "subtype":"LABEL"
}

For a complete description of each field, take a look at the JSON Properties section below.

Response Payload

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

If you want an example of a basic document package creation for comparison, you can follow this guide.

To update a field, you will need to make a PUT request to:

https://sandbox.esignlive.com/api/packages/{packageId}/documents/{documentId}/approvals/{signatureId}/fields/{fieldId}

With the updated field parameters:

{
  "id": "myLabelField",
  "top": 200,
  "left": 100,
  "width": 250,
  "height": 50,
  "page": 0,
  "type": "INPUT",
  "binding": "{approval.signed}",
  "subtype": "LABEL"
}

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. Finally, deleting a field is done by making a DELETE request to:

https://sandbox.esignlive.com/api/packages/{packageId}/documents/{documentId}/approvals/{signatureId}/fields/{fieldId}

Running Your Code

Once you’ve run your code, if you login to OneSpan Sign and head over to the document view of your package, you can view the added signing date field.

Capture

Get The Code

JSON Properties

Property Type Editable Required Default Sample Value(s)
name string Yes No n/a Signer Name
top integer Yes No 0 500
left integer Yes No 0 300
width integer Yes No 200 100
height integer Yes No 50 30
page integer Yes No 0 0 / 1 / 2 …
type string Yes No n/a SIGNATURE / INPUT
value string Yes No null STU BANK
subtype string Yes No n/a FULLNAME / INITIALS / CAPTURE / LABEL / TEXTFIELD / TEXTAREA / CHECKBOX / DATE / RADIO / LIST
binding string Yes No null {approval.signed} / {signer.title} / {signer.name} / {signer.company}