Template Creation

This service allows you to create custom templates that can later be used to fill out documents for signature.

POST/templateprivate keyprk_

Authentication

Include your private key in the Authorization header.

Authorization: prk_xxx...

Creation Parameters

Name	Type	Description
`name`	String required	Name of the automation.
`description`	String optional	Text describing the template, up to 500 characters.
`config`	Array required	Array of questions for the user. See JSON Configuration.
`signatureProfile`	Array required	Definition of signers and approvers. See Signature Profiles.
`sign`	Array required	Names of required questions.
`preBuild`	Boolean optional	If `true`, includes automatic pre-fill.

The description limit is 500 characters

description is informational: it does not change the template's behavior, and it helps your team recognize what each template is for. If you do not send it, the template has no description. If the text goes over 500 characters, the API responds 400 and does not create the template.

GET /template returns the field, both in the list and in the detail by id.

Creation Examples

curl
Python
Node.js

curl -X POST https://api.auco.ai/v1.5/ext/template \
  -H "Content-Type: application/json" \
  -H "Authorization: prk_private_key_company" \
  -d '{
    "name": "Test document variable modification",
    "description": "Service agreement with a single signer, for the sales team",
    "config": [
      {
        "name": "client_name",
        "type": "name",
        "description": "Enter the client name"
      },
      {
        "description": "Select the document type for the client",
        "name": "client_document_type",
        "type": "clausula",
        "value": "id_card",
        "options": [
          {
            "name": "National ID Card",
            "value": "id_card"
          },
          {
            "name": "Foreign ID Card",
            "value": "foreign_id"
          }
        ]
      },
      {
        "description": "Enter the national ID card number for the client",
        "name": "client_id_card",
        "type": "number",
        "prereq": [
          {
            "k": "client_document_type",
            "v": "id_card"
          }
        ]
      },
      {
        "description": "Enter the foreign ID number for the client",
        "name": "client_foreign_id",
        "type": "number",
        "prereq": [
          {
            "k": "client_document_type",
            "v": "foreign_id"
          }
        ]
      },
      {
        "name": "client_email",
        "type": "email",
        "description": "Enter the client email"
      },
      {
        "name": "client_phone",
        "type": "phone",
        "description": "Enter the client phone"
      }
    ],
    "sign": [
      "client_name",
      "client_id_card",
      "client_foreign_id",
      "client_email",
      "client_phone"
    ],
    "signatureProfile": [
      {
        "email": "client_email",
        "phone": "client_phone",
        "identification": "client_id_card|client_foreign_id",
        "name": "client_name",
        "type": "client"
      }
    ]
  }'

import requests
import json

template_data = {
    "name": "Test document variable modification",
    "description": "Service agreement with a single signer, for the sales team",
    "config": [
        {
            "name": "client_name",
            "type": "name",
            "description": "Enter the client name"
        },
        {
            "description": "Select the document type for the client",
            "name": "client_document_type",
            "type": "clausula",
            "value": "id_card",
            "options": [
                {
                    "name": "National ID Card",
                    "value": "id_card"
                },
                {
                    "name": "Foreign ID Card",
                    "value": "foreign_id"
                }
            ]
        },
        {
            "description": "Enter the national ID card number for the client",
            "name": "client_id_card",
            "type": "number",
            "prereq": [
                {
                    "k": "client_document_type",
                    "v": "id_card"
                }
            ]
        },
        {
            "description": "Enter the foreign ID number for the client",
            "name": "client_foreign_id",
            "type": "number",
            "prereq": [
                {
                    "k": "client_document_type",
                    "v": "foreign_id"
                }
            ]
        },
        {
            "name": "client_email",
            "type": "email",
            "description": "Enter the client email"
        },
        {
            "name": "client_phone",
            "type": "phone",
            "description": "Enter the client phone"
        }
    ],
    "sign": [
        "client_name",
        "client_id_card",
        "client_foreign_id",
        "client_email",
        "client_phone"
    ],
    "signatureProfile": [
        {
            "email": "client_email",
            "phone": "client_phone",
            "identification": "client_id_card|client_foreign_id",
            "name": "client_name",
            "type": "client"
        }
    ]
}

def create_template():
    url = "https://api.auco.ai/v1.5/ext/template"
    headers = {
        "Content-Type": "application/json",
        "Authorization": "prk_private_key_company"
    }

    try:
        response = requests.post(
            url,
            json=template_data,
            headers=headers
        )
        response.raise_for_status()

        result = response.json()
        print("Template created successfully!")
        print(f"Template ID: {result['id']}")
        print(f"Mask URL: {result['urls']['mask']}")
        print(f"Complete URL: {result['urls']['complete']}")

        return result

    except requests.exceptions.RequestException as error:
        print(f"Error creating template: {error.response.json() if hasattr(error, 'response') else error}")

if __name__ == "__main__":
    create_template()

const axios = require('axios');

const templateData = {
  name: 'Test document variable modification',
  description: 'Service agreement with a single signer, for the sales team',
  config: [
    {
      name: 'client_name',
      type: 'name',
      description: 'Enter the client name',
    },
    {
      description: 'Select the document type for the client',
      name: 'client_document_type',
      type: 'clausula',
      value: 'id_card',
      options: [
        {
          name: 'National ID Card',
          value: 'id_card',
        },
        {
          name: 'Foreign ID Card',
          value: 'foreign_id',
        },
      ],
    },
    {
      description: 'Enter the national ID card number for the client',
      name: 'client_id_card',
      type: 'number',
      prereq: [
        {
          k: 'client_document_type',
          v: 'id_card',
        },
      ],
    },
    {
      description: 'Enter the foreign ID number for the client',
      name: 'client_foreign_id',
      type: 'number',
      prereq: [
        {
          k: 'client_document_type',
          v: 'foreign_id',
        },
      ],
    },
    {
      name: 'client_email',
      type: 'email',
      description: 'Enter the client email',
    },
    {
      name: 'client_phone',
      type: 'phone',
      description: 'Enter the client phone',
    },
  ],
  sign: ['client_name', 'client_id_card', 'client_foreign_id', 'client_email', 'client_phone'],
  signatureProfile: [
    {
      email: 'client_email',
      phone: 'client_phone',
      identification: 'client_id_card|client_foreign_id',
      name: 'client_name',
      type: 'client',
    },
  ],
};

async function createTemplate() {
  try {
    const response = await axios.post('https://api.auco.ai/v1.5/ext/template', templateData, {
      headers: {
        'Content-Type': 'application/json',
        Authorization: 'prk_private_key_company',
      },
    });

    console.log('Template created successfully!');
    console.log('Template ID:', response.data.id);
    console.log('Mask URL:', response.data.urls.mask);
    console.log('Complete URL:', response.data.urls.complete);

    return response.data;
  } catch (error) {
    console.error('Error creating template:', error.response?.data || error.message);
  }
}

createTemplate();

Response Example

{
    "id": "template_id",
    "urls": {
        "mask": "https://signed_url_mask",
        "complete": "https://signed_url_complete"
    }
}

Uploading HTML Complete and HTML Mask:

In the creation service response, you will find two signed URLs, one for each HTML. They have a lifespan of 120 seconds: after that, they are no longer valid. Have the HTML Complete and HTML Mask files ready before creating the template and upload each one, as is, in a PUT request to its URL.

Upload with Content-Type: binary/octet-stream

The URLs are signed for that content type: if you send another one —for example text/html—, the upload is rejected. Send the file untransformed: in curl use --data-binary, not -d, which strips line breaks.

curl
Python
Node.js

# Upload HTML Mask
curl -X PUT https://signed_url_mask \
  -H "Content-Type: binary/octet-stream" \
  --data-binary @mask.html

# Upload HTML Complete
curl -X PUT https://signed_url_complete \
  -H "Content-Type: binary/octet-stream" \
  --data-binary @complete.html

import requests

def upload_html_files(mask_url, complete_url):
    """
    Uploads HTML files to the signed URLs

    Args:
        mask_url (str): Signed URL for the HTML Mask
        complete_url (str): Signed URL for the HTML Complete
    """
    try:
        # Read HTML files
        with open('mask.html', 'rb') as f:
            mask_html = f.read()

        with open('complete.html', 'rb') as f:
            complete_html = f.read()

        headers = {'Content-Type': 'binary/octet-stream'}

        # Upload Mask HTML
        response_mask = requests.put(mask_url, data=mask_html, headers=headers)
        print(f"Mask HTML uploaded: {response_mask.status_code}")

        # Upload Complete HTML
        response_complete = requests.put(complete_url, data=complete_html, headers=headers)
        print(f"Complete HTML uploaded: {response_complete.status_code}")

    except requests.exceptions.RequestException as error:
        print(f"Error uploading: {error}")

# Usage from the previous response
mask_url = "https://signed_url_mask"
complete_url = "https://signed_url_complete"
upload_html_files(mask_url, complete_url)

const fs = require('fs');
const axios = require('axios');

/**
 * Uploads HTML files to the signed URLs
 * @param {string} maskUrl - Signed URL for the HTML Mask
 * @param {string} completeUrl - Signed URL for the HTML Complete
 */
async function uploadHtmlFiles(maskUrl, completeUrl) {
  try {
    // Read HTML files
    const maskHtml = fs.readFileSync('mask.html');
    const completeHtml = fs.readFileSync('complete.html');

    const headers = { 'Content-Type': 'binary/octet-stream' };

    // Upload Mask HTML
    await axios.put(maskUrl, maskHtml, { headers });
    console.log('Mask HTML uploaded successfully');

    // Upload Complete HTML
    await axios.put(completeUrl, completeHtml, { headers });
    console.log('Complete HTML uploaded successfully');
  } catch (error) {
    console.error('Error uploading files:', error.message);
  }
}

// Usage from the previous response
const maskUrl = 'https://signed_url_mask';
const completeUrl = 'https://signed_url_complete';
uploadHtmlFiles(maskUrl, completeUrl);

The URLs expire in 120 seconds

If they expire before you upload the files, call PUT /template with the template's id to get new URLs. Do not call POST /template again: you would create another template.

⚠️ Error Responses

Errors come with the body { "message": "..." }.

Code	Description
400	Invalid body: `PAYLOAD_NOT_VALID` (the body is not JSON), `PROFILE_FIELD_NOT_FOUND: <field>` (a signer's `email` or `phone` is neither a `config` question nor a `preFill` field), `PROFILE_FIELD_TYPE_INVALID: <field> must be type <type>` (it points to a question of another type), or the validator's message
401	Invalid or missing authentication

The validator's message names the failing field, for example "name" is required, "config[0].maxLength" is not allowed, or "signatureProfile[0].name" must be a string. See the rules for each field in JSON Configuration.

Authentication​

Creation Parameters​

Creation Examples​

Response Example​

Uploading HTML Complete and HTML Mask:​

⚠️ Error Responses​