Using Text Anchors

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

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

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

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

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

Property	Type	Editable	Required	Default	Sample Values
Property	Type	Editable	Required	Default	Sample Values
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	[email protected]
firstName	string	Yes	Yes	n/a	John
lastName	string	Yes	Yes	n/a	Smith
id	string	Yes	No	n/a	client

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

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