Text Anchors

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 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 anchors, 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/cs-packages

JS

HTTP Headers

Accept: application/json
Content-Type: multipart/form-data
Authorization: Bearer access_token

JS

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": "Mary",   "lastName": "Doe",   "email": "mary.doe@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--

JS

For a complete description of each field, see the Request Payload Table below.

Response Payload

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

JS

Request Payload Table

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	`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`