👍

When to use tag fields?

When a document is variable length and is dynamically generated, it's a good idea to use tag fields to automatically detect where a user should sign and where data should be entered.
This makes it easy for you to setup documents via the api without needing to manually position fields yourself.

Step 1: Update your pdf to include tag syntax
Update your pdf to include our tag syntax in any position where you would like a data_field to appear.
These "tags" are text that you place in your document.

The syntax is as follow <# tag_id #>. The data_field_tag_id must be specified in data_field json that you submit with the request The width of the <# and #> indicates how wide to make the data_field. The height is determined based on the font size (use bigger font size to make a taller data field.

Step 2: Create the data_field json to link to the tags
Create the data_field json for all the tags in the pdf. You can also link signatories to those datafields at this point if you have the information on hand. Be sure to specify a type so we know what type of field to use.

{//document json
	"data_fields":[
  	   {
                "custom_id": "owner_name", //custom_id field is setup when you create a document and enter a custom id for the field.
                "uuid": "", //internal use
                
                "type": "text", //type of field. https://quicklysign.readme.io/docs/constants#datafield-type
                "required": false, //whether field is required or not.
                "height": 22, //this will be overridden when extracting feilds
                "width": 150,//this will be overridden when extracting feilds
               
                "signatory_uuid": "8f307866-cc34-3fee-f3a0-5c89e88f2841", //this must link to a signatory
                "x": 506.5, //this will be overridden when extracting feilds
              
                "data": null, //THIS IS WHERE YOU SET DATA. E.g. "Hello world".
                "y": 207, //this will be overridden when extracting feilds
              	"tag_id": "0" //this ID must be used in your tag on the pdf.
                "description":"",
                "background_colour":"", //rgb background colour with # e.g. #fff 
              	"tag_id":"" //tag_id used to link to tag_fields in pdf.
            }
  ],
  "signatories":[
    {
      "uuid":"8f307866-cc34-3fee-f3a0-5c89e88f2841", //this is the signatory_uuid in data_field.
      "name":"Rob Curtis",
     	"role": "signer_1", 
      "mobile_number":"",
      "email": "[email protected]", 
      "name": "Rob Curtis"
    }
  
  ]
	
}

Step 3: POST to /documents/ to create the file

Use query string parameter extract_fields_from_pdf_by_tag=true to indicate that the service must extract fields.

Post your json to /documents/?extract_fields_from_pdf_by_tag=true
This will return a temp_upload_url which you post your file to. The api will then detect the fields asynchronously, so don't request signatures just yet!

Note: you can also include query string parameter auto_request_signatures_when_ready=true if you want the document to send as soon as fields are setup.
Further info Documents ]