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.

Parameter Description Required Default Value

Anchor Text

The exact string that will be searched for 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.

No

TOPLEFT

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.

Yes

Not applicable

Width

The width of the field or signature.

Yes

Not applicable

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("[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))))   ) 

Results

Here is an example of what you can expect to see once you have run your code.

Capture

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.

Parameter Description Required Default Value

Anchor Text

The exact string that will be searched for 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.

No

TOPLEFT

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.

Yes

Not applicable

Width

The width of the field or signature.

Yes

Not applicable

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("[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))))   ) 

Results

Here is an example of what you can expect to see once you have run your code.

Capture

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.

Parameter Description Required Default Value

Anchor Text

The exact string that will be searched for 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.

No

TOPLEFT

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

Not applicable

Character Index

The index of the character within the anchor text that will be used to calculate the position.

Yes

Starting from 0

Left Offset

The offset applied to the final x-coordinate.

Yes

Refer to the Offset Axis

Top Offset

The offset applied to the final y-coordinate.

Yes

Refer to the Offset Axis

Height

The height of the field or signature.

Yes

Not applicable

Width

The width of the field or signature.

Yes

Not applicable

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": "[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   },   {   "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

Here is an example of what you can expect to see once you have run your code.

Capture

Request Payload Table

PropertyTypeEditableRequiredDefaultSample Values
PropertyTypeEditableRequiredDefaultSample Values
statusstringYesNoDRAFTDRAFT / SENT / COMPLETED / ARCHIVED / DECLINED / OPTED_OUT / EXPIRED
autoCompletebooleanYesNotruetrue / false
typestringYesNoPACKAGEPACKAGE / TEMPLATE / LAYOUT
namestringYesYesn/aText Anchor Extraction Example REST API
languagestringYesYesenen / fr / de ...
documents
namestringYesNon/aSample Contract
approvals
rolestringYesNon/aclient
fields
typestringYesYesn/aSIGNATURE / INPUT
extractbooleanYesNofalsetrue / false
subtypestringYesYesn/aFULLNAME / INITIALS / CAPTURE / MOBILE_CAPTURE / LABEL / TEXTFIELD / TEXTAREA / CHECKBOX / DATE / RADIO / LIST
bindingstringYesNonullnull / {approval.signed} / {signer.title} / {signer.name} / {signer.company}
leftintegerYesNo00 / 10 / 20 ...
topintegerYesNo00 / 10 / 20 ...
extractAnchor
textstringYesYesn/aSignature of the Client
anchorPointstringYesYesn/aTOPLEFT / TOPRIGHT / BOTTOMLEFT / BOTTOMRIGHT
indexintegerYesNo00 / 1 / 2 ...
widthintegerYesNo200150
characterIndexintegerYesNo00
heightintegerYesNo5040
leftOffsetintegerYesNo040
rightOffsetintegerYesNo0-10
roles
idstringYesNon/aclient
indexintegerYesNo01 / 2 / 3 ...
namestringYesNon/aclient
typestringYesNoSIGNERSIGNER / SENDER
signers
emailstringYesYesn/a[email protected]
firstNamestringYesYesn/aJohn
lastNamestringYesYesn/aSmith
idstringYesNon/aclient

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.

Parameter Description Required Default Value

Anchor Text

The exact string that will be searched for 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.

No

TOPLEFT

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.

Yes

Not applicable

Width

The width of the field or signature.

Yes

Not applicable

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};   document1.approvals = new List<ESignLiveAPIObjects.Approval>{approval1,approval2};   pkg.documents = new List<ESignLiveAPIObjects.Document>{document1}; //add document 

Results

Here is an example of what you can expect to see once you have run your code.

Capture