Document Data Prefill

POST /document/prebuild

This service allows you to create a signing process from a custom document by prefilling only part of the information and sending it to a recipient who will complete the remaining data. Unlike document creation, where all the values needed to generate the document are sent at once, here the process is created in an in progress state with the prefilled fields and waits for the recipient to fill in the pending information.

It is useful when one party (for example, your company) already knows some of the document's data and wants to leave it completed, while the other party (the recipient) must provide the rest before signing.

info

The fields that can be prefilled are defined in the custom document's configuration. Before integrating this endpoint you may need to query the document variables and, if applicable, how to define signature positions and identity validation configurations.

Steps to prefill a document:

1. Query the custom document: Identify the custom document you want to use and obtain its _id.
2. Identify the prefillable variables: Query the document variables to find out which ones you can prefill.
3. Build the preBuild array: Assemble the list of key / value pairs with the data you want to leave filled in.
4. Send the request: Make the request (POST) indicating the recipient (emailTo) who will complete the remaining information.

Below are the necessary parameters for this service, along with examples and possible system responses.

---

Authentication

Include your private key in the Authorization header.

Authorization: prk_xxx...

---

Prefill Parameters

Name	Type	Required	Description
email	String	Required	Email of the process creator.
name	String	Required	Name of the document process.
document	String	Required	ID of the custom document from which the process is created.
preBuild	Array	Required	List of objects with the data prefilled in the document. Only the variables enabled for prefill in the document configuration are accepted.
preBuild[x].key	String	Required	Name of the variable registered in the document.
preBuild[x].value	String	Required	Value assigned to the variable.
sign	Boolean	Required	Defines if the process will be done through signature. If false, the document will be sent by email for printing.
notification	Boolean	Required	Defines if the recipient (emailTo) is notified once the process is created so they can complete the information.
emailTo	String	Required	Email of the recipient who must complete the remaining data of the document.
folder	String	Conditional	Path of the folder where the process will be saved. The folder must exist and belong to the process creator.
camera	Boolean	Optional	Indicates if photo validation is mandatory, default is false.
otpCode	Boolean	Optional	Indicates if OTP code validation is mandatory, default is false.
options	Object	Optional	Specifications of the identity validation. See more
expiredDate	Date	Optional	Document expiration date. It must be greater than 3 days from the creation date and is sent in JSON Date format.

---

🧪 Usage Examples

tip

You can copy any of the examples according to your preferred language.

• In preBuild you should only send the variables you want to prefill; the recipient will complete the rest.
• Phone numbers must include the country code, for example: +57, +1, +52...

Data prefill

curl

curl --location 'https://dev.auco.ai/v1.5/ext/document/prebuild' \
--header 'Authorization: prk_private_key_company' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "example@auco.ai",
    "name": "Employment contract - Juan Pérez",
    "document": "64823dc5ce28a265e02d68f3",
    "sign": true,
    "notification": true,
    "emailTo": "juan.perez@example.com",
    "preBuild": [
        {
            "key": "company_name",
            "value": "Auco SAS"
        },
        {
            "key": "position",
            "value": "Backend Developer"
        }
    ]
}'

Python

import requests
import json

url = "https://dev.auco.ai/v1.5/ext/document/prebuild"

payload = json.dumps({
  "email": "example@auco.ai",
  "name": "Employment contract - Juan Pérez",
  "document": "64823dc5ce28a265e02d68f3",
  "sign": True,
  "notification": True,
  "emailTo": "juan.perez@example.com",
  "preBuild": [
    {
      "key": "company_name",
      "value": "Auco SAS"
    },
    {
      "key": "position",
      "value": "Backend Developer"
    }
  ]
})
headers = {
  'Authorization': 'prk_private_key_company',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Node.js

const axios = require('axios');
let data = JSON.stringify({
  email: 'example@auco.ai',
  name: 'Employment contract - Juan Pérez',
  document: '64823dc5ce28a265e02d68f3',
  sign: true,
  notification: true,
  emailTo: 'juan.perez@example.com',
  preBuild: [
    {
      key: 'company_name',
      value: 'Auco SAS',
    },
    {
      key: 'position',
      value: 'Backend Developer',
    },
  ],
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://dev.auco.ai/v1.5/ext/document/prebuild',
  headers: {
    Authorization: 'prk_private_key_company',
    'Content-Type': 'application/json',
  },
  data: data,
};

axios
  .request(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

---

📥 Response Examples

Process creation

{
  "document": "DOCUMENTCODE"
}

---

⚠️ Error Responses

Code	Description
400	Missing parameters, the document does not exist, or a variable does not match the document configuration
401	Invalid or missing authentication