Template Variables

What is template variables?

Template variables allow you to connect multiple fields together by sharing the same value across different elements in your template.

The Problem Without Variables:

When the same value needs to appear in multiple places, you'd have to specify it repeatedly in your modifications:

{
  "modifications": [
    {"id": "header_name", "text": "John Doe"},
    {"id": "body_name", "text": "John Doe"},
    {"id": "footer_name", "text": "John Doe"},
    {"id": "signature", "text": "John Doe"}
  ]
}

This creates several issues:

• Repetitive and error-prone

• Risk of inconsistency (typos, different values)

• Hard to maintain when values change

• Verbose API requests

The Solution With Variables:

Define the value once and reference it everywhere:

{
  "modifications": [
    {"id": "header_name", "text": "{{user_name}}"},
    {"id": "body_name", "text": "{{user_name}}"},
    {"id": "footer_name", "text": "{{user_name}}"},
    {"id": "signature", "text": "{{user_name}}"}
  ],
  "variables": {
    "user_name": "John Doe"
  }
}

Creating variables

Variables are defined in your template's configuration. Inside the template editor, you'll see a "Variables" button at the top bar.

Variable types

Variables support three types:

• string

• number

• boolean (False/True)

Defining variables

You'll need to specify the variable name and they have to be unique. Each variable also requires default value.

Using variables

Currently, variables can only be used with the API. Soon, we are extending this to other integrations.

With API

Apart from the modifications field, you can now specify variables field to define the value that should be assigned to the variable. If you don't specify it here, the default value will be used.

Example of using variables with image generation API

{
  "template": "a2bdf44a-5fba-467d-a4d2-8685b1c4f8f5",
  "modifications": [
    {
      "name": "image_1",
      "src": "/images/image-placeholder.jpg",
      "visible": "{{visibility}}"
    },
    {
      "name": "text_2",
      "text": "Hello {{name}}!",
      "visible": "{{visibility}}"
    }
  ],
  "variables": {
    "visibility": false,
    "name": {
      "type": "string",
      "value": "John Doe"
    }
  }
}

The above example shows that we can control both layers' visibility by setting the variable visibility to false.

Also, note that for variable name, we are declaring and defining variables right from the API without using the template editor. In this case, the name variable is only temporary for the current request.

Without variables, you'll need to set them individually.

Variables are useful for cases where you want to link some fields together. A common use case is to hide and show certain fields together.

Variable Resolution

Variables are resolved in two places during generation:

1. Template Resolution: Variables in the template itself are replaced with provided values

2. Modification Resolution: Variables in the modifications array are replaced with provided values

Resolution Order

1. Use value from request's variables object if provided

2. Fall back to template's default value if defined

3. Return error if variable is required but not provided and has no default

Type Validation

The system validates that provided values match the declared variable type:

• Text variables must receive string values

• Number variables must receive numeric values (integers or floats)

• Boolean variables must receive boolean values (true/false)

Type mismatches will result in an error.

You can look at the Console of each template to see the expected type for each field.

number variable type refers to either integer and float in the console page. array type is not supported for variables.