Create a Signature Package

POST /document/many

This service allows you to generate a package of documents from an Auco template or a PDF file. Once the process is completed, you will receive each document with its own signature certificate.

info

Before integrating this endpoint, you may need to see how to define signature positions and identity validation settings.

warning

The documents array must contain at least 2 elements. If you only need a single document, use the POST /document/upload endpoint.

Steps to create a document package through an automated template:

1. Query available templates or custom documents.
2. Obtain the _id of the base document.
3. Query required variables of the selected document.
4. Construct and send the creation request.

info

If you want to do it using a PDF, it is not necessary to send the file in the initial request. At the end, a signed URL will be returned for each document in the package.

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

---

Authentication

Include your private key in the Authorization header.

Authorization: prk_xxx...

---

Creation Parameters

Name	Type	Required	Description
email	String	Required	Email address of the process creator.
document	String	Conditional	ID of the custom document or Auco template. Only required if you want to use a template.
name	String	Required	Name of the document signing process. Required if the process includes document signing.
message	String	Required	Message that will be sent in the body of the email notifying signers or approvers of the document.
subject	String	Required	Subject with which the notification email will be sent to signers or approvers.
folder	String	Conditional	If you want to save this process in a specific folder, specify the path here. The folder must exist and belong to the process creator.
remember	Number	Conditional	Enables automatic reminders with the time interval (in hours) between each notification. Must be a multiple of 3.
expiredDate	Date	Optional	Expiration date of the document. Must be at least 3 days after the process creation date and is sent in JSON Date format.
camera	Boolean	Optional	Indicates if photo validation is required. Default is false.
otpCode	Boolean	Optional	Indicates if OTP code validation is required. Default is false.
options	Object	Optional	Specifies identity validation settings. See more
notification	Boolean	Optional	Defines whether Auco notifies participants once the process is created. Default is true. If set to false, the response includes an id for each signer (grouped by email across all documents) that lets the integrator handle notifications externally.
custom	Object	Optional	Free-form object to send integrator-defined parameters (for example, internal identifiers or metadata). Auco stores it as-is and forwards it in webhook notifications and in the GET /document response, without interpreting or validating its contents. Applies to the whole package.
data	Array	Conditional	Contains all the data required by the template to generate the document. Only required if using a template.
data[x].key	String	Required	Name of the parameter registered in the template.
data[x].value	String	Required	Value assigned to the parameter.
documents *	Array	Required	List of objects, each representing a document in the package.
documents[0].name	String	Required	Name of the document.
documents[0].readers	Array	Optional	List of objects defining participants who are not part of the signing process but should observe each phase of the signing process.
documents[0].readers[x].name	String	Required	Name of the reader.
documents[0].readers[x].email	String	Required	Email address of the reader.
documents[0].signProfile	Array	Required	List of objects containing information for each signer or approver for notification and signing.
documents[0].signProfile[x].name	String	Required	Name of the signer.
documents[0].signProfile[x].email	String	Required	Email address of the signer.
documents[0].signProfile[x].phone	String	Required	Phone number of the signer.
documents[0].signProfile[x].role	String	Conditional	Defines the participant's role, can be 'APPROVER' or 'SIGNER'.
documents[0].signProfile[x].order	String	Conditional	Defines the order in which the notification process for signing or approval will occur.
documents[0].signProfile[x].position	Array	Conditional	Signature positions for this signer on each page. Signature positions can be preloaded in templates. See more in how to define signature positions.
documents[0].signProfile[x].type	Array	Conditional	Name used to identify the signer type if pre-saved in a template, e.g.: 'co-signer'.
documents[0].signProfile[x].label	Boolean	Conditional	Indicates if signature positioning will be done using labels in the PDF.
documents[0].signProfile[x].options	Object	Optional	Allows defining custom validations for a specific signer. To apply validations individually per signer, see more.
documents[0].signProfile[x].camera	Boolean	Optional	If you want individual validations per signer and require photo or video validation, set this parameter to true. Default is false.
documents[0].signProfile[x].otpCode	Boolean	Optional	If you want individual validations per signer and require OTP validation, set this parameter to true. Default is false.
documents[0].signProfile[x].both	Boolean	Optional	If you want individual validations per signer and require the signing process to be possible via WhatsApp and/or email, set this parameter to true. Default is false.
documents[0].signProfile[x].notification	Boolean	Optional	Only applies when the global notification parameter is false. If a signer is sent with notification: true, Auco takes care of notifying them and no id will be assigned in the response.

---

🧪 Usage Examples

tip

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

• Email addresses and phone numbers among signers must not repeat.
• Readers will receive notifications for every update in the signature process.
• Date format: 'DD/MM/YYYY'
• Phone numbers must include the country code, e.g.: +57, +1, +52...

Document Package via PDF

curl

curl --location 'https://dev.auco.ai/v1/ext/document/many' \
--header 'Authorization: prk_e1cd6a01ecdb4b4ea72ec118e33b18de' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Prueba paquete 2 documentos",
    "email": "example@auco.ai",
    "message": "Hola a todos, les comparto el paquete de documentos para la firma",
    "options": {
        "camera": "identification",
        "whatsapp": true
    },
    "camera": true,
    "otpCode": false,
    "documents": [
        {
            "name": "Documento 1",
            "signProfile": [
                {
                    "type": "solicitante",
                    "name": "Firmante 1",
                    "phone": "+573000000000",
                    "email": "example1@auco.ai"
                }
            ]
        },
        {
            "name": "Documento 2",
            "signProfile": [
                {
                    "type": "solicitante",
                    "name": "Firmante 1",
                    "phone": "+573000000000",
                    "email": "example2@auco.ai"
                }
            ]
        }
    ]
}

Python

import requests
import json

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

payload = json.dumps({
  "name": "Prueba notification2",
  "email": "example@auco.ai",
  "message": "Hola a todos, les comparto el paquete de documentos para la firma",
  "options": {
    "camera": "identification",
    "whatsapp": True
  },
  "camera": True,
  "otpCode": False,
  "documents": [
    {
      "name": "Documento 1",
      "signProfile": [
        {
          "type": "solicitante",
          "name": "Firmante 1",
          "phone": "+573000000000",
          "email": "example1@auco.ai"
        }
      ]
    },
    {
      "name": "Documento 2",
      "signProfile": [
        {
          "type": "solicitante",
          "name": "Firmante 1",
          "phone": "+573000000000",
          "email": "example2@auco.ai"
        }
      ]
    }
  ]
})
headers = {
  'Authorization': 'prk_e1cd6a01ecdb4b4ea72ec118e33b18de',
  '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({
  name: 'Prueba notification2',
  email: 'example@auco.ai',
  message: 'Hola a todos, les comparto el paquete de documentos para la firma',
  options: {
    camera: 'identification',
    whatsapp: true,
  },
  camera: true,
  otpCode: false,
  documents: [
    {
      name: 'Documento 1',
      signProfile: [
        {
          type: 'solicitante',
          name: 'Firmante 1',
          phone: '+573000000000',
          email: 'example1@auco.ai',
        },
      ],
    },
    {
      name: 'Documento 2',
      signProfile: [
        {
          type: 'solicitante',
          name: 'Firmante 1',
          phone: '+573000000000',
          email: 'example2@auco.ai',
        },
      ],
    },
  ],
});

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

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

Document Package via Custom Templates

curl

curl --location 'https://dev.auco.ai/v1/ext/document/many' \
--header 'Authorization: prk_e1cd6a01ecdb4b4ea72ec118e33b18de' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Prueba notification2",
    "email": "example@auco.ai",
    "message": "Hola a todos, les comparto el paquete de documentos para la firma",
    "options": {
        "camera": "identification",
        "whatsapp": true
    },
    "camera": true,
    "otpCode": false,
    "documents": [
        {
            "name": "Documento 1",
            "document": "documentId",
            "data": [
                {"key": "signer_nombre", "value":"firmante 1"},
                {"key": "signer_identification", "value":"cc"},
                {"key": "signer_phone", "value":"+573000000000"},
                {"key": "manager_name", "value":"manager 1"}
            ]
        },
        {
            "name": "Documento 2",
            "document": "documentId",
            "data": [
                {"key": "signer_nombre", "value":"firmante 1"},
                {"key": "signer_identification", "value":"cc"},
                {"key": "signer_phone", "value":"+573000000000"},
                {"key": "manager_name", "value":"manager 1"}
            ]
        }
    ]
}'

Python

import requests
import json

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

payload = json.dumps({
  "name": "Prueba notification2",
  "email": "example@auco.ai",
  "message": "Hola a todos, les comparto el paquete de documentos para la firma",
  "options": {
    "camera": "identification",
    "whatsapp": True
  },
  "camera": True,
  "otpCode": False,
  "documents": [
    {
      "name": "Documento 1",
      "document": "documentId",
      "data": [
        {
          "key": "signer_nombre",
          "value": "firmante 1"
        },
        {
          "key": "signer_identification",
          "value": "cc"
        },
        {
          "key": "signer_phone",
          "value": "+573000000000"
        },
        {
          "key": "manager_name",
          "value": "manager 1"
        }
      ]
    },
    {
      "name": "Documento 2",
      "document": "documentId",
      "data": [
        {
          "key": "signer_nombre",
          "value": "firmante 1"
        },
        {
          "key": "signer_identification",
          "value": "cc"
        },
        {
          "key": "signer_phone",
          "value": "+573000000000"
        },
        {
          "key": "manager_name",
          "value": "manager 1"
        }
      ]
    }
  ]
})
headers = {
  'Authorization': 'prk_e1cd6a01ecdb4b4ea72ec118e33b18de',
  '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({
  name: 'Prueba notification2',
  email: 'example@auco.ai',
  message: 'Hola a todos, les comparto el paquete de documentos para la firma',
  options: {
    camera: 'identification',
    whatsapp: true,
  },
  camera: true,
  otpCode: false,
  documents: [
    {
      name: 'Documento 1',
      document: 'documentId',
      data: [
        {
          key: 'signer_nombre',
          value: 'firmante 1',
        },
        {
          key: 'signer_identification',
          value: 'cc',
        },
        {
          key: 'signer_phone',
          value: '+573000000000',
        },
        {
          key: 'manager_name',
          value: 'manager 1',
        },
      ],
    },
    {
      name: 'Documento 2',
      document: 'documentId',
      data: [
        {
          key: 'signer_nombre',
          value: 'firmante 1',
        },
        {
          key: 'signer_identification',
          value: 'cc',
        },
        {
          key: 'signer_phone',
          value: '+573000000000',
        },
        {
          key: 'manager_name',
          value: 'manager 1',
        },
      ],
    },
  ],
});

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

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

---

📥 Response Examples

Document Package via PDF

{
  "id": "packageId",
  "documents": [
    {
      "url": "https://signed_url_to_upload_PDF",
      "name": "Documento 1",
      "code": "CODEDOC1"
    },
    {
      "url": "https://signed_url_to_upload_PDF",
      "name": "Documento 2",
      "code": "CODEDOC2"
    }
  ]
}

info

The signed URL provided in the response is single-use and available only for 5 seconds. It must be used to upload the PDF document in binary format via an HTTP PUT request.

Via Custom Templates

{
  "id": "packageId",
  "documents": [
    {
      "name": "Documento 1",
      "code": "CODEDOC1"
    },
    {
      "name": "Documento 2",
      "code": "CODEDOC2"
    }
  ]
}

🔹 With notification: false

When notification: false is sent, each signer receives an id that the integrator can use to build their own notification flow. Signers are grouped by email: if the same email appears in multiple documents, it receives the same id in all of them.

If a specific signer inside signProfile is marked with notification: true, Auco takes care of notifying them and no id is assigned.

{
  "id": "packageId",
  "documents": [
    {
      "url": "https://signed_url_to_upload_PDF",
      "name": "Documento 1",
      "code": "GNAZED5HTR",
      "signProfile": [
        { "id": "0Q", "name": "Alejandro", "email": "alejandro@auco.ai" },
        { "name": "Rector", "email": "rector@auco.ai" }
      ]
    },
    {
      "url": "https://signed_url_to_upload_PDF",
      "name": "Documento 2",
      "code": "RC0OO75VL7",
      "signProfile": [
        { "id": "0Q", "name": "Alejandro", "email": "alejandro@auco.ai" },
        { "name": "Rector", "email": "rector@auco.ai" }
      ]
    }
  ]
}

Field	Type	Description
documents[x].signProfile	Array	List of signers for the document.
documents[x].signProfile[y].id	String	Unique identifier of the signer. Only present when Auco will not notify that signer.
documents[x].signProfile[y].name	String	Name of the signer.
documents[x].signProfile[y].email	String	Email of the signer.

---

⚠️ Error Responses

Code	Description
400	Missing parameters, or one or more validations do not meet the applicability conditions.
400	DOCUMENTS_MIN_TWO — The documents array must have at least 2 elements. Use /document/upload for a single document.
401	Invalid or missing authentication.