API Variables

The Variable object

A variable is a dynamic placeholder inside a template that will be replaced by the provided value when generating a document.

Note: All endpoints below (including the GET list endpoint) apply to custom templates only — they return 404 Not Found when called with a fillable_form template id. On a fillable_form template, variables are auto-detected from the uploaded PDF form fields and kept in sync on every upload; to read them, use GET /api/v1/templates/:id (the template show response embeds the variables). To change them, re-upload an updated PDF from the DocLift dashboard.

A variable includes the following fields:

• id: a unique identifier
• title: the name of the variable (alphanumeric characters and underscores only). Must be unique within a template. Automatically lowercased on custom templates; on fillable_form templates it mirrors the PDF form field name as-is.
• description: a text describing the expected content and format of the variable
• field_type: the type of variable — text, checkbox, radio, or select
• seed_value: a sample value used for previewing the template rendering (only visible in the template detail view returned by write endpoints)
• allowed_values: a list of accepted values (only for radio and select field types). When generating a document, the API will reject any value not present in this list with a 422 error.

---

Listing variables

To list all variables of a template:

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

[
    {
        "id": 200001,
        "title": "client_name",
        "description": "Full name of the client",
        "field_type": "text",
        "allowed_values": []
    },
    {
        "id": 200002,
        "title": "status",
        "description": "Client status",
        "field_type": "select",
        "allowed_values": ["active", "inactive", "pending"]
    }
]

---

Creating a variable

To create a new variable on a template:

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

{
    "variable": {
        "title": "investor_city",
        "description": "City of residence of the investor",
        "field_type": "text",
        "seed_value": "Paris"
    }
}

You'll get a 201 Created response with the created variable:

{
    "id": 200003,
    "title": "investor_city",
    "description": "City of residence of the investor",
    "field_type": "text",
    "allowed_values": []
}

For radio or select variables, include the allowed_values field:

{
    "variable": {
        "title": "payment_method",
        "description": "Selected payment method",
        "field_type": "select",
        "seed_value": "bank_transfer",
        "allowed_values": ["bank_transfer", "credit_card", "check"]
    }
}

Note: The seed_value is accepted in the request body but is not returned in the API response. It is only visible in the template detail view returned by template write endpoints (create, update, publish, unpublish).

---

Updating a variable

To update an existing variable:

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

{
    "variable": {
        "description": "Updated description",
        "seed_value": "Lyon"
    }
}

You'll get a 200 OK response with the updated variable:

{
    "id": 200003,
    "title": "investor_city",
    "description": "Updated description",
    "field_type": "text",
    "allowed_values": []
}

---

Deleting a variable

To delete a variable from a template:

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

You'll get a 204 No Content response.

Note: Variables can also be managed inline when creating or updating a template using variables_attributes. See the Templates API for details.