Skip to main content

Create a Signature Package

POST/document/manyprivate keyprk_

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 package-level 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​

NameTypeDescription
emailString requiredEmail address of the process creator.
packageString optionalIdentifier of a package previously put into edit. Sending it overwrites that package instead of creating a new one, keeping its identifier. Resend the full payload: whatever you leave out is removed. Read more
documentString conditionalID of the custom document or Auco template. Only required if you want to use a template.
nameString requiredName of the document signing process. Required if the process includes document signing.
messageString optionalMessage that will be sent in the body of the email notifying signers or approvers of the document.
subjectString optionalSubject with which the notification email will be sent to signers or approvers.
folderString conditionalIf you want to save this process in a specific folder, specify the path here. The folder must exist and belong to the process creator.
rememberNumber conditionalEnables automatic reminders with the time interval (in hours) between each notification. Must be a multiple of 3.
expiredDateDate optionalExpiration date of the document. Must be at least 3 days after the process creation date and is sent in JSON Date format.
cameraBoolean optionalIndicates if photo validation is required. Default is false.
otpCodeBoolean optionalIndicates if OTP code validation is required. Default is false.
optionsObject optionalSpecifies identity validation settings. See more
notificationBoolean optionalDefines whether Auco notifies participants once the process is created. Default is true. It is the default for every signer; each one can override it with signProfile[x].notification. Signers Auco does not notify get an id in the response, grouped by email across all documents, so the integrator can take them to sign on their own.
customObject optionalFree-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.
dataArray conditionalContains all the data required by the template to generate the document. Only required if using a template.
data[x].keyString requiredName of the parameter registered in the template.
data[x].valueString requiredValue assigned to the parameter.
documents *Array requiredList of objects, each representing a document in the package.
documents[0].nameString requiredName of the document.
documents[0].readersArray optionalList 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].nameString requiredName of the reader.
documents[0].readers[x].emailString requiredEmail address of the reader.
documents[0].signProfileArray requiredList of objects containing information for each signer or approver for notification and signing.
documents[0].signProfile[x].nameString requiredName of the signer.
documents[0].signProfile[x].emailString requiredEmail address of the signer. It is what Auco uses to relate them to each document in the package, so it is required even when you notify them over WhatsApp. Omitting it returns SIGNER_EMAIL_REQUIRED.
documents[0].signProfile[x].phoneString optionalPhone number of the signer, with country code. Required if the package uses WhatsApp as its channel.
documents[0].signProfile[x].positionArray conditionalSignature 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].typeArray conditionalName used to identify the signer type if pre-saved in a template, e.g.: 'co-signer'.
documents[0].signProfile[x].labelBoolean conditionalIndicates if signature positioning will be done using labels in the PDF.
documents[0].signProfile[x].notificationBoolean optionalOverrides the global notification for this signer, in either direction: false silences them even if the global is true, and true makes Auco notify them even if the global is false. If the same email appears in several documents with different values, false wins. Only applies to PDF documents; for template documents the per-signer flag is defined in the template's signatureProfile.
Identity validations in packages are global

In this service, identity validation and the signing channel are configured once for the whole package, using camera, otpCode and options at the root of the request, and they apply equally to every participant.

Package creation does not support per-participant identity validations or channel selection. Sending camera, otpCode or options inside signProfile[x] returns the error SIGNER_VALIDATIONS_NOT_SUPPORTED. If you need different validations per participant, create separate processes with POST /document/upload.

A package has no sequential signing and no roles

Every participant in a package is notified at the same time: there are no turns and no approval stages. Sending role or order inside signProfile[x] returns the error SIGNER_SEQUENCE_NOT_SUPPORTED.

If you need some participants to sign before others, or someone to approve before signing starts, create separate processes with POST /document/upload, which does support order and role.

🧪 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 --location 'https://api.auco.ai/v1.5/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"
                }
            ]
        }
    ]
}

Document Package via Custom Templates​

curl --location 'https://api.auco.ai/v1.5/ext/document/many' \
--header 'Authorization: prk_e1cd6a01ecdb4b4ea72ec118e33b18de' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Contract package",
    "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"}
            ]
        }
    ]
}'

📥 Response Examples​

Document Package via PDF​

{
  "id": "packageId",
  "documents": [
    {
      "url": "https://signed_url_to_upload_PDF",
      "name": "Documento 1",
      "code": "CODEDOC1",
      "signProfile": [{ "name": "Firmante 1", "email": "example1@auco.ai" }]
    },
    {
      "url": "https://signed_url_to_upload_PDF",
      "name": "Documento 2",
      "code": "CODEDOC2",
      "signProfile": [{ "name": "Firmante 1", "email": "example2@auco.ai" }]
    }
  ]
}
info

The signed URL provided in the response will only be available for 300 seconds (5 minutes). 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",
      "signProfile": [{ "name": "Firmante 1", "email": "example1@auco.ai" }]
    },
    {
      "name": "Documento 2",
      "code": "CODEDOC2",
      "signProfile": [{ "name": "Firmante 1", "email": "example2@auco.ai" }]
    }
  ]
}

🔹 Signers Auco does not notify​

A signer is silenced when their effective notification is false: their own if they carry one, otherwise the global one. signProfile always comes back in the response; what changes is that silenced signers carry an id and the ones Auco notifies do not, because their access is generated when the email goes out.

This example turns notification off for the whole package and back on only for example2@auco.ai:

{
  "name": "Contract package",
  "email": "example@auco.ai",
  "notification": false,
  "documents": [
    {
      "name": "Documento 1",
      "signProfile": [
        { "type": "solicitante", "name": "Firmante 1", "email": "example1@auco.ai" },
        { "type": "aprobador", "name": "Firmante 2", "email": "example2@auco.ai", "notification": true }
      ]
    },
    {
      "name": "Documento 2",
      "signProfile": [
        { "type": "solicitante", "name": "Firmante 1", "email": "example1@auco.ai" }
      ]
    }
  ]
}

Firmante 1 appears in both documents, so they get the same id in each: they are one person within the package. Firmante 2 carries no id because Auco takes care of them.

{
  "id": "packageId",
  "documents": [
    {
      "url": "https://signed_url_to_upload_PDF",
      "name": "Documento 1",
      "code": "CODEDOC1",
      "signProfile": [
        { "id": "0Q", "name": "Firmante 1", "email": "example1@auco.ai" },
        { "name": "Firmante 2", "email": "example2@auco.ai" }
      ]
    },
    {
      "url": "https://signed_url_to_upload_PDF",
      "name": "Documento 2",
      "code": "CODEDOC2",
      "signProfile": [{ "id": "0Q", "name": "Firmante 1", "email": "example1@auco.ai" }]
    }
  ]
}
FieldTypeDescription
documents[x].signProfileArrayList of signers for the document.
documents[x].signProfile[y].idStringIdentifier of the signer within the package. Only present when Auco does not notify them; regenerated if you overwrite the package.
documents[x].signProfile[y].nameStringName of the signer.
documents[x].signProfile[y].emailStringEmail of the signer.

⚠️ Error Responses​

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