Why does the document send API return a “Form fields cannot be null” error?

If the Document Send API returns a 400 Bad Request error with the message “Form fields cannot be null”, the request contains missing, empty, malformed, or invalid form field data in the signer payload.

This article explains the common causes of this error and how to resolve it.

Why does this happen?

This error typically occurs when one of the following conditions is true:

• The request does not include any signers.
• A signer is present, but the signer does not contain a formFields array.
• The Signers payload is incorrectly serialized when using multipart/form-data.
• The formFields array is empty.
• One or more form field objects contain invalid or incomplete property values.

When sending documents through the API, each signer must contain a valid formFields collection. Each form field should include the required properties, such as fieldType, pageNumber, bounds, and isRequired.

How do I fix this error?

Review your request and verify the following:

1. Include at least one signer

Your request must include at least one signer in the signers payload.

2. Add a valid formFields array

If you are defining signer fields through the API request, each signer must include a valid formFields array.

3. Ensure the formFields array is not empty

The formFields array must contain one or more valid field definitions.

4. Validate the form field properties

Verify that each form field contains valid values for required properties such as:

• fieldType
• pageNumber
• bounds
• isRequired
• id or name, when applicable

5. Check payload serialization

If you are using multipart/form-data, make sure the Signers value is sent as properly serialized JSON.

A formatting issue in the Signers payload can cause the API to read formFields incorrectly or treat it as null.

Example of a valid signer structure

The following example shows a simplified signer payload containing a valid formFields array:

{
  "name": "Alex",
  "emailAddress": "[email protected]",
  "signerType": "Signer",
  "formFields": [
    {
      "id": "signature1",
      "fieldType": "Signature",
      "pageNumber": 1,
      "bounds": {
        "x": 80,
        "y": 50,
        "width": 31,
        "height": 21
      },
      "isRequired": true
    }
  ],
  "locale": "EN"
}

Additional troubleshooting

If the request still fails after validating the payload:

1. Compare your request with a working Send Document API example.
2. Review your application logs to inspect the exact payload sent to BoldSign.
3. Verify that signer and form field objects are correctly structured and serialized.
4. Check for a SendFailed webhook event to determine whether the document failed validation during asynchronous processing.

Document sending is processed asynchronously. In some cases, you may initially receive a documentId, while the final status is determined after processing completes. If validation fails during processing, the SendFailed webhook event contains details that can help identify the root cause.

For more information, refer to:

• Send documents - API Documentation
• How to view all API logs in the developer console as an account admin?

After validating the signer payload, formFields array, and request serialization, the Document Send API can successfully process the request without returning the “Form fields cannot be null” error.