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.

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 for custom templates.
• 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.