Server API for PDF Forms

PSPDFKit Server supports working with PDF documents with forms. The following API endpoints are provided for working with forms in PDFs:

• Fetching Document Form Field Values

• Updating Form Field Values

Fetching Document Form Field Values

To fetch all form field values in a given document, the following endpoint is provided. You need to specify the application/json content type header:

Request

GET /api/documents/:document_id/form-field-values
Accept: application/json
Authorization: Token token="<secret token>"

$ curl http://localhost:5000/api/documents/abc/form-field-values \
   -H "Accept: application/json" \
   -H "Authorization: Token token=<secret token>"

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "formFieldValues": [
      {
        "name": "first-name",
        "type": "pspdfkit/form-field/text",
        "value": "John",
        "createdBy": "alice",
        "updatedBy": "john",
        "group": "tenant"
      },
      {
        "name": "last-name",
        "type": "pspdfkit/form-field/text",
        "value": "Doe",
        "createdBy": "alice",
        "updatedBy": "john",
        "group": "tenant"
      },
      {
        "name": "speaks-languages",
        "type": "pspdfkit/form-field/checkbox",
        "value": [
          "English",
          "Hindi"
        ],
        "createdBy": "alice",
        "updatedBy": "john",
        "group": "tenant"
      }
    ]
  }
}

The type of the form field determines if the value is a single string or an array of strings. Currently, the following types hold a single string:

• pspdfkit/form-field/text

• pspdfkit/form-field/radio

• pspdfkit/form-field/signature

• pspdfkit/form-field/button

The types below can hold multiple values as an array of strings:

• pspdfkit/form-field/checkbox

• pspdfkit/form-field/combobox

• pspdfkit/form-field/listbox

Each form field value includes the ID of both the user who created it and the user who last modified it. For annotations created or updated in the browser, the user_id is extracted from the JSON Web Token (JWT) used for authentication. The group of the form field value is always the group of the associated form field.

Updating Form Field Values

To update existing form field values, send a POST request with a JSON body containing the list of form fields — and optionally, a user_id — to /api/documents/:document_id/annotations/:annotation_id, specifying the application/json content type.

The formFieldValues property expects a list of JSON objects in the following format:

{
  "name": string;
  "value": string | Array<String>;
}

Request

POST /api/documents/:document_id/form-field-values
Content-Type: application/json
Authorization: Token token="<secret token>"

{
  "formFieldValues": [
    {"name": "first-name", "value": "foo"},
    {"name": "last-name", "value": "bar"},
    {"name": "email-address", "value": "foo@bar.com"},
  ],
  "user_id": "bob",
}

$ curl -X POST http://localhost:5000/api/documents/abc/form-field-values \
   -H "Content-Type: application/json" \
   -H "Authorization: Token token=<secret token>" \
   -d '{"formFieldValues": [{"name": "first-name", "value": "foo"}, ...], "user_id": "bob"}'

Response

The server will validate the content and return an HTTP response with the status 200 and an empty body in the case of success.

If there’s a validation error, the following response will be returned:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": {
    "reason": {
      "formFieldValues": [
        // An object with a detailed reason for every invalid form field value.
        { ... }
      ]
    }
  }
}

Using Form API Endpoints with Layers

All the endpoints described above work on the default layer of a document and can also be used on a specific layer in a document by replacing documents/:document_id with documents/:document_id/layers/:layer_id in the URL of the endpoint. For more information on layers and how to use them, take a look at the Instant Layers guide.