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

1
2
3

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

1
2
3

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

Response

1
2
3
4
5
6
7
8
9
10
11
12

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

{
  "data": {
    "formFieldValues": [
      {"name": "first-name", "value": "", "createdBy": "alice", "updatedBy": "bob"},
      {"name": "last-name", "value": "", "createdBy": "alice", "updatedBy": "bob"},
      {"name": "email-address", "value": "", "createdBy": "alice", "updatedBy": "bob"},
    ]
  }
}

Each annotation includes the user_ids of both the person who created it and the person 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.

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:

1
2
3
4

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

Request

1
2
3
4
5
6
7
8
9
10
11
12

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",
}

1
2
3
4

$ curl -XPOST 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:

1
2
3
4
5
6
7
8

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

{
  "error": {
    "reason": "<error description>"
  }
}

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.