API Templates

The Template object

A template is a layout that once filled with variables will allow you to create a document.

A template is made of the following fields:

• id: a unique identifier
• title: any string that might make sense to you to name your template
• description: text given to describe the template
• category: the type of template — custom (HTML editor) or fillable_form (uploaded PDF with form fields)
• orientation: the page orientation — portrait or landscape
• published: whether the template is published or not. Only published templates can be used to generate documents
• content: the HTML content of the template (custom templates only)
• margin_top, margin_bottom, margin_left, margin_right: page margins in millimeters (minimum 5)
• variables: list of variables used in the template. See the Variables API for details
• created_at: the creation date (ISO-8601) of the template
• updated_at: the last update date (ISO-8601) of the template. Note that if a variable is updated, added or destroyed it will also actualize this value

Note: custom templates support full CRUD via the API. fillable_form templates are listed and readable through GET /api/v1/templates and GET /api/v1/templates/:id, and they can be used to generate documents. They cannot be created, updated, deleted, published or unpublished through the API — they must be managed from the DocLift dashboard. The content and margin fields described above are not used to render fillable forms (the layout comes from the uploaded PDF).

---

Listing the templates

To list the published templates of an account you can perform the following request:

GET https://app.doclift.io/api/v1/templates

You'll get:

[
    {
        "id": 100011,
        "title": "Template 1",
        "description": "Template 1 amazing description"
    },
    {
        "id": 100012,
        "title": "Template 2",
        "description": "Template 2 amazing description"
    }
]

Note that the list endpoint returns a short view with only id, title, and description. Use the view endpoint to get more details.

This result is paginated. See pagination chapter for more information about pagination.

---

Viewing a template

To view detailed information about a template, you can perform the following request:

GET https://app.doclift.io/api/v1/templates/:id

You'll get:

{
    "id": 100011,
    "title": "Template 1",
    "description": "Template 1 amazing description",
    "variables": [
        {
            "title": "firstname",
            "description": "First name of the client",
            "field_type": "text",
            "allowed_values": []
        },
        {
            "title": "status",
            "description": "Status selection",
            "field_type": "select",
            "allowed_values": ["active", "inactive", "pending"]
        }
    ],
    "created_at": "2021-02-28 21:48:03 +0100",
    "updated_at": "2021-02-28 21:48:58 +0100"
}

Note that you can view only published templates through the DocLift API, otherwise you'll get a 404 error response.

Viewing a fillable form template

The show endpoint also returns fillable_form templates. The response payload uses the same shape as a custom template show, but the variables array holds the form fields DocLift auto-detected from the uploaded PDF. These variables can be inspected only through this template show response — the /api/v1/templates/:template_id/variables endpoints return 404 for fillable forms.

{
    "id": 100021,
    "title": "Subscription form",
    "description": "Tax form uploaded as a fillable PDF",
    "variables": [
        {
            "title": "first_name",
            "description": "First name",
            "field_type": "text",
            "allowed_values": []
        },
        {
            "title": "accepts_terms",
            "description": "I accept the terms and conditions",
            "field_type": "checkbox",
            "allowed_values": []
        },
        {
            "title": "plan",
            "description": "Subscription plan",
            "field_type": "select",
            "allowed_values": ["starter", "pro", "enterprise"]
        }
    ],
    "created_at": "2024-04-12 09:15:00 +0100",
    "updated_at": "2024-04-12 09:15:00 +0100"
}

To use this template to generate a document, send the variable values exactly as you would for a custom template — see Document Requests API.

---

Creating a template

Applies to custom templates only. fillable_form templates must be created from the DocLift dashboard by uploading a PDF.

To create a new custom template, perform the following request:

POST https://app.doclift.io/api/v1/templates

{
    "template": {
        "title": "My new template",
        "description": "A template for invoices",
        "orientation": "portrait",
        "content": "<h1>Invoice</h1><p>{{client_name}}</p>",
        "margin_top": 10,
        "margin_bottom": 10,
        "margin_left": 15,
        "margin_right": 15,
        "variables_attributes": [
            {
                "title": "client_name",
                "description": "Name of the client",
                "field_type": "text",
                "seed_value": "John Doe"
            }
        ]
    }
}

You'll get a 201 Created response with the full template details:

{
    "id": 100013,
    "title": "My new template",
    "description": "A template for invoices",
    "content": "<h1>Invoice</h1><p>{{client_name}}</p>",
    "category": "custom",
    "orientation": "portrait",
    "published": false,
    "margin_top": 10,
    "margin_bottom": 10,
    "margin_left": 15,
    "margin_right": 15,
    "created_at": "2024-01-15 10:30:00 +0100",
    "updated_at": "2024-01-15 10:30:00 +0100",
    "variables": [
        {
            "id": 200003,
            "title": "client_name",
            "description": "Name of the client",
            "seed_value": "John Doe",
            "field_type": "text",
            "allowed_values": []
        }
    ]
}

Note: The create, update, publish, and unpublish endpoints return the full template detail view (including content, category, orientation, published, margins, and variables with id and seed_value). The GET show endpoint returns a lighter view without these fields.

You can include variables_attributes to create variables at the same time as the template. See the Variables API for the variable fields reference.

---

Updating a template

Applies to custom templates only. fillable_form templates must be edited from the DocLift dashboard (re-upload the PDF to refresh their variables).

To update an existing custom template, perform the following request:

PATCH https://app.doclift.io/api/v1/templates/:id

{
    "template": {
        "title": "Updated template title",
        "content": "<h1>Updated content</h1>"
    }
}

You'll get a 200 OK response with the full template detail view.

You can also manage variables inline using variables_attributes:

{
    "template": {
        "variables_attributes": [
            {
                "id": 200001,
                "title": "client_name_updated"
            },
            {
                "title": "new_variable",
                "field_type": "select",
                "allowed_values": ["option_a", "option_b"]
            },
            {
                "id": 200002,
                "_destroy": true
            }
        ]
    }
}

• To update an existing variable, include its id
• To create a new variable, omit the id
• To delete a variable, include its id with "_destroy": true

---

Deleting a template

Applies to custom templates only. fillable_form templates must be archived from the DocLift dashboard.

To archive a custom template (soft delete), perform the following request:

DELETE https://app.doclift.io/api/v1/templates/:id

You'll get a 204 No Content response. The template will be archived and no longer visible in listings.

---

Publishing a template

Applies to custom templates only. fillable_form templates are published from the DocLift dashboard.

To publish a template and make it available for document generation:

PUT https://app.doclift.io/api/v1/templates/:id/publish

You'll get a 200 OK response with the full template detail view.

---

Unpublishing a template

Applies to custom templates only. fillable_form templates are unpublished from the DocLift dashboard.

To unpublish a template and prevent it from being used for document generation:

PUT https://app.doclift.io/api/v1/templates/:id/unpublish

You'll get a 200 OK response with the full template detail view.