How do I use anchors?
Summary
Anchors will enable dynamic field placements based on a pre-configured phrase present in the PDF content. This is in many cases particularly interesting for use cases where PDFs are generated automatically and where the layout may differ a bit from document to document.
There are two ways in which anchors can be used. One is by using a reference PDF which holds all anchors and their placement relative to the phrase followed by replacing the PDF and the other is by using an offset parameter which decides the placement relative to the phrase occurrence.
API only feature
The anchoring function only works when working with our eSign API. We have the possibility of setting up anchors in our frontend, however this is just to enable easier configuration. The actual function will trigger with the use of the API.
Using anchors with an offset placement
Summary
The offset defines the placement of the field relative to the occurrence of the phrase. This can be quicker to set up and in some cases a bit easier to manage.
Usage
1. Create a document or a template without a PDF present.
https://apidocs.scrive.com/#apiv2documentsnew
https://apidocs.scrive.com/#templates
2. Update the template with fields that you wish to anchor. For example a signature field anchored to the phrase "SIGNATURE_1".
{
"type": "signature",
"name": "signature 1",
"signature": null,
"is_obligatory": true,
"should_be_filled_by_sender": false,
"placements": [{
"xrel": null,
"yrel": null,
"wrel": null,
"hrel": null,
"fsrel": null,
"page": null,
"tip": "left",
"anchors": [{
"text": "SIGNATURE_1",
"index": 1,
"offset": {
"x": 0,
"y": 0
}
}]
}],
"description": null
}
3. Once added, set the main file of the document to a PDF containing the anchor phrase.
https://apidocs.scrive.com/#set-the-main-file
4. The placement should now be updated and place the field directly under the occurrence. If you need to adjust the position, you may do so with the help of "x" and "y" in the "offset" object.
Using anchors with a reference PDF
Summary
This particular anchoring function will only trigger if a PDF is replaced in a document. This is because it will check for the relativity between the original PDF and the one that it is replaced with. For example, the function will see that the Scrive field “first name” is placed 20 pixels to the right of the phrase “name” written in the PDF. When the PDF is replaced by calling the endpoint /setfile without removing the original PDF, it will check for the same equal phrase “name” and place the Scrive field “first name” 20 pixels to the right of it.
Usage:
1. Create a Scrive template with a PDF file.
https://apidocs.scrive.com/#templates
Either by setting the parameter "is_template": true OR via Scrive Online
2. Update the template with the desired fields, e.g: a signature field. Set the placement to the desired relativity to the phrase which you are anchoring it to. If you are having issues placing the field using the API, you may also set the placements directly in the UI by logging in to your Scrive user.
{
"type": "signature",
"name": "signature 1",
"signature": null,
"is_obligatory": true,
"should_be_filled_by_sender": false,
"placements": [
{
"xrel": 0.34436506418081436,
"yrel": 0.8029571666972598,
"wrel": 0.273,
"hrel": 7.6e-2,
"fsrel": 1.6842105263157894e-2,
"page": 1,
"tip": "left",
"anchors": []
}
],
"description": null
}
3. Set an anchor on the field you want to be dynamically repositioned, then add the corresponding keyword as value for the parameter "text".
{
"type": "signature",
"name": "signature 1",
"signature": null,
"is_obligatory": true,
"should_be_filled_by_sender": false,
"placements": [
{
"xrel": 0.34436506418081436,
"yrel": 0.8029571666972598,
"wrel": 0.273,
"hrel": 7.6e-2,
"fsrel": 1.6842105263157894e-2,
"page": 1,
"tip": "left",
"anchors": [
{
"text": "signature 1",
"index": 1,
"offset": null
}
]
}
],
"description": null
}
4. Call the /newfromtemplate endpoint on the new Scrive template.
POST /api/v2/documents/newfromtemplate/{document_id}
https://apidocs.scrive.com/#new-document-from-template
5. Call the /setfile endpoint on a PDF containing the value set for "text" in the anchor properties.
POST /api/v2/documents/{document_id}/setfile
https://apidocs.scrive.com/#apiv2documents{document_id}setfile
If you logon to Scrive Online and open the draft via the e-Archive you should now see that the field has been moved according to the keyword.
Questions?
Contact us at support@scrive.com