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:

Feature	Legacy Structure (Two-dimensional)	New Structure (One-dimensional)
Object format	Two-dimensional array, where an array of field objects is nested inside another array	One-dimensional array, where a flat object contains two arrays; one for documents and one for fields
Matching fields to documents	Uses the index of the array to determine which document the fields are associated with	Uses the `document_index` property to explicitly define the document the fields are associated with
Documents without fields	Must be included as an empty array (`[]`) to maintain index of other arrays	Can be omitted from API call

And side-by-side comparison:

Legacy: Two-dimensional ArrayNew: One-dimensional Array

Copy

Copied

{
  "file": [
    "file_0",
    "file_1",
    "file_2"
  ],
  "form_fields_per_document": [ // files array
    [ // file_0's fields array
      { // field 1
        "api_id": "uniqueIdHere_1",
        "name": "",
        "placeholder": "",
        "type": "text",
        "x": 112,
        "y": 328,
        "width": 100,
        "height": 16,
        "required": true,
        "signer": 1,
        "page": 1,
        "validation_type": "numbers_only"
      }
    ],
    [],
    [ // file_2's fields array
      { // field 1
        "api_id": "uniqueIdHere_3",
        "name": "",
        "type": "signature",
        "x": 530,
        "y": 415,
        "width": 120,
        "height": 30,
        "required": true,
        "signer": 0,
        "page": 1
      }
    ]
  ]
}

Copy

Copied

{
  "file": [
    "file_0",
    "file_1",
    "file_2"
  ],
  "form_fields_per_document": [ // files array
    { // file_0's field 1
      "document_index": 0,
      "api_id": "uniqueIdHere_1",
      "name": "",
      "placeholder": "",
      "type": "text",
      "x": 112,
      "y": 328,
      "width": 100,
      "height": 16,
      "required": true,
      "signer": 1,
      "page": 1,
      "validation_type": "numbers_only"
    },
    { // file_2's field 1
      "document_index": 2,
      "api_id": "uniqueIdHere_3",
      "name": "",
      "type": "signature",
      "x": 530,
      "y": 415,
      "width": 120,
      "height": 30,
      "required": true,
      "signer": 0,
      "page": 1
    }
  ]
}

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.

Legacy Format - Add field to two documentsLegacy Format - Add field to third document only

Copy

Copied

{
  "file": [
    "file_0",
    "file_1"
  ],
  "form_fields_per_document": [ // files array
    [ // file_0's fields array
      { // field 1
        "api_id": "uniqueIdHere_1",
        "name": "",
        "placeholder": "",
        "type": "text",
        "x": 112,
        "y": 328,
        "width": 100,
        "height": 16,
        "required": true,
        "signer": 1,
        "page": 1,
        "validation_type": "numbers_only"
      }
    ],
    [ // file_1's fields array
      { // field 1
        "api_id": "uniqueIdHere_2",
        "name": "",
        "type": "signature",
        "x": 530,
        "y": 415,
        "width": 120,
        "height": 30,
        "required": true,
        "signer": 0,
        "page": 1
      }
    ]
  ]
}

Copy

Copied

{
  "file": [
    "file_0",
    "file_1",
    "file_2",
    "file_3",
    "file_4"
  ],
  "form_fields_per_document": [ // files array
    [],
    [],
    [ // file_2's fields array
      { // field 1
        "api_id": "uniqueIdHere_1",
        "name": "",
        "placeholder": "",
        "type": "text",
        "x": 112,
        "y": 328,
        "width": 100,
        "height": 16,
        "required": true,
        "signer": 1,
        "page": 1,
        "validation_type": "numbers_only"
      }
    ],
    [],
    []
  ]
}

New: One-dimensional Array

There are two major changes to this new data structure:

Introduction of an explicity defined index for documents (document_index) — allowing fields to specify the document they belong to (no more passing empty arrays)
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.

New Format - Add field to two documentsNew Format - Add field to third document only

Copy

Copied

{
  "file": [
    "file_0",
    "file_1"
  ],
  "form_fields_per_document": [ // files array
    { // file_0's field 1
      "document_index": 0,
      "api_id": "uniqueIdHere_1",
      "name": "",
      "placeholder": "",
      "type": "text",
      "x": 112,
      "y": 328,
      "width": 100,
      "height": 16,
      "required": true,
      "signer": 1,
      "page": 1,
      "validation_type": "numbers_only"
    },
    { // file_0's field 2
      "document_index": 0,
      "api_id": "uniqueIdHere_2",
      "name": "",
      "type": "signature",
      "x": 530,
      "y": 415,
      "width": 120,
      "height": 30,
      "required": true,
      "signer": 0,
      "page": 1
    },
    { // file_1's field 1
      "document_index": 1,
      "api_id": "uniqueIdHere_3",
      "name": "",
      "type": "signature",
      "x": 530,
      "y": 415,
      "width": 120,
      "height": 30,
      "required": true,
      "signer": 0,
      "page": 1
    }
  ]
}

Copy

Copied

{
  "file": [
    "file_0",
    "file_1",
    "file_2",
    "file_3",
    "file_4"
  ],
  "form_fields_per_document": [ // files array
    { // file_2's field 1
      "document_index": 2,
      "api_id": "uniqueIdHere_1",
      "name": "",
      "placeholder": "",
      "type": "text",
      "x": 112,
      "y": 328,
      "width": 100,
      "height": 16,
      "required": true,
      "signer": 1,
      "page": 1,
      "validation_type": "numbers_only"
    },
  ]
}

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.