How to use the Form_Fields_Per_Document parameter in the Dropbox Sign API

The form_fields_per_document parameter allows you to place fields on a document using a coordinate system. You can set the x and y coordinates of a field, as well as its height and width. The parameter is designed to be used with standard US Letter documents (8.5” x 11”). If you upload a differently sized document, the results may be inconsistent due to resizing variations during the conversion process.

It is important to note that there are currently *two* coordinate systems - an old one based on 80 DPI, and a new one based on 72 DPI. Each is explained below.

How to use the new system:

Here is the new system. This can only be used with the PDF file type. There's an outer array for all documents on the request, and an inner array that contains all of the fields for each document on the request. Note that it includes a page parameter, which tells the API that you are using the new system:

For 72 DPI documents, that means the dimensions are 612 x 792. To put a field near the top-left corner of the second page in this coordinate system, you would enter an “x” value of 10 and a “y” value of 10, and a “page” value of 2. 

The width and height parameters are calculated in an 80 DPI system no matter which coordinate system you are using, so if you want fields that perfectly line up next to each other, you will need to multiply the height by 1.111 and the width by 1.111 + 2. For example, here is how to line up two 100px signature fields that touch perfectly at the corners diagonally:

Here are the required parameters for each field:

1. api_id (string) - a unique identifier for the field. It must be unique for ALL documents in the request.
2. Type (string) - signature, text, date, initials, checkbox, text-merge or checkbox-merge. See the types section for more details.
3. x & y (integer) - location coordinates of the field in pixels. Cannot exceed the width or height of the document, or you will get an out-of-bounds warning.
4. width and height (integer) - the size of the field in pixels. Cannot exceed the width or height of the document.
5. required (boolean) - true or false depending on whether the field is required to be filled out.
6. signer (integer) - the index of the signer that this field is assigned to. For merge fields, set this to “sender.”

Here are the optional parameters:

1. name (string) - the field label for the field that appears on the document, such as “address.”
2. validation_type (string) - allows you to set a validation type for the field, such as “numbers only.”

How to use the old system:

The old system is similar to the new one, with a few key differences:

1. It uses an 80 DPI system, meaning that your dimensions will be slightly different from the 72 DPI system.
2. There is no page parameter - if you want a field on page 3, you have to add up the values of all pages for the y coordinate consecutively. (If page one has a length of 800, then to place a field on page two at 100 pixels down, you would enter the y coordinate as 900.) 
3. The x-coordinate value begins at 100 (not 0) on portrait orientation pages, and as 0 on landscape orientation pages.

The new system is recommended, as 72 DPI is a standard screen resolution for documents. However, if you are pulling data from old Dropbox Sign template (using the templates/get/:template_id endpoint), note that the data is returned with the old coordinate system.

Document conversion for non-standard sizing

The form_fields_per_document coordinate system is designed to use with US Letter-sized documents, and the following formula to convert fields will not work in all circumstances - however, it may be useful as a starting point if you are trying to place fields on a non-standard document and are willing to experiment!

The Dropbox Sign document converter will automatically resize the width of a document to letter size for the purposes of displaying it in the editor. This may make text appear more narrow during the signing process, but the final PDF will appear true to form. This also means that the placement and width of fields needs to be modified to appear correctly in the editor.

For example, let's say we have a document that's 11 x 17 (US Ledger) and we want a text field at x: 600 y: 700 with a width of 300 on our page 2. Assuming the new coordinate system with 72 dpi, we know that:

1. 8.5 x 11 (landscape US Letter) is 612 x 792 DPI
2. 11 x 17 (landscape US Ledger) is 792 x 1224 DPI

Now we "scale" the document's width from 792 to 612 by dividing 612 by 792. We get an answer of 0.7727.

Get the new document height using this ratio:

Previous_height / sqrt(pow(ratio, 2) + 1) = new height

1224 / sqrt(pow(0.7727, 2) + 1 = 990

(Read more about this calculation here: https://stackoverflow.com/a/30494623)

So the "document" that we're working with is 612 x 989.

Now we can calculate the new coordinates to send to Dropbox Sign:

New x position: 600 * 0.7727 = 463

Adjusting the textbox width: 300 * 0.7727 = 232

Calculate y scaling ratio: 990 / 792 = 1.25

Calculate y position: 700 * 1.25 = 875

Consider the invisible margin to get the new y position: 700 - ((990 - 875) / 2) = 642.5

So the new coordinates are:

x: 463

y: 642.5

w: 232

page: 2

These calculations are an approximation and there will be edge cases where the fields do not quite line up - for intended results, either use only US Standard Letter sized documents, or convert them in the document editor of your choice prior to uploading them.