--- title: "Using Text Anchors" slug: "using-text-anchors" updated: 2025-07-17T13:49:46Z published: 2025-07-17T13:49:46Z canonical: "docs.onespan.com/using-text-anchors" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.onespan.com/llms.txt > Use this file to discover all available pages before exploring further. # Using Text Anchors [Java SDK](/v1/docs/using-text-anchors#java-sdk) [.NET SDK](/v1/docs/using-text-anchors#net-sdk) [REST API](/v1/docs/using-text-anchors#rest-api) [APEX SDK](/v1/docs/using-text-anchors#apex-sdk) ## Java SDK To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/using-text-anchors-java-sdk/) site. The PDF used in this guide can be found [here](https://cdn.document360.io/038f59a7-abd0-4c14-9de7-3434d28b49fd/Images/Documentation/cleaning_contract(1).pdf). 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. - OneSpan uses PDF points as its unit of measurement. For example, 1 inch = 72 pts. - When navigating with text anchors, (0, 0) is located at the **top left** of the PDF document. | 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. ![](https://cdn.document360.io/038f59a7-abd0-4c14-9de7-3434d28b49fd/Images/Documentation/image(17).png) ### 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 [](https://developer.esignlive.com/guides/quick-start/creating-and-sending-a-package-net/)[Creating and Sending a Transaction](/v1/docs/creating-and-sending-a-transaction#net-sdk). ```java .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](https://community.onespan.com/documentation/onespan-sign/codeshare/using-text-anchors-net-sdk/) site. The PDF used in this guide can be found [here](https://cdn.document360.io/038f59a7-abd0-4c14-9de7-3434d28b49fd/Images/Documentation/cleaning_contract(1).pdf). 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. ![](https://cdn.document360.io/038f59a7-abd0-4c14-9de7-3434d28b49fd/Images/Documentation/image(18).png) ### 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 [](https://developer.esignlive.com/guides/quick-start/creating-and-sending-a-package-net/)[Creating and Sending a Transaction](/v1/docs/creating-and-sending-a-transaction#net-sdk). ```plaintext .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](https://community.onespan.com/documentation/onespan-sign/codeshare/using-text-anchors-rest-api/) site. The PDF used in this guide can be found [here](https://cdn.document360.io/038f59a7-abd0-4c14-9de7-3434d28b49fd/Images/Documentation/cleaning_contract(1).pdf). 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 [](https://developer.esignlive.com/guides/quick-start/creating-and-sending-a-package-net/)[Creating and Sending a Transaction](/v1/docs/creating-and-sending-a-transaction#net-sdk). 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. ![](https://cdn.document360.io/038f59a7-abd0-4c14-9de7-3434d28b49fd/Images/Documentation/image(19).png) #### HTTP Request ```http POST /api/packages ``` #### HTTP Headers ```http Accept: application/json Content-Type: multipart/form-dataAuthorization: Basic api_key ``` #### Request Payload ```json ------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 ```json {  "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 | 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 | ## APEX SDK To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/using-text-anchors-apex-sdk/) site. The PDF used in this guide can be found [here](/resources/pdfs/cleaning_contract.pdf). 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. ![](https://cdn.document360.io/038f59a7-abd0-4c14-9de7-3434d28b49fd/Images/Documentation/image(20).png) ### 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 [](https://developer.esignlive.com/guides/quick-start/creating-and-sending-a-package-net/)[Creating and Sending a Transaction](/v1/docs/creating-and-sending-a-transaction#net-sdk). ```plaintext // Prepare Documents Blob String document1Name = 'Sample_Text_Anchor'; StaticResource sr = [SELECT Id, Body FROM StaticResource WHERE Name = 'test_text_anchor' LIMIT 1]; Map documentBlobMap = new Map(); 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{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{field21, field22, field23}; // Assign approvals to document document1.approvals = new List{approval1, approval2}; // Add document to package pkg.documents = new List{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.