Skip to content
Documentation menu

Parameters

Typed inputs of a template, bound to SQL variables, passed by name through the API and validated before rendering.

Parameters are the inputs of a template: the id of the invoice to print, a date range, a language, a flag. Your application passes them by name when it renders the document; datasets use them as SQL bind variables and the layout can print or test them.

What a parameter is

You define parameters in the Designer's Parameters panel:

namestringrequired
Letters, digits and _, not starting with a digit, unique in the template. It is the name your application sends (DOCUMENT_ID).
typeenum
string, integer, decimal, date, dateTime or boolean (below). Default string.
requiredboolean
A required parameter without a value and without a default makes the render fail.
defaultvalue
Used when the caller sends no value.
test valuevalue
Used only in the Designer: dataset tests, previews and render tests.
descriptionstring
Shown in the API explorer and returned by GET /v1/templates/{code}.
logboolean
Records the value in the run log (on by default). Turn it off for confidential values.

A bind variable without a matching parameter can become one with Create parameter in the dataset editor: it is added as required, with a type guessed from its name.

Types and values

stringtext
Any scalar value, used as text.
integerwhole number
A JSON integer or a text with an integer: 18425 or "18425".
decimalnumber
A JSON number or a text with a dot as decimal separator: 12.5 or "12.5".
datedate
ISO text: "2026-10-31".
dateTimedate and time
ISO text: "2026-10-31T14:30", with seconds, or with a space instead of T; with Z or an offset the time is kept as written.
booleanyes/no
true / false, or 1 / 0 (also as text).

An empty text means "no value" for every type except string. Defaults and test values are written in the same invariant format (ISO dates, a dot for decimals, true/false); an invalid default is reported when you save.

Parameters in SQL

In a dataset, write the parameter as a bind variable, :NAME. Prynt binds the value with its type; it is never pasted into the SQL text, so a value cannot change the query (no SQL injection), and the database can reuse the execution plan.

Dataset with parameters
SELECT r.RIGA, r.ARTICOLO, r.QUANTITA  FROM DDT_RIGHE r WHERE r.DDT_ID = :DOCUMENT_ID   AND r.DATA >= :FROM_DATE   AND r.DATA <  :TO_DATE + 1          -- the whole last day   AND (:CUSTOMER IS NULL OR r.CLIENTE = :CUSTOMER)
  • A null value is bound as a typed NULL: optional filters are written (:P IS NULL OR column = :P).
  • A date parameter arrives as a date at midnight: to include the whole last day of a range on date-and-time columns, compare with < :TO_DATE + 1.
  • On Oracle, a boolean arrives as the number 1 or 0, and an empty text is NULL. See Oracle.
  • Never build SQL from parameter values: there is no way to do it, by design.

Parameters in the layout

In expressions a parameter is Params.NAME: print it in a text ({{Params.DOCUMENT_ID}}), use it in a condition (Visible if Params.SHOW_PRICES) or in the number of copies of a label (Params.COPIES).

Passing parameters through the API

Send the values in the parameters object of POST https://api.prynt.it/api/v1/render, by name, with the JSON types above:

Request body
{  "template": "DELIVERY_NOTE",  "parameters": {    "DOCUMENT_ID": 18425,    "FROM_DATE": "2026-10-01",    "TO_DATE": "2026-10-31",    "CUSTOMER": null,    "SHOW_PRICES": true  },  "context": { "company": "01", "user": "erp-batch", "language": "en" }}
  • Names are not case-sensitive: document_id and DOCUMENT_ID are the same parameter.
  • Parameters the template does not declare are ignored.
  • GET /v1/templates/{code} returns the parameters of the published version with their types, and a JSON Schema of the parameters object you can validate against. The API explorer writes the request for you with the real names.

Validation and errors

Prynt converts and checks every value against the declared type before running any query. A missing required parameter (with no default) or a value that cannot be converted answers 400 with errorCode PARAMETER_INVALID, the name of the parameter and the reason: missing or invalid.

400 PARAMETER_INVALID
HTTP/1.1 400 Bad RequestContent-Type: application/problem+json {  "title": "Invalid parameter",  "status": 400,  "detail": "…",  "errorCode": "PARAMETER_INVALID",  "parameter": "DOCUMENT_ID",  "reason": "missing",  "correlationId": "4bf92f3577b34da6a3ce929d0e0e4736"}

Fix the request, not the template, and do not retry the same call. In the Designer, the preview shows the same error next to the parameter's field.

System values and context

Besides parameters, a template can use system values: $DITTA (the company), $USER, $LANGUAGE, $DATE and $NOW in expressions, :DITTA, :USER, :LANGUAGE, :DATE, :NOW as bind variables. Company, user and language come from the optional context of the render request (defaults: the company set in the workspace settings, the name of the API key, and Italian); DATE and NOW are the server's date and time. The language also decides number and date formats and the translations of the template.

A parameter hides a system value

A parameter named like a system value (DITTA, USER…) takes its place in bind variables without an explicit binding. Choose different names unless that is what you want.

Confidential values

The Log option

By default the values of parameters are recorded with each run, to reproduce a problem later. Turn Log off for values that must not be stored (a tax code, a personal id): they are then kept out of the run log, the file name and the logged error messages.