Free trial

OneSpan Sign How To: Using Text Anchors

eSignature developers
Haris Haidary,
Thumbnail

Lately, there has been a number of questions, in the forums, concerning the text anchor extraction feature with the SDKs and API, so I thought it would be a great opportunity to create a How To blog. In short, text anchors allow you to position a field or signature based on the text in your document. This document can be of any type as opposed to document extraction, which requires a PDF form. In this blog, I will show you how to use text anchor extraction with the OneSpan Sign Java SDK, .NET SDK, and the REST API.

Text Anchor Parameters

Before diving into the code, let me give you a brief description of each parameter you can pass when building your text anchor. It is important to note that when using text anchor, the search is performed in a case sensitive fashion. Also, if some parameters are not specified, they will default to the values below. 

Parameter Description Required Default Value
Anchor Text The exact string that will be searched in your document. Yes Not applicable
Anchor Point The corner of the specified character to use as the base for calculating the position. Available values: TOPLEFT, TOPRIGHT, BOTTOMLEFT, and BOTTOMRIGHT. Yes Not applicable
Index The occurrence of the string. For example, a value of 1 will skip the first occurrence and use the second instance to calculate position. No 0
Character Index The index of the character within the anchor text that will be used to calculate the position. No 0
Left Offset The offset applied to the final x-coordinate. No 0
Top Offset The offset applied to the final y-coordinate. No 0
Height The height of the field or signature. No 50
Width The width of the field or signature. No 200

The Code

As I mentioned above, I will show you how to use text anchor with the Java SDK, .NET SDK, and the REST API. Go ahead and skip to the section which applies to your technology. I will cover the same information in each segment. Full example code for this blog can be found in the Developer Community Code Share: Java, .NET, and REST.

Java SDK

Let’s begin with the Java SDK. In my example, I used text anchor to add a signature, signing date, and signer name for each signer. The sample code below shows you how to edit the document block for text anchor. If you need a comparison to the basic document object creation or if this is your first time creating a package with the Java SDK, see this blog.

.withDocument(newDocumentWithName("Sample Contract")
		              .fromFile("PATH_TO_YOUR_FILE")
		              .enableExtraction()
		              .withSignature(signatureFor("[email protected]")
		                   .withPositionAnchor(TextAnchorBuilder.newTextAnchor("Signature of the Client")
		                        .atPosition(TextAnchorPosition.TOPLEFT)
		                        .withSize(150, 40)
		                        .withOffset(0, -50)
		                        .withCharacter(0)
		                        .withOccurence(0))
		                   .withField(FieldBuilder.signerName()
		                		   	.withPositionAnchor(TextAnchorBuilder.newTextAnchor("(hereafter referred to as")
			                             .atPosition(TextAnchorPosition.TOPRIGHT)
			                             .withSize(150, 20)
			                             .withOffset(-175, -5)
			                             .withCharacter(0)
			                             .withOccurence(0)))
		                   .withField(FieldBuilder.signatureDate()
			                        .withPositionAnchor(TextAnchorBuilder.newTextAnchor("Date")
			                             .atPosition(TextAnchorPosition.TOPRIGHT)
			                             .withSize(75, 40)
			                             .withCharacter(4)
			                             .withOffset(10, -30)
			                             .withOccurence(0))))
		              .withSignature(signatureFor("[email protected]")
		                   .withPositionAnchor(TextAnchorBuilder.newTextAnchor("Signature of the Contractor")
		                        .atPosition(TextAnchorPosition.TOPLEFT)
		                        .withSize(150, 40)
		                        .withOffset(0, -50)
		                        .withCharacter(0)
		                        .withOccurence(0))
		                   .withField(FieldBuilder.signerName()
			                        .withPositionAnchor(TextAnchorBuilder.newTextAnchor("(hereafter referred to as")
			                             .atPosition(TextAnchorPosition.TOPLEFT)
			                             .withSize(150, 20)
			                             .withOffset(-175, -5)
			                             .withCharacter(0)
			                             .withOccurence(1)))
		                   .withField(FieldBuilder.signatureDate()
			                        .withPositionAnchor(TextAnchorBuilder.newTextAnchor("Date")
			                             .atPosition(TextAnchorPosition.TOPRIGHT)
			                             .withSize(75, 40)
			                             .withOffset(10, -30)
			                             .withCharacter(4)
			                             .withOccurence(1)))
OneSpan Developer Community

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today

.NET SDK

Next, I will go over the .NET SDK. In my example, I used text anchor to add a signature, signing date, and signer name for each signer. The sample code below shows you how to edit the document block for text anchor. If you need a comparison to the basic document object creation or if this is your first time creating a package with the .NET SDK, see this blog.

.WithDocument(DocumentBuilder.NewDocumentNamed("Sample Contract")
                                    .FromStream(fs, DocumentType.PDF)
                                    .EnableExtraction()
                                    .WithSignature(SignatureBuilder.SignatureFor("[email protected]")
                                            .WithPositionAnchor(TextAnchorBuilder.NewTextAnchor("Signature of the Client")
                                                    .AtPosition(TextAnchorPosition.TOPLEFT)
                                                    .WithSize(150, 40)
                                                    .WithOffset(0, -50)
                                                    .WithCharacter(0)
                                                    .WithOccurrence(0))
                                            .WithField(FieldBuilder.SignerName()
                                                    .WithPositionAnchor(TextAnchorBuilder.NewTextAnchor("(hereafter referred to as")
                                                            .AtPosition(TextAnchorPosition.TOPRIGHT)
                                                            .WithSize(150, 20)
                                                            .WithOffset(-175, -5)
                                                            .WithCharacter(0)
                                                            .WithOccurrence(0)))
                                            .WithField(FieldBuilder.SignatureDate()
                                                    .WithPositionAnchor(TextAnchorBuilder.NewTextAnchor("Date")
                                                            .AtPosition(TextAnchorPosition.TOPRIGHT)
                                                            .WithSize(75, 40)
                                                            .WithCharacter(4)
                                                            .WithOffset(10, -30)
                                                            .WithOccurrence(0))))
                                .WithSignature(SignatureBuilder.SignatureFor("[email protected]")
                                        .WithPositionAnchor(TextAnchorBuilder.NewTextAnchor("Signature of the Contractor")
                                                .AtPosition(TextAnchorPosition.TOPLEFT)
                                                .WithSize(150, 40)
                                                .WithOffset(0, -50)
                                                .WithCharacter(0)
                                                .WithOccurrence(0))
                                        .WithField(FieldBuilder.SignerName()
                                                .WithPositionAnchor(TextAnchorBuilder.NewTextAnchor("(hereafter referred to as")
                                                         .AtPosition(TextAnchorPosition.TOPLEFT)
                                                         .WithSize(150, 20)
                                                         .WithOffset(-175, -5)
                                                         .WithCharacter(0)
                                                         .WithOccurrence(1)))
                                        .WithField(FieldBuilder.SignatureDate()
                                                .WithPositionAnchor(TextAnchorBuilder.NewTextAnchor("Date")
                                                         .AtPosition(TextAnchorPosition.TOPRIGHT)
                                                         .WithSize(75, 40)
                                                         .WithOffset(10, -30)
                                                         .WithCharacter(4)
                                                         .WithOccurrence(1)))

REST API

Finally, I will cover the REST API. In my example, I used text anchor to add a signature, signing date, and signer name for each signer. I included the JSON that will create your document package with text anchor for convenience. Please note that OneSpan Sign’s API convention allows only one signature field (i.e. "type": "SIGNATURE") per approval in the approvals object. A second signature for a given role would need to be added as a separate approval. If you need a comparison to the basic document object creation or if this is your first time creating a package with the REST API, see this blog.

{

  "roles": [

    {

      "id": "client",

      "type": "SIGNER",

      "index": 1,

      "signers": [

        {

          "firstName": "John",

          "lastName": "Smith",

          "email": "[email protected]"

        }

      ],

      "name": "client"

    },

    {

      "id": "contractor",

      "type": "SIGNER",

      "index": 2,

      "signers": [

        {

          "firstName": "Bob",

          "lastName": "Murray",

          "email": "[email protected]"

        }

      ],

      "name": "contractor"

    }

  ],

  "documents": [

    {

      "approvals": [

        {

          "fields": [

            {

              "type": "SIGNATURE",

              "extract": false,

              "extractAnchor": {

                "text": "Signature of the Client",

                "index": 0,

                "width": 150,

                "height": 40,

                "anchorPoint": "TOPLEFT",

                "characterIndex": 0,

                "leftOffset": 0,

                "topOffset": -50

              },

              "left": 0,

              "subtype": "FULLNAME",

              "top": 0

            },

            {

              "value": null,

              "type": "INPUT",

              "binding": "{signer.name}",

              "extract": false,

              "extractAnchor": {

                "text": "(hereafter referred to as",

                "index": 0,

                "width": 150,

                "height": 20,

                "anchorPoint": "TOPRIGHT",

                "characterIndex": 0,

                "leftOffset": -175,

                "topOffset": -5

              },

              "left": 0,

              "subtype": "LABEL",

              "top": 0

            },

            {

              "value": null,

              "type": "INPUT",

              "binding": "{approval.signed}",

              "extract": false,

              "extractAnchor": {

                "text": "Date",

                "index": 0,

                "width": 75,

                "height": 40,

                "anchorPoint": "TOPRIGHT",

                "characterIndex": 4,

                "leftOffset": 10,

                "topOffset": -30

              },

              "left": 0,

              "subtype": "LABEL",

              "top": 0

            }

          ],

          "role": "client"

        },

        {

          "fields": [

            {

              "type": "SIGNATURE",

              "extract": false,

              "extractAnchor": {

                "text": "Signature of the Contractor",

                "index": 0,

                "width": 150,

                "height": 40,

                "anchorPoint": "TOPLEFT",

                "characterIndex": 0,

                "leftOffset": 0,

                "topOffset": -50

              },

              "left": 0,

              "subtype": "FULLNAME",

              "top": 0

            },

            {

              "value": null,

              "type": "INPUT",

              "binding": "{signer.name}",

              "extract": false,

              "extractAnchor": {

                "text": "(hereafter referred to as",

                "index": 1,

                "width": 150,

                "height": 20,

                "anchorPoint": "TOPRIGHT",

                "characterIndex": 0,

                "leftOffset": -175,

                "topOffset": -5

              },

              "left": 0,

              "subtype": "LABEL",

              "top": 0

            },

            {

              "value": null,

              "type": "INPUT",

              "binding": "{approval.signed}",

              "extract": false,

              "extractAnchor": {

                "text": "Date",

                "index": 1,

                "width": 75,

                "height": 40,

                "anchorPoint": "TOPRIGHT",

                "characterIndex": 4,

                "leftOffset": 10,

                "topOffset": -30

              },

              "left": 0,

              "subtype": "LABEL",

              "top": 0

            }

          ],

          "role": "contractor"

        }

      ],

      "name": "Sample Contract"

    }

  ],

  "name": "Text Anchor Extraction Example REST API",

  "type": "PACKAGE",

  "language": "en",

  "autoComplete": true,

  "status": "DRAFT"

}

Running Your Code

Once you’ve run your code, if you log into OneSpan Sign, you should find the appropriate signatures and fields in the document in your OneSpan Sign document package, as seen below.

screenshot

There you go. You have successfully created a new package with text anchors.

If you have questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the developer community forums: https://developer.esignlive.com. That's it from me. Thank you for reading! If you found this post helpful, please share it on Facebook, Twitter, or LinkedIn.

Haris Haidary
Junior Technical Evangelist
LinkedIn | Twitter

Haris Haidary
Go To Top
Share