Using Text Anchors

Java SDK.NET SDKREST APIAPEX SDK

Java SDK

To download the full code sample see our Code Share site. The PDF used in this guide can be found here.

Text anchors allow you to position a field or signature based on the text in your document.

Text Anchor Parameters

The following table provides a brief description of every parameter that can be passed when building your text anchors. Note the following:

• Text anchors are case-sensitive, and thus when using text anchor, the search is performed in a case sensitive fashion.

• If a parameter is not specified, the default value below will be used.

Best Practices for Using Text Tags

If you are having problems putting your text anchors in their proper location, try using the offset attribute.

Adding Text Anchors

In this example, text anchors are used to add a signature, signing date, and signer name for each signer.

If you need a comparison to the basic object creation procedure, or if this is the first time creating a transaction, see Creating and Sending a Transaction.

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

Results

Once you have run your code, your signature fields will appear in your documents, at the locations specified by your text anchors.

.NET SDK

To download the full code sample see our Code Share site. The PDF used in this guide can be found here.

Text anchors allow you to position a field or signature based on the text in your document.

Text Anchor Parameters

The following table provides a brief description of every parameter that can be passed when building your text anchors. Note the following:

• Text anchors are case-sensitive, and thus when using text anchor, the search is performed in a case sensitive fashion.

• If a parameter is not specified, the default value below will be used.

Best Practices for Using Text Anchors

If you are having problems putting your text anchors in their proper location, try using the offset attribute.

Adding Text Anchors

In this example, text anchors are used to add a signature, signing date, and signer name for each signer.

If you need a comparison to the basic object creation procedure, or if this is the first time creating a transaction, see Creating and Sending a Transaction.

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

Results

Once you have run your code, your signature fields will appear in your documents, at the locations specified by your text anchors.

REST API

To download the full code sample see our Code Share site. The PDF used in this guide can be found here.

Text anchors allow you to position a field or signature based on the text in your document.

Adding Text Anchors

In this example, text anchors are used to add a signature, signing date, and signer name for each signer.

If you need a comparison to the basic object creation procedure, or if this is the first time creating a transaction, see Creating and Sending a Transaction.

Below is the JSON that will create your document package with text anchors. Please note that OneSpan Sign's API convention allows only for only one signature field (for example, type: SIGNATURE) per approval in the approvals object. A second signature for a given role would need to be added as a separate approval.

Text Anchor Parameters

The following table provides a brief description of every parameter that can be passed when building your text anchors. Note the following:

• Text anchors are case-sensitive, and thus when using text anchor, the search is performed in a case sensitive fashion.

• If a parameter is not specified, the default value below will be used.

Best Practices for Using Text Anchors

If you are having problems putting your text anchors in their proper location, try using the offset attribute.

HTTP Request

 POST /api/packages 

HTTP Headers

Accept: application/json
Content-Type: multipart/form-dataAuthorization: 
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, see the Request Payload table below.

Response Payload

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

Results

Once you have run your code, your signature fields will appear in your documents, at the locations specified by your text anchors.

Request Payload Table

APEX SDK

To download the full code sample see our Code Share site. The PDF used in this guide can be found here.

Text anchors allow you to position a field or signature based on the text in your document.

Text Anchor Parameters

The following table provides a brief description of every parameter that can be passed when building your text anchors. Note the following:

• Text anchors are case-sensitive, and thus when using text anchor, the search is performed in a case sensitive fashion.

• If a parameter is not specified, the default value below will be used.

Best Practices for Using Text Anchors

If you are having problems putting your text anchors in their proper location, try using the offset attribute.

Adding Text Anchors

In this example, text anchors are used to add a signature, signing date, and signer name for each signer.

If you need a comparison to the basic object creation procedure, or if this is the first time creating a transaction, see Creating and Sending a Transaction.

// Prepare Documents Blob
String document1Name = 'Sample_Text_Anchor';
StaticResource sr = [SELECT Id, Body FROM StaticResource WHERE Name = 'test_text_anchor' LIMIT 1];
Map<String, Blob> documentBlobMap = new Map<String, Blob>();
documentBlobMap.put(document1Name, sr.Body);

// Create Document Metadata
ESignLiveAPIObjects.Document document1 = new ESignLiveAPIObjects.Document();
document1.name = document1Name;
document1.id = document1Name;
document1.extract = true; // document level extraction: true

// Approval for role1
ESignLiveAPIObjects.Approval approval1 = new ESignLiveAPIObjects.Approval();
approval1.role = roleId1;
approval1.id = 'approval1';

ESignLiveAPIObjects.Field field11 = new ESignLiveAPIObjects.Field();
field11.id = 'signature1';
field11.type = 'SIGNATURE';
field11.subtype = 'FULLNAME';
field11.extractAnchor = new ESignLiveAPIObjects.ExtractAnchor(
    ESignLiveAPIObjects.AnchorPoint.TOPLEFT, 0, 40, 0, 0, 'Signature of the Client', -50, 150
);

ESignLiveAPIObjects.Field field12 = new ESignLiveAPIObjects.Field();
field12.id = 'signername1';
field12.type = 'INPUT';
field12.subtype = 'LABEL';
field12.binding = '{signer.name}'; // indicate it's a signer name label
field12.extractAnchor = new ESignLiveAPIObjects.ExtractAnchor(
    ESignLiveAPIObjects.AnchorPoint.TOPRIGHT, 0, 20, 0, -175, '(hereafter referred to as', -5, 150
);

ESignLiveAPIObjects.Field field13 = new ESignLiveAPIObjects.Field();
field13.id = 'signerdate1';
field13.type = 'INPUT';
field13.subtype = 'LABEL';
field13.binding = '{approval.signed}'; // indicate it's a signing date
field13.extractAnchor = new ESignLiveAPIObjects.ExtractAnchor(
    ESignLiveAPIObjects.AnchorPoint.TOPRIGHT, 4, 40, 0, 10, 'Date', -30, 75
);

approval1.fields = new List<ESignLiveAPIObjects.Field>{field11, field12, field13};

// Approval for role2
ESignLiveAPIObjects.Approval approval2 = new ESignLiveAPIObjects.Approval();
approval2.role = roleId2;
approval2.id = 'approval2';

ESignLiveAPIObjects.Field field21 = new ESignLiveAPIObjects.Field();
field21.id = 'signature2';
field21.type = 'SIGNATURE';
field21.subtype = 'FULLNAME';
field21.extractAnchor = new ESignLiveAPIObjects.ExtractAnchor(
    ESignLiveAPIObjects.AnchorPoint.TOPLEFT, 0, 40, 0, 0, 'Signature of the Contractor', -50, 150
);

ESignLiveAPIObjects.Field field22 = new ESignLiveAPIObjects.Field();
field22.id = 'signername2';
field22.type = 'INPUT';
field22.subtype = 'LABEL';
field22.binding = '{signer.name}'; // indicate it's a signer name label
field22.extractAnchor = new ESignLiveAPIObjects.ExtractAnchor(
    ESignLiveAPIObjects.AnchorPoint.TOPRIGHT, 0, 20, 1, -175, '(hereafter referred to as', -5, 150
);

ESignLiveAPIObjects.Field field23 = new ESignLiveAPIObjects.Field();
field23.id = 'signerdate2';
field23.type = 'INPUT';
field23.subtype = 'LABEL';
field23.binding = '{approval.signed}'; // indicate it's a signing date
field23.extractAnchor = new ESignLiveAPIObjects.ExtractAnchor(
    ESignLiveAPIObjects.AnchorPoint.TOPRIGHT, 4, 40, 1, 10, 'Date', -30, 75
);

approval2.fields = new List<ESignLiveAPIObjects.Field>{field21, field22, field23};

// Assign approvals to document
document1.approvals = new List<ESignLiveAPIObjects.Approval>{approval1, approval2};

// Add document to package
pkg.documents = new List<ESignLiveAPIObjects.Document>{document1}; // add document

Results

Once you have run your code, your signature fields will appear in your documents, at the locations specified by your text anchors.