New Patterns: Using Form Fields per Document

This page demonstrates and explains the correct format to use when calling form_fields_per_document.

The Dropbox Sign API offers different approaches to placing fields on your documents, with one of them being form_fields_per_document. Using the form_fields_per_document parameter allows you to add and place fields when sending an API request using x and y coordinates.

As part of our work on Dropbox Sign’s OpenAPI spec, we introduced the ability to use a one-dimensional array with form_fields_per_document. That’s a different data structure than the two-dimensional arrays used in the past. Our goal was to improve the experience of developers programmatically placing fields on documents while maintaining backwards compatibility.

Improving Data Structures

We understand breaking known patterns can be disruptive, so our apologies for any inconvenience to the folks already using form_fields_per_document. However, we strongly believe the new one-dimensional data structure is a positive change. This new structure offers two main benefits:

• Reduced complexity — making it more accessible for developers to programatically place fields
• Compatibility with new SDKs — all OpenAPI-powered SDKs support the new format

Differences between the two data structures at-a-glance:

And side-by-side comparison:

1
{
2
  "file": [
3
    "file_0",
4
    "file_1",
5
    "file_2"
6
  ],
7
  "form_fields_per_document": [ // files array
8
    [ // file_0's fields array
9
      { // field 1
10
        "api_id": "uniqueIdHere_1",
11
        "name": "",
12
        "placeholder": "",
13
        "type": "text",
14
        "x": 112,
15
        "y": 328,
16
        "width": 100,
17
        "height": 16,
18
        "required": true,
19
        "signer": 1,
20
        "page": 1,
21
        "validation_type": "numbers_only"
22
      }
23
    ],
24
    [],
25
    [ // file_2's fields array
26
      { // field 1
27
        "api_id": "uniqueIdHere_3",
28
        "name": "",
29
        "type": "signature",
30
        "x": 530,
31
        "y": 415,
32
        "width": 120,
33
        "height": 30,
34
        "required": true,
35
        "signer": 0,
36
        "page": 1
37
      }
38
    ]
39
  ]
40
}

Legacy: Two-dimensional Arrays

In this two-dimensional model, new fields were added to documents by inserting additional field objects into the array that corresponded with a specific document. This structure also required that an empty array [] be passed for documents that you didn’t want to add fields to. These objects had the potential to get confusing and difficult to work with, especially as they grew in size for signature requests with lots of documents or lots of fields.

1
{
2
  "file": [
3
    "file_0",
4
    "file_1"
5
  ],
6
  "form_fields_per_document": [ // files array
7
    [ // file_0's fields array
8
      { // field 1
9
        "api_id": "uniqueIdHere_1",
10
        "name": "",
11
        "placeholder": "",
12
        "type": "text",
13
        "x": 112,
14
        "y": 328,
15
        "width": 100,
16
        "height": 16,
17
        "required": true,
18
        "signer": 1,
19
        "page": 1,
20
        "validation_type": "numbers_only"
21
      }
22
    ],
23
    [ // file_1's fields array
24
      { // field 1
25
        "api_id": "uniqueIdHere_2",
26
        "name": "",
27
        "type": "signature",
28
        "x": 530,
29
        "y": 415,
30
        "width": 120,
31
        "height": 30,
32
        "required": true,
33
        "signer": 0,
34
        "page": 1
35
      }
36
    ]
37
  ]
38
}

New: One-dimensional Array

There are two major changes to this new data structure:

1. Introduction of an explicity defined index for documents (document_index) — allowing fields to specify the document they belong to (no more passing empty arrays)
2. Flattens the object overall — eliminating nested arrays

It might seem subtle, but this change in structure adds a lot of value. The reduction in complexity is designed to help developers read, understand, and interact with form_fields_per_document more effectively.

1
{
2
  "file": [
3
    "file_0",
4
    "file_1"
5
  ],
6
  "form_fields_per_document": [ // files array
7
    { // file_0's field 1
8
      "document_index": 0,
9
      "api_id": "uniqueIdHere_1",
10
      "name": "",
11
      "placeholder": "",
12
      "type": "text",
13
      "x": 112,
14
      "y": 328,
15
      "width": 100,
16
      "height": 16,
17
      "required": true,
18
      "signer": 1,
19
      "page": 1,
20
      "validation_type": "numbers_only"
21
    },
22
    { // file_0's field 2
23
      "document_index": 0,
24
      "api_id": "uniqueIdHere_2",
25
      "name": "",
26
      "type": "signature",
27
      "x": 530,
28
      "y": 415,
29
      "width": 120,
30
      "height": 30,
31
      "required": true,
32
      "signer": 0,
33
      "page": 1
34
    },
35
    { // file_1's field 1
36
      "document_index": 1,
37
      "api_id": "uniqueIdHere_3",
38
      "name": "",
39
      "type": "signature",
40
      "x": 530,
41
      "y": 415,
42
      "width": 120,
43
      "height": 30,
44
      "required": true,
45
      "signer": 0,
46
      "page": 1
47
    }
48
  ]
49
}

Future Plans — Deprecating Two-dimensional Arrays

We are optimistic about the impact the new, one-dimensional pattern will have moving forward. The improvements to developer experience and overall usability make programmatically placing fields accessible to more developers.

The new, OpenAPI-powered SDKs require the use of one-dimensional arrays with form_fields_per_document. Legacy SDKs can still use two-dimensional arrays and backwards compatibility will be maintained for as long as those SDKs are supported. Moving forward, all code examples involving form_fields_per_document will prioritize the one-dimensional structure, which is the recommended format.