What is the new coordinate system and how do I use it?
When the “page” parameter is supplied in the “form_fields_per_document” JSON object, HelloSign will interpret the coordinates of the component relative to the top left corner of the page. For example, if the “page” is 10 and the (x, y) coordinates provided are (100, 100), the component will be placed near the top left on the 10th page of the document.
The new coordinate system will use the commonly used standard of 72 dpi resolution for displaying web images, and all pages are resized to 8.5 x 11 (or 11 x 8.5 if the pages are landscape).
What was the previous coordinate system and how do I use it?
The fields that should appear on the document, expressed as a 2-dimensional JSON array serialized to a string. The main array represents documents, with each containing an array of form fields. One document array is required for each file provided by the file parameter. In the case of a file with no fields, an empty list must be specified.
Each field must contain:
- api_id - (string) an identifier for the field that is unique across all documents in the request
- type - one of the Type options
- x & y - (int) location coordinates of the field in pixels
- width & height - (int) size of the field in pixels
- required - (boolean) whether this field is required
- signer - (int) signer index identified by the offset %i% in the signers[%i%] parameter, indicating which signer should fill out the field
Optionally, each field may contain a name (string) parameter. This is a display name for the field. Each text field may contain a validation_type parameter. Check out the list of validation types to learn more about the possible values.
The following is an example of a form_fields_per_document for a 2-document request with a text field and signature field on the first document, prior to serialization to a string for the API request:
I don’t want to switch yet to the new coordinate system. How can I continue to use the original one?
You don’t need to do anything! The existing “form_fields_per_document” parameter format will continue to work and as long as you don’t supply the optional page parameter, you will use the old coordinate system. When you are ready to switch over, just add the page parameter, along with the new (x, y) coordinates.