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",
  "description": "Service agreement with a single signer, for the sales team",
  "preBuild": false,
  "config": [],
  "signatureProfile": [],
  "sign": []
}

Property	Type	Required	Description
`name`	string	Required	Name of the automation
`description`	string	Optional	Text describing the template, up to 500 characters. Informational only: `GET /template` returns it and it does not affect the fill-out flow
`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
`files`	array	Optional	Attachments requested from participants with `package: true`. See Attachments
`build`	number	Server-managed	SDK cache version. Do not send it: the API rejects the request if you include it. 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"]
}

Attachments (`files`)

Lists the documents requested from the participant with package: true in signatureProfile: a copy of their ID, a certificate, a receipt.

"files": [
  { "name": "Copy of ID", "approve": "pending" },
  { "name": "Bank certificate", "approve": "pending", "optional": true },
  { "name": "Co-signer ID", "approve": "pending", "preReq": "has_cosigner" }
]

Name	Type	Description
`name`	String required	Document name, as the participant sees it.
`approve`	String required	Always `"pending"`.
`optional`	Boolean optional	`true` lets the participant continue without uploading it. Without `optional`, the attachment is required.
`preReq`	String optional	Name of a yes/no `clausula` question (options `s` and `n`). The attachment is only requested if the answer is `s`.

`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"
}

From today onward (min: "now"):

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

With min: "now" the calendar opens with today's date already selected and does not allow past dates.

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 name="buyer" class="sign-margin"> plus signatureProfile — see HTML Configuration.

The exception is signing on the spot: if you reference the question from signatureProfile[].signature, that signature becomes the signer's own, captured inside the form. See Signature Profiles.

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	Type	Applies to	Description
`maxlength`	Number (integer ≥ 1)	`text`, `name`, `email`, `nit`, `request`, `phone`	Maximum number of characters.
`regex`	String	any text input	JavaScript regex the value must match. Example: `"^[A-Z]{3}\\d{3}$"`
`min`	String or Number	`number`, `currency`, `date`	On `number` and `currency`, minimum value. On `date`, minimum date (`"2024-01-15"`) or `"now"`: preselects today's date and blocks past dates.
`max`	String or Number	`number`, `currency`, `date`	On `number` and `currency`, maximum value. On `date`, maximum date (`"2024-12-31"`).
`subYears`	Number (integer ≥ 0)	`date`	Minimum age in years (e.g. `18` means the date must be ≥ 18 years ago).
`subDays`	Number (integer ≥ 0)	`date`	The date must be at least this many days before today.
`afterSubYears`	Number (integer ≥ 0)	`date`	The date cannot be earlier than this many years ago (e.g. `5` blocks dates more than 5 years back).
`addText`	Boolean	`number`	Adds the value written out in words: `5.000 (CINCO MIL)`. See Number.
`country`	String	`phone`, `identification`, `department`	ISO2 country code (e.g. `"CO"`, `"MX"`).
`allow`	Array<String>	`signature`	Allowed capture modes: `"draw"`, `"font"`, or both. At least one. See Signature.
`groupQuestion`	Object	`number`	Validates that a group of fields sums up to a maximum: `id` and `max` required, `errorMessage` optional. See below.

An unknown attribute rejects the whole template

The API validates each question against a closed list of attributes: the ones in this table, plus name, description, type, value, help, options, select, values, endpoint, removeText, prereq, and prereqOptionals. If a question carries any other attribute —a misspelled name, such as maxLength—, POST and PUT /template respond 400 and save nothing. The same happens with an out-of-range value, such as a maxlength of 0 or an empty allow.

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.

Name	Type	Description
`name`	String required	Name of the question holding the signer's name.
`identification`	String optional	Name of the question for identification. Multiple options allowed with `\|`.
`email`	String conditional	Name of the `email` question holding the signer's email, or of a `preFill` field. Send `email`, `phone`, or both, unless the signer has `signature`.
`phone`	String conditional	Name of the `phone` question holding the signer's phone (recommended for OTP), or of a `preFill` field. Send `email`, `phone`, or both, unless the signer has `signature`.
`type`	String required	Unique signer identifier. It is the `name` of the signer's signature slot in the Complete HTML: `<div name="…" class="sign-margin">`.
`role`	String optional	`"APPROVER"` makes the participant approve the document instead of signing it. Without `role`, they are a signer.
`order`	Number optional	Signing turn. With `order`, signing is sequential: the participant gets their invitation once those with an earlier turn have signed.
`package`	Boolean optional	`true` if this participant is asked for attachments. The template must declare which ones in `files`.
`country`	String optional	A fixed value, not a question name: ISO2 code of the country of the signer's document (e.g. `"CO"`). Use it together with `identificationType` when identification is asked with a question that is not of type `identification`, which already carries country and type.
`identificationType`	String optional	A fixed value, not a question name: the signer's document type (e.g. `"CC"`). Same case as `country`.
`signature`	String optional	Name of a `type: "signature"` question in `config` the signer uses to sign inside the form (signing on the spot). With `signature`, `email` and `phone` are no longer required.

name is a single question

name must be a string. The API rejects an array of question names with "signatureProfile[0].name" must be a string. If the document collects the name in several fields (first name, middle name, last name), add a name question that asks for the full name and use it as the signer's name.

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"
}

Signer email and phone

email and phone do not carry the signer's data: they carry the name of the field Auco reads it from when it creates the process. That is why POST and PUT /template validate each one against the template:

It must be the name of a config question of the matching type —email for email, phone for phone—, or the name of a preFill field, the template's array of fixed values (name and value).
If the name is neither a question nor a preFill field, the API responds 400 with PROFILE_FIELD_NOT_FOUND: <field>.
If the question exists but has another type —for example, an email pointing to a text question—, it responds 400 with PROFILE_FIELD_TYPE_INVALID: <field> must be type email (or phone).
A signer with neither email nor phone and no signature is rejected with the validator's message: "signatureProfile[0]" must contain at least one of [email, phone].

A text question for the email

If your template asks for the signer's email with a text question, the API rejects it with PROFILE_FIELD_TYPE_INVALID. Change that question's type to email: besides passing validation, the form checks that the email has a valid format.

Signing on the spot (`signature`)

A signer with signature signs while filling out the form, with the signature question you reference. Since nothing is sent to them, they need neither email nor phone; if they have them, they are validated anyway.

The question must exist in config with type: "signature". The API does not check it, so review it before saving.
The convention is to use the same value in all three places: the question's name, the type, and the signer's signature.
The form must be opened with signing on the spot enabled (signNow). Without it, the signature question has no effect on the signer.

{
  "config": [
    {
      "name": "client_name",
      "description": "Enter your full name",
      "type": "name"
    },
    {
      "name": "client",
      "description": "Sign here",
      "type": "signature",
      "allow": ["draw"]
    }
  ],
  "signatureProfile": [
    {
      "name": "client_name",
      "type": "client",
      "signature": "client"
    }
  ]
}

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​

Attachments (files)​

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​

Signer email and phone​

Signing on the spot (signature)​

Required Questions​

Key Differences: clausula vs select vs searchlist​

Localization and defaults

Main Properties of the Root Object

`preBuild` Property - Automatic Pre-fill

Attachments (`files`)

`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

Signer email and phone

Signing on the spot (`signature`)

Required Questions

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