JSON Configuration

Complete reference for the JSON configuration file — root structure, question types, validations, conditionals, and signature profiles.

Localization and defaults

The platform assumes Colombia by default in several types. Some accept an override via the country attribute; others are fixed.

Type	Default	Override
`currency`	COP	Not supported — always formatted as Colombian pesos
`nit`	Colombia	Not supported — Colombian NIT format fixed (`XXXXXX-X`)
`identification`	CO	`country: "MX" \| "CL" \| "SV" \| ...` (see the Identification section below)
`phone`	Auto-detects	`country: "co" \| "mx" \| ...` (ISO2 lowercase)
`department`	CO	`country: "CO" \| "MX" \| ...`
`date`	Spanish, Gregorian calendar	Not localizable — renders as `"15 de enero de 2024"`

Non-Colombian markets

If your use case requires USD or another currency format, currency is not the right type — use number and format the prefix manually in the HTML. Similarly, nit applies only to Colombia; for tax IDs from other countries use text with an appropriate regex.

Main Properties of the Root Object

{
  "name": "My First Automation",
  "preBuild": false,
  "username": "example_user",
  "config": [],
  "signatureProfile": [],
  "sign": []
}

Property	Type	Required	Description
`name`	string	Required	Name of the automation
`config`	array	Required	Array of questions for the user
`signatureProfile`	array	Required	Definition of signers and approvers
`sign`	array	Required	Names of required questions
`preBuild`	boolean	Optional	If `true`, includes automatic pre-fill
`username`	string	Optional	Owner username
`build`	number	Server-managed	SDK cache version. Do not set it manually — the server auto-increments it when you update the template to invalidate the SDK's cache on clients.

`preBuild` Property - Automatic Pre-fill

When preBuild is true, you must include preBuildData. This field enables automatic pre-filling of the template: some fields are completed in advance so the user only needs to finish filling out the document.

In preBuildData, you declare the questions that will be pre-filled in this first instance. The last element of the array must be the email of the end user, who will receive the completion request by email.

{
  "preBuild": true,
  "preBuildData": ["buyer_name", "buyer_email", "end_user_email"]
}

`config` and its question types

In this section, all the questions that the user must fill out to generate the document for signature are added.

info

Each question in config is an object with specific properties. It always requires name, description, and type.
Questions can also have a default value by adding the value attribute (only meaningful on clausula, select, and searchlist).

{
  "name": "unique_identifier",
  "description": "Text the user sees",
  "type": "question_type"
}

Question Types Summary

Type	Input UI	Stored value	Rendered in span
`text`	free text	`"str"`	as-is
`name`	text	`"str"`	UPPERCASE
`email`	email	`"lower@x.com"`	as-is
`phone`	international phone input	`"+573001234567"`	as-is
`number`	numeric input	`"50000"`	`"50,000"` (or with written text if `addText`)
`currency`	numeric input	`"50000"`	`"$50,000 (FIFTY THOUSAND PESOS)"`
`date`	date picker	`"2024-01-15"`	`"15 de enero de 2024"`
`nit`	numeric input	`"9001234567"`	`"900123456-7"` (auto-formatted)
`identification`	country + doc type + number	`"CC 1084340519"` (two parts)	full string
`department`	territorial dropdown	`"Antioquia"`	as-is
`select`	simple dropdown	`"option_value"`	matching `options[i].label`
`searchlist`	dropdown with search	`"option_value"`	matching `options[i].label`
`clausula`	dropdown with conditional spans	`"option_value"`	shows `<span name="question_value">`
`check`	multi-checkbox	`select: ["a","b"]` array	`"a, b"` (comma-joined)
`image`	file upload	base64 data URI	`<img src="..." class="object-contain"/>`
`signature`	drawn / typed signature	base64 or string	`<img>` or `<span class="text-sign">`
`request`	text input + external validation	`"str"`	as-is (plus fields pre-filled by service)

request requires extra backend integration and is covered in its own page: see Request Type.

Free Text (`text`)

Accepts any text without restrictions.

{
  "name": "product_description",
  "description": "Briefly describe the product",
  "type": "text"
}

Supports maxlength and regex validations (see Validation Properties).

Name (`name`)

Same as text, but automatically converts to uppercase in the HTML.

{
  "name": "buyer_name",
  "description": "Enter your full name",
  "type": "name"
}

info

Output example:

User enters: john doe
Displayed in HTML: JOHN DOE

Number (`number`)

Only accepts numeric values. Rendered with thousand separators.

{
  "name": "items_quantity",
  "description": "How many items do you want?",
  "type": "number"
}

With written text (addText):

{
  "name": "items_quantity",
  "description": "How many items do you want?",
  "type": "number",
  "addText": true
}

Supports min and max numeric bounds.

`addText`	User enters `5000`	Rendered as
(omit)	`5000`	`5,000`
`true`	`5000`	`5,000 (FIVE THOUSAND)`

Currency (`currency`)

Automatically formats as currency (Colombian pesos by default) with written amount.

{
  "name": "total_amount",
  "description": "Enter the value in pesos",
  "type": "currency"
}

Without written text (removeText):

{
  "name": "total_amount",
  "description": "Enter the value in pesos",
  "type": "currency",
  "removeText": true
}

`removeText`	User enters `50000`	Rendered as
(omit)	`50000`	`$50,000 (FIFTY THOUSAND PESOS)`
`true`	`50000`	`$50,000`

Email (`email`)

Validates that it is a correct email.

{
  "name": "buyer_email",
  "description": "Enter your email address",
  "type": "email"
}

Phone (`phone`)

Validates phone number according to the selected country code.

{
  "name": "buyer_phone",
  "description": "Enter your phone number",
  "type": "phone"
}

Country-specific:

{
  "name": "buyer_phone",
  "description": "Enter your Colombian phone",
  "type": "phone",
  "country": "co"
}

When country is set, the input is locked to that country's dial code.

Date (`date`)

Shows a calendar to select a date.

{
  "name": "delivery_date",
  "description": "Select the delivery date",
  "type": "date"
}

Supports min, max, subYears, subDays, and afterSubYears for range constraints. See Validation Properties.

NIT (`nit`)

Colombian tax ID input. Automatically formats as XXXXXX-X in the rendered document.

{
  "name": "company_tax_id",
  "description": "Enter the company NIT",
  "type": "nit"
}

User enters	Rendered as
`9001234567`	`900123456-7`
`8301234`	`830123-4`

Identification (`identification`)

Structured signer identification input. The user picks a country, an ID type, and enters the number. The stored value has two parts separated by a space: "{ID_TYPE} {NUMBER}".

{
  "name": "buyer_id",
  "description": "Enter the buyer's identification",
  "type": "identification",
  "country": "CO"
}

User action	Stored value	Rendered in span
Picks `CC`, enters `1084340519`	`"CC 1084340519"`	`CC 1084340519`
Picks `CE`, enters `A0123456`	`"CE A0123456"`	`CE A0123456`

When to use

Use identification for signer documents instead of text or number. The runtime splits the value into identificationType and identification when composing the signer profile, which is required for identity verification flows.

Supported countries: Colombia (CC, CE, PPT, DL, PASSPORT), México (CURP, PASSPORT), Chile (RUT, RUN, PASSPORT), El Salvador (DUI, PASSPORT), Costa Rica (CCCR, PASSPORT), Perú (DNI, PASSPORT), Uruguay (CI, PASSPORT), Venezuela (CI, PASSPORT), Honduras (DNI, PASSPORT), Panamá (CI, PASSPORT), España (DNI, PASSPORT), Ecuador (CI, PASSPORT), Aruba (CI, PASSPORT).

Department (`department`)

Dropdown of territorial divisions (departments / states) for the configured country. Defaults to Colombia.

{
  "name": "buyer_department",
  "description": "Select the buyer's department",
  "type": "department",
  "country": "CO"
}

The stored value is the department's full name (e.g. "Antioquia").

Simple List (`select`)

Simple dropdown. Does not trigger conditional visibility of other questions.

{
  "name": "document_type",
  "description": "Select the document type",
  "type": "select",
  "value": "id_card",
  "options": [
    { "name": "National ID Card", "label": "National ID Card", "value": "id_card" },
    { "name": "Foreign ID Card",  "label": "Foreign ID Card",  "value": "foreign_id" }
  ]
}

Corresponding HTML:

<span name="document_type">_______________</span>

The SDK automatically places the option's label into the span.

Searchable List (`searchlist`)

Dropdown with a search input. Identical to select in JSON — only the UX differs. Use when the list has more than ~10 options.

{
  "name": "country_of_birth",
  "description": "Select your country of birth",
  "type": "searchlist",
  "options": [
    { "name": "Argentina", "label": "Argentina", "value": "AR" },
    { "name": "Brazil",    "label": "Brazil",    "value": "BR" }
  ]
}

HTML is a single <span name="country_of_birth"> just like select.

Clause List (`clausula`)

Dropdown with predefined options. Allows limiting other questions via prereq.

{
  "name": "document_type",
  "description": "Select the document type",
  "type": "clausula",
  "value": "id_card",
  "options": [
    { "name": "National ID Card", "value": "id_card" },
    { "name": "Foreign ID Card",  "value": "foreign_id" },
    { "name": "Passport",         "value": "passport" }
  ]
}

Corresponding HTML:

<span name="document_type_id_card">ID Card</span>
<span name="document_type_foreign_id" hidden>Foreign ID</span>
<span name="document_type_passport" hidden>Passport</span>

Rules:

One <span> is created per option, with name = {question_name}_{option_value}.
The element matching the default value must not have hidden.
All other options must have hidden.
The SDK toggles visibility as the user picks different options.

Multi-checkbox (`check`)

Multiple-choice field rendered as a comma-joined list.

{
  "name": "included_services",
  "description": "Select included services",
  "type": "check",
  "values": ["cleaning", "maintenance", "insurance"]
}

values is an array of strings — NOT options with objects

The check type is the only type that uses a flat values: ["a", "b"] array instead of an options: [{...}] structure. Using options here will not render anything.

Rendered output: <span name="included_services">cleaning, maintenance</span> (if user checks those two).

Image (`image`)

File upload input (PNG or JPEG, max 8 MB). The stored value is a base64 data URI, and the span is replaced with an <img> element.

{
  "name": "id_photo",
  "description": "Upload a photo of your ID",
  "type": "image"
}

Corresponding HTML:

<span name="id_photo">___________</span>

When filled, the span becomes:

<span name="id_photo"><img src="data:image/png;base64,..." class="object-contain"/></span>

Signature (`signature`)

Captures a signature drawn on canvas or typed with a signature-style font. Always mandatory (cannot be left blank).

{
  "name": "buyer_signature",
  "description": "Draw your signature",
  "type": "signature",
  "allow": ["draw", "font"]
}

The allow array restricts the capture modes available to the user:

["draw"] — only hand-drawn on canvas
["font"] — only typed in a signature-style font
["draw", "font"] — both allowed

Signature type vs signer signature

This is different from the signature placeholder used by signatureProfile. Use signature questions when you need a second inline signature inside the document body (e.g., initials on each clause). For the signer's main signature, use <div id="buyer" class="sign-margin"> plus signatureProfile — see HTML Configuration.

Request (`request`)

Text input that validates its value against an external HTTP endpoint and uses the response to pre-fill other fields in the document.

Covered in a dedicated page because it requires backend integration: Request Type →.

Validation Properties

All question types support a set of optional validation properties to constrain user input.

Property	Applies to	Description
`maxlength`	`text`, `name`, `phone`	Maximum number of characters.
`regex`	any text input	JavaScript regex the value must match. Example: `"^[A-Z]{3}\\d{3}$"`
`min`	`number`, `currency`	Minimum numeric value (as string).
`max`	`number`, `currency`, `date`	Maximum numeric or date value.
`subYears`	`date`	Minimum age in years (e.g. `18` means the date must be ≥ 18 years ago).
`subDays`	`date`	Minimum distance in days from today.
`afterSubYears`	`date`	Date must be at least this many years in the future.
`country`	`phone`, `identification`, `department`	ISO2 country code (e.g. `"CO"`, `"MX"`).
`groupQuestion`	`number`	Validates that a group of fields sums up to a maximum. See below.

Example: date of birth for adults only

{
  "name": "birth_date",
  "description": "Enter your date of birth",
  "type": "date",
  "subYears": 18
}

Example: strict alphanumeric code

{
  "name": "reference_code",
  "description": "Enter the reference code (format ABC-1234)",
  "type": "text",
  "regex": "^[A-Z]{3}-\\d{4}$",
  "maxlength": 8
}

Example: `groupQuestion` (fields must sum to ≤ 100)

[
  {
    "name": "owner_percentage",
    "description": "Owner percentage",
    "type": "number",
    "groupQuestion": {
      "id": "ownership",
      "max": 100,
      "errorMessage": "Percentages must not exceed 100%"
    }
  },
  {
    "name": "partner_percentage",
    "description": "Partner percentage",
    "type": "number",
    "groupQuestion": {
      "id": "ownership",
      "max": 100,
      "errorMessage": "Percentages must not exceed 100%"
    }
  }
]

All questions that share the same groupQuestion.id are validated together: their sum must not exceed max.

Conditional Questions with `prereq`

The prereq property controls the conditional visibility of a question:

k (key): name of the reference question
v (value): required value in the reference question to show the current question

Structure

"prereq": [
  { "k": "reference_question_name", "v": "required_value" }
]

Multiple entries are combined with AND (all must match).

Important

The question referenced in k must be of type clausula. Only clausula triggers conditional visibility.

Complete Example

[
  {
    "name": "document_type",
    "description": "Select the buyer's document type",
    "type": "clausula",
    "value": "id_card",
    "options": [
      { "name": "National ID Card", "value": "id_card" },
      { "name": "Foreign ID Card",  "value": "foreign_id" }
    ]
  },
  {
    "name": "id_card_number",
    "description": "Enter the national ID card number",
    "type": "number",
    "prereq": [{ "k": "document_type", "v": "id_card" }]
  },
  {
    "name": "foreign_id_number",
    "description": "Enter the foreign ID number",
    "type": "number",
    "prereq": [{ "k": "document_type", "v": "foreign_id" }]
  }
]

`prereqOptionals` — OR logic

To show a question when the reference matches any of several values, use prereqOptionals alongside prereq. Each entry has the format {question_name}_{option_value}.

{
  "name": "company_tax_id",
  "description": "Company NIT",
  "type": "nit",
  "prereq": [{ "k": "client_type", "v": "company" }],
  "prereqOptionals": [
    "client_type_company",
    "client_type_consortium"
  ]
}

The question appears when client_type is either company or consortium.

Signature Profiles (`signatureProfile`)

Defines who signs the document and their associated data. This object does not store raw signer data — it stores references to the questions that hold each signer's information.

Property	Type	Required	Description
`name`	String \| String[]	Required	Name of the question holding the signer's name. Can be an array of question names to concatenate (see below).
`identification`	String	Required	Name of the question for identification. Multiple options allowed with `\|`.
`email`	String	Required	Name of the question for the signer's email
`phone`	String	Required	Name of the question for the phone (recommended for OTP)
`type`	String	Required	Unique identifier, used as `id` (or `name`) in the Complete HTML

Example - One Signer

{
  "name": "buyer_name",
  "identification": "buyer_id",
  "email": "buyer_email",
  "phone": "buyer_phone",
  "type": "buyer"
}

Example - Multiple Identifications

If you have multiple identification questions (ID Card, Foreign ID, Passport), separate with | (pipe). The runtime picks whichever has a value.

{
  "name": "seller_name",
  "identification": "seller_id_card|seller_foreign_id|seller_passport",
  "email": "seller_email",
  "phone": "seller_phone",
  "type": "seller"
}

Example - Name as an Array

When the document collects the name in multiple fields (first name + middle name + last name), pass an array of question names. The runtime concatenates them with spaces.

{
  "name": ["buyer_first_name", "buyer_middle_name", "buyer_last_name"],
  "identification": "buyer_id",
  "email": "buyer_email",
  "phone": "buyer_phone",
  "type": "buyer"
}

Signature positioning

For placement of <div> elements in the Complete HTML, see HTML Configuration → Signature Placement.

Required Questions

The sign property is an array with the names of questions that the user cannot skip:

"sign": [
  "buyer_name",
  "buyer_email",
  "buyer_id"
]

info

The user must mandatorily complete the questions registered in sign.
Questions of type signature are automatically mandatory — you do not need to list them in sign.

Key Differences: `clausula` vs `select` vs `searchlist`

Feature	Clausula	Select	Searchlist
Dropdown?	Yes	Yes	Yes, with search input
HTML elements needed	One `<span>` per option	One `<span>`	One `<span>`
Can limit other questions?	✅ Yes	❌ No	❌ No
Can be referenced in `prereq.k`?	✅ Yes	❌ No	❌ No
Options structure	`{name, value}`	`{name, label, value}`	`{name, label, value}`
Recommended option count	2–8	2–10	10+

Localization and defaults​

Main Properties of the Root Object​

preBuild Property - Automatic Pre-fill​

config and its question types​

Question Types Summary​

Free Text (text)​

Name (name)​

Number (number)​

Currency (currency)​

Email (email)​

Phone (phone)​

Date (date)​

NIT (nit)​

Identification (identification)​

Department (department)​

Simple List (select)​

Searchable List (searchlist)​

Clause List (clausula)​

Multi-checkbox (check)​

Image (image)​

Signature (signature)​

Request (request)​

Validation Properties​

Example: date of birth for adults only​

Example: strict alphanumeric code​

Example: groupQuestion (fields must sum to ≤ 100)​

Conditional Questions with prereq​

Structure​

Complete Example​

prereqOptionals — OR logic​

Signature Profiles (signatureProfile)​

Example - One Signer​

Example - Multiple Identifications​

Example - Name as an Array​

Required Questions​

Key Differences: clausula vs select vs searchlist​

Localization and defaults

Main Properties of the Root Object

`preBuild` Property - Automatic Pre-fill

`config` and its question types

Question Types Summary

Free Text (`text`)

Name (`name`)

Number (`number`)

Currency (`currency`)

Email (`email`)

Phone (`phone`)

Date (`date`)

NIT (`nit`)

Identification (`identification`)

Department (`department`)

Simple List (`select`)

Searchable List (`searchlist`)

Clause List (`clausula`)

Multi-checkbox (`check`)

Image (`image`)

Signature (`signature`)

Request (`request`)

Validation Properties

Example: date of birth for adults only

Example: strict alphanumeric code

Example: `groupQuestion` (fields must sum to ≤ 100)

Conditional Questions with `prereq`

Structure

Complete Example

`prereqOptionals` — OR logic

Signature Profiles (`signatureProfile`)

Example - One Signer

Example - Multiple Identifications

Example - Name as an Array

Required Questions

Key Differences: `clausula` vs `select` vs `searchlist`