Text Anchors

This guide will cover how to use text anchor extraction to position your fields on your document.

The text anchor extraction feature allows the package (transaction in the new UI) sender to position a field or signature based on the text in the uploaded document.

Text Anchor Parameters

Below is 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. Yes 0
Character Index The index of the character within the anchor text that will be used to calculate the position. Yes 0
Left Offset The offset applied to the final x-coordinate. Yes 0
Top Offset The offset applied to the final y-coordinate. Yes 0
Height The height of the field or signature. Yes 50
Width The width of the field or signature. Yes 200

The Code

Full example code for this guide can be found in the Developer Community Code Share, here.

In this guide, text anchors are used 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 the first time creating a package with the Java SDK, see this guide.

.withDocument(newDocumentWithName("Sample Contract")
		              .fromFile("PATH_TO_YOUR_FILE")
		              .enableExtraction()
		              .withSignature(signatureFor("john.smith@example.com")
		                   .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("bob.murray@example.com")
		                   .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)))

Running Your Code

The PDF used in this guide can be found, here. I used for text anchor. 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.

Capture

Get the Code

The text anchor extraction feature allows the package (transaction in the new UI) sender to position a field or signature based on the text in the uploaded document.

Text Anchor Parameters

Below is 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. Yes 0
Character Index The index of the character within the anchor text that will be used to calculate the position. Yes 0
Left Offset The offset applied to the final x-coordinate. Yes 0
Top Offset The offset applied to the final y-coordinate. Yes 0
Height The height of the field or signature. Yes 50
Width The width of the field or signature. Yes 200

The Code

Full example code for this guide can be found in the Developer Community Code Share, here.

In this guide, text anchors are used 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 the first time creating a package with the .NET SDK, see this guide.

.WithDocument(DocumentBuilder.NewDocumentNamed("Sample Contract")
                                    .FromStream(fs, DocumentType.PDF)
                                    .EnableExtraction()
                                    .WithSignature(SignatureBuilder.SignatureFor("john.smith@example.com")
                                            .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("bob.murray@example.com")
                                        .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)))

Running Your Code

The PDF used in this guide can be found, here I used for text anchor. 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.

Capture

Get the Code

The text anchor extraction feature allows the package (transaction in the new UI) sender to position a field or signature based on the text in the uploaded document.

The Code

Full example code for this guide can be found in the Developer Community Code Share, here.

In this guide, text anchors are used to add a signature, signing date, and signer name for each signer. Below is the JSON that will create your document package with text anchors. 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 the first time creating a package with the REST API, see this guide.

HTTP Request
POST /api/packages

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

Request Payload

------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="file"; filename="Sample Contract.pdf"
Content-Type: application/pdf

%PDF-1.5
%µµµµ
1 0 obj
<>>>
endobj.... 

------WebKitFormBoundary1bNO60n7FqP5WO4t

{
  "roles": [
    {
      "id": "client",
      "type": "SIGNER",
      "index": 1,
      "signers": [
        {
          "firstName": "John",
          "lastName": "Smith",
          "email": "john.smith@example.com"
        }
      ],
      "name": "client"
    },
    {
      "id": "contractor",
      "type": "SIGNER",
      "index": 2,
      "signers": [
        {
          "firstName": "Bob",
          "lastName": "Murray",
          "email": "bob.murray@example.com"
        }
      ],
      "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
            },
            {
              "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
            },
            {
              "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
            },
            {
              "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
            },
            {
              "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"
}

------WebKitFormBoundary1bNO60n7FqP5WO4t--

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

Response Payload

{
    "id": "9sKhW-h-qS9m6Ho3zRv3n2a-rkI="
}

Running Your Code

The PDF used in this guide can be found, here I used for text anchor. 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.

Capture

Get the Code

JSON Properties

Property Type Editable Required Default Sample Value(s)
status string Yes No DRAFT DRAFT / SENT / COMPLETED / ARCHIVED / DECLINED / OPTED_OUT / EXPIRED
autoComplete boolean Yes No true true / false
type string Yes No PACKAGE PACKAGE / TEMPLATE / LAYOUT
name string Yes Yes n/a Text Anchor Extraction Example REST API
language string Yes Yes en en / fr / de …
documents
name string Yes No n/a Sample Contract
approvals
role string Yes No n/a client
fields
type string Yes Yes n/a SIGNATURE / INPUT
extract boolean Yes No false true / false
subtype string Yes Yes n/a FULLNAME / INITIALS / CAPTURE / MOBILE_CAPTURE / LABEL / TEXTFIELD / TEXTAREA / CHECKBOX / DATE / RADIO / LIST
binding string Yes No null null / {approval.signed} / {signer.title} / {signer.name} / {signer.company}
left integer Yes No 0 0 / 10 / 20 …
top integer Yes No 0 0 / 10 / 20 …
extractAnchor
text string Yes Yes n/a Signature of the Client
anchorPoint string Yes Yes n/a TOPLEFT / TOPRIGHT / BOTTOMLEFT / BOTTOMRIGHT
index integer Yes No 0 0 / 1 / 2 …
width integer Yes No 200 150
characterIndex integer Yes No 0 0
height integer Yes No 50 40
leftOffset integer Yes No 0 40
rightOffset integer Yes No 0 -10
roles
id string Yes No n/a client
index integer Yes No 0 1 / 2 / 3 …
name string Yes No n/a client
type string Yes No SIGNER SIGNER / SENDER
signers
email string Yes Yes n/a john.smith@example.com
firstName string Yes Yes n/a John
lastName string Yes Yes n/a Smith
id string Yes No n/a client