Fillable forms

What a fillable form is

A fillable form is a template authored by uploading a PDF that already contains AcroForm fields: text inputs, checkboxes, radio groups, drop-downs. Its category is fillable_form. Instead of an HTML body, its layout is the uploaded PDF itself. There is no content field to author by hand, and no HTML template involved at all.

Creating and editing a fillable form happens exclusively from the Doclift dashboard, which uploads the PDF on your behalf. There is no classic-API endpoint for it.

Variables come from the PDF, not from you

Uploading a PDF extracts every AcroForm field and turns each one into a variable:

Because title is copied verbatim from the PDF's own field name, it is not guaranteed to follow the naming convention you would otherwise choose for a custom template's variables. Name the fields deliberately in whatever tool produced the PDF.

Re-uploading a new version of the PDF resynchronizes variables: a field whose name matches an existing variable updates that variable's field_type and allowed_values; a new field name creates a new variable; a variable whose name is no longer among the PDF's fields is destroyed.

What the API can read

Once published, a fillable form is listed and shown exactly like any other template:

• GET /api/v1/templates: appears in the list, id/title/description only
• GET /api/v1/templates/:id: full detail, including variables with title, description, field_type, and allowed_values for each auto-detected field

{
  "id": 100021,
  "title": "Subscription form",
  "description": "Tax form uploaded as a fillable PDF",
  "content": null,
  "created_at": "2024-04-12T09:15:00+01:00",
  "updated_at": "2024-04-12T09:15:00+01:00",
  "variables": [
    {
      "title": "first_name",
      "description": "First name",
      "field_type": "text",
      "allowed_values": []
    },
    {
      "title": "plan",
      "description": "Subscription plan",
      "field_type": "select",
      "allowed_values": ["starter", "pro", "enterprise"]
    }
  ]
}

See Templates API for the full field reference of this response.

What only the dashboard can do

Every write path on this API (POST/PATCH/DELETE /api/v1/templates, publish, unpublish, and every /api/v1/templates/:template_id/variables action) is scoped to custom templates only. Calling any of them with a fillable form's id answers 404, identical to an id that does not exist. See Writes only reach custom templates for the exact response body and the same rule as it applies to custom templates' write endpoints.

There is no way to create, edit, delete, publish, unpublish, or manage the variables of a fillable form through the API. All of it (including the initial PDF upload and any resync) happens from the Doclift dashboard.

Generating a document

Once published, a fillable form generates exactly like a custom template: send its id as template_id and the variable values as a flat map to POST /api/v1/document_requests. See Document requests API. The one difference is that Doclift checks each provided value against the variable's allowed_values, when set, and answers 422 with a structured invalid_variables array on a mismatch. See Variable validation errors. orientation and the margin fields have no effect on a fillable form's output, since the layout is the uploaded PDF itself.