Below, you'll find sections on:
- What is the coordinate system and how do I use it?
- How do I handle documents that are not US Letter sized 8.5x11 inches (or 11x8.5 in landscape)?
- What was the previous coordinate system and how do I use it?
- I don’t want to switch yet to the new coordinate system. How can I continue to use the original one?
1. What is the 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.
This 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).
2. How do I handle documents that are not US Letter sized 8.5x11 inches (or 11x8.5 in landscape)?
The coordinate system (both the old one based on 80 dpi, and the new one based on 72dpi) is designed to work only with 8.5x11 or 11x8.5 inch documents.
That's not to say that you can't use documents that are not the US Letter, though if you can't resize to US Letter before it gets to HelloSign, you'll have to do some calculations before passing in the form_fields_per_document values.
Basically you'll need to use x and y coordinates as if the document is 8.5 x 11. If you have the dimensions for the signer components based on the original size of your document, you can do some transformations to figure out what that would be based on the coordinates you'd use for US Letter with 8.5x11.
For example, let's say we have a document that's 17x11 (US Ledger in landscape) and we want a textbox at x: 622 y: 723 with a width of 318 on our page 2. Assuming the new coordinate system with 72 dpi, we know that:
1. 11x8.5 (landscape US Letter) is 792x612 dpi
2. 17x11 (landscape US Ledger) is 1224x792 dpi
Now we "scale" the document's width from 1224 to 792. 792/1224 = 0.647 (x scaling ratio)
Get new document height using ratio:
New document height: 612/sqrt(pow(0.647,2)+1) = 664.99 (More about this calc here: https://stackoverflow.com/a/30494623)
So the "document" that we're working with is 792x665.
Now we can calculate the new coordinates to send to HelloSign:
new x position: 622 * 0.647 = 402
Probably want to adjust the textbox width too: 318 * 0.647 = 206
Calculate y scaling ratio: 664.99/792 = 0.8396
Calculate y position: 723*0.8396 = 607
Consider the invisible margin to get the new y position: 607 - ((664.99 - 607)/2) = 578
So the new coordinates are:
Here's a visualization for this, in case it helps for context:
3. 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:
4. 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.