Document Upload

POST/document/uploadprivate keyprk_

This service allows initiating a process to request attachments for signature or just attachments without signature. Each attachment can be configured as mandatory or optional.

info

If you want to include a signature process, you can directly send a PDF document in base64 format. If you want the signature and attachment request to be part of a template, note that this flow cannot be configured directly through the endpoint; you must request support from our team.

info

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

Authentication

Include your private key in the Authorization header.

Authorization: prk_xxx...

Creation Parameters

Name	Type	Description
`email`	String required	Email address of the process creator.
`code`	String optional	Code of a document previously put into edit. Sending it overwrites that process instead of creating a new one, keeping its code. Resend the full payload: whatever you leave out is removed. Read more
`document`	String conditional	If you want to create the process using a template, you must send the template ID in this field. To view and obtain templates, access this documentation.
`name`	String required	Name of the document signing process, only if the attachments process includes document signing.
`message`	String conditional	Message that will be included in the body of the email notifying signers or approvers of the document. Required when any participant is notified by email.
`subject`	String conditional	Subject line for the notification email sent to signers or approvers. Required when any participant is notified by email.
`file`	String conditional	If you want to upload the document in the same request, send the PDF file in Base64 in this parameter. (Only for small files)
`compress`	Boolean conditional	If the PDF file to be uploaded is too large, it is recommended not to send the file parameter; instead, use `compress: true`. This way, the service returns a signed URL to upload the PDF file in binary format via a PUT request.
`folder`	String conditional	If you want to save this process in a specific folder, provide the path of that folder in this parameter. Note that the folder must exist and belong to the process creator.
`remember`	Number conditional	Parameter that enables automatic reminders with the time interval (in hours) between each notification.
`expiredDate`	Date optional	Expiration date of the document. This must be more than 3 days after the process creation date and is sent in JSON Date format.
`camera`	Boolean optional	This parameter indicates if photo validation is required. Default is `false`.
`otpCode`	Boolean optional	This parameter indicates if OTP code validation is required. Default is `false`.
`options`	Object optional	This parameter specifies the identity validation settings. See more
`notification`	Boolean optional	Defines 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`.
`targetWebhooks`	Array[String] optional	If you have several webhooks, you can send the name of the webhook to which you want the updates of this process to be notified.
`tags`	Array[String] optional	If you want to classify processes with tags, you can send the names of the tags to relate the process to (They must exist).
`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.
`readers`	Array optional	This parameter is a list of objects defining participants who are not part of the signing process but should be able to observe each phase of the signing process.
`readers[x].name`	String required	Name of the reader.
`readers[x].email`	String required	Email of the reader.
`signProfile`	Array required	This field is a list of objects containing information for each signer or approver for their notification and signature.
`signProfile[x].name`	String required	Name of the signer.
`signProfile[x].email`	String required	Email of the signer.
`signProfile[x].phone`	String required	Phone number of the signer.
`signProfile[x].role`	String conditional	This parameter defines the participant's role; it can be `'APPROVER'` or `'SIGNER'`.
`signProfile[x].order`	String conditional	This parameter defines the order in which the notification process for signing or approval will take place.
`signProfile[x].label`	Boolean(true) \| String conditional	Parameter indicating if signature positioning will be done using labels in the PDF.
`signProfile[x].position`	Array conditional	In this parameter, the signature positions for this signer on each page are sent. Signature positions can be preloaded in templates. Obtain more information in the documentation.
`signProfile[x].type`	String conditional	Name used to identify the signer type if pre-saved in a template, e.g., `'co-signer'`.
`signProfile[x].options`	Object optional	Allows defining custom validations for a specific signer. If you want to apply validations individually by signer, See more.
`signProfile[x].camera`	Boolean optional	If you want individual validations per signer and require photo validation, send this parameter as `true`. Default is `false`.
`signProfile[x].otpCode`	Boolean optional	If you want individual validations per signer and require OTP validation, send this parameter as `true`. Default is `false`.
`signProfile[x].notification`	Boolean optional	Overrides 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`. Silenced signers get an `id` in the response.

🧪 Usage Examples

tip

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

Remember that email addresses and phone numbers between signers must not be repeated.
Readers will receive notifications for each update in the signing process.

Signing Process with Automatic Reminders (PDF Base64)

In this case, reminders will be sent every 3 hours.

curl
Python
Node.js

curl --location 'https://api.auco.ai/v1.5/ext/document/upload' \
--header 'Authorization: prk_private_key_company' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Documento de prueba",
    "subject": "prueba auco",
    "message": "prueba auco",
    "remember": 3,
    "email": "example@auco.ai",
    "signProfile": [
        {
            "name": "Jhon Firma",
            "email": "example@auco.ai",
            "label": true
        }
    ],
    "readers":[{"email":"example2@auco.ai", "name":"Frimante 1"}],
    "file": Base64
}'

import requests
import json

url = "https://api.auco.ai/v1.5/ext/document/upload"

payload = json.dumps({
  "name": "Documento de prueba",
  "subject": "prueba auco",
  "message": "prueba auco",
  "remember": 3,
  "email": "example@auco.ai",
  "signProfile": [
    {
      "name": "Jhon Firma",
      "email": "example@auco.ai",
      "label": True
    }
  ],
  "readers": [
    {
      "email": "example2@auco.ai",
      "name": "Frimante 1"
    }
  ],
  "file": Base64
})
headers = {
  'Authorization': 'prk_private_key_company',
  'Content-Type': 'application/json'
}

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

print(response.text)

const axios = require('axios');
let data = JSON.stringify({
  name: 'Documento de prueba',
  subject: 'prueba auco',
  message: 'prueba auco',
  remember: 3,
  email: 'example@auco.ai',
  signProfile: [
    {
      name: 'Jhon Firma',
      email: 'example@auco.ai',
      label: true,
    },
  ],
  readers: [
    {
      email: 'eyvasquezt30@gmail.com',
      name: 'Frimante 1',
    },
  ],
  file: Base64,
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.auco.ai/v1.5/ext/document/upload',
  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);
  });

Document Signing with Individual Validations (compress - PDF binary)

curl
Python
Node.js

curl --location 'https://api.auco.ai/v1.5/ext/document/upload' \
--header 'Authorization: prk_private_key_company' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Prueba de Anexos Compress y validaciones individuales",
    "email": "owner@auco.ai",
    "message": "Cargar adjuntos de prueba",
    "subject": "Solicitud de adjuntos",
    "signProfile": [
        {
            "type": "firmante1",
            "name": "Nombre Firmante 1",
            "email": "example @auco.ai",
            "camera": true,
            "otpCode": true,
            "options": {
                "camera": "identification",
                "whatsapp": true,
                "otpCode": "email"
            },
            "phone": "+573000000000",
        },
        {
            "type": "firmante2",
            "name": "Nombre Firmante 2",
            "email": "example2@auco.ai",
            "phone": "+573000000000",
            "otpCode": true,
            "options": {
                "otpCode": "email"
            },
        }
    ],
    "compress": true
}'

import requests
import json

url = "https://api.auco.ai/v1.5/ext/document/upload"

payload = json.dumps({
  "name": "Prueba de Anexos Compress y validaciones individuales",
  "email": "owner@auco.ai",
  "message": "Cargar adjuntos de prueba",
  "subject": "Solicitud de adjuntos",
  "signProfile": [
    {
      "type": "firmante1",
      "name": "Nombre Firmante 1",
      "email": "example @auco.ai",
      "camera": True,
      "otpCode": True,
      "options": {
        "camera": "identification",
        "whatsapp": True,
        "otpCode": "email"
      },
      "phone": "+573000000000",
    },
    {
      "type": "firmante2",
      "name": "Nombre Firmante 2",
      "email": "example2@auco.ai",
      "phone": "+573000000000",
      "otpCode": True,
      "options": {
        "otpCode": "email"
      }
    }
  ],
  "compress": True
})
headers = {
  'Authorization': 'prk_private_key_company',
  'Content-Type': 'application/json'
}

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

print(response.text)

const axios = require('axios');
let data = JSON.stringify({
  name: 'Prueba de Anexos Compress y validaciones individuales',
  email: 'owner@auco.ai',
  message: 'Cargar adjuntos de prueba',
  subject: 'Solicitud de adjuntos',
  signProfile: [
    {
      type: 'firmante1',
      name: 'Nombre Firmante 1',
      email: 'example @auco.ai',
      camera: true,
      otpCode: true,
      options: {
        camera: 'identification',
        whatsapp: true,
        otpCode: 'email',
      },
      phone: '+573000000000',
      files: [
        {
          name: 'cedula de ciudadanía',
        },
        {
          name: 'hoja de vida',
        },
        {
          name: 'pasaporte',
          optional: true,
        },
      ],
    },
    {
      type: 'firmante2',
      name: 'Nombre Firmante 2',
      email: 'example2@auco.ai',
      phone: '+573000000000',
      otpCode: true,
      options: {
        otpCode: 'whatsapp',
      },
    },
  ],
  compress: true,
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.auco.ai/v1.5/ext/document/upload',
  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

🔹 Normal mode (without `compress` or `compress: false`)

{
  "document": "ABCDEF1234"
}

Field	Type	Description
`document`	String	Unique code of the created document.

🔸 Compress mode (`compress: true`)

info

The pre-signed URL provided in the response is single-use and 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.

{
  "document": "ABCDEF1234",
  "url": "https://s3.amazonaws.com/...signed-url..."
}

Field	Type	Description
`document`	String	Unique code of the created document.
`url`	String	Pre-signed S3 URL to upload the PDF (expires in 300s).

🔹 Signers Auco does not notify

The response includes signProfile when any signer is silenced, that is, when their effective notification is false: their own if they carry one, otherwise the global one. Every silenced signer carries an id the integrator uses to take them to sign on their own. Signers Auco does notify appear without id: their access is generated when they are notified.

{
  "document": "ABCDEF1234",
  "signProfile": [
    {
      "id": "abc123",
      "name": "Juan",
      "email": "juan@email.com",
      "phone": "+57300..."
    }
  ]
}

Field	Type	Description
`document`	String	Unique code of the created document.
`signProfile`	Array	List of signers in the process.
`signProfile[x].id`	String	Unique identifier of the signer.
`signProfile[x].name`	String	Name of the signer.
`signProfile[x].email`	String	Email address of the signer.
`signProfile[x].phone`	String	Phone number of the signer.

tip

This field is also included in compress mode along with the url.

⚠️ Error Responses

Code	Description
400	Missing parameters, or some validations do not meet applicability conditions
401	Invalid or missing authentication

Authentication​

Creation Parameters​

🧪 Usage Examples​

Signing Process with Automatic Reminders (PDF Base64)​

Document Signing with Individual Validations (compress - PDF binary)​

📥 Response Examples​

🔹 Normal mode (without compress or compress: false)​

🔸 Compress mode (compress: true)​

🔹 Signers Auco does not notify​

⚠️ Error Responses​

Authentication

Creation Parameters

🧪 Usage Examples

Signing Process with Automatic Reminders (PDF Base64)

Document Signing with Individual Validations (compress - PDF binary)

📥 Response Examples

🔹 Normal mode (without `compress` or `compress: false`)

🔸 Compress mode (`compress: true`)

🔹 Signers Auco does not notify

⚠️ Error Responses