Document Workflow

For each document state, a request is generated with the following body, varying only in the status description.

You have 10 seconds to respond

Auco closes the connection if your endpoint does not respond within 10 seconds. Both a timeout and a 4xx or 5xx response are retried up to 3 times before the notification is discarded. Return 200 immediately, process in the background, and make your handler idempotent. See Response Time and Retries.

---

Notified States

Name	Description
CREATE	Notified when a document is created or a PDF is uploaded to the platform.
FINISH	Notified when all parties have signed the document.
NOTIFICATION	Notified when a document participant has completed the signing process.
REJECT	Notified when at least one signer has rejected the document.
REJECTED	Indicates the details of the process cancellation.
BLOCKED	Notified when a signer exceeds the identity validation attempts (3), requiring manual validation.
EXPIRED	Notified when a document expires, only if an expiration date was set during creation.

---

🧪 Notification Examples

tip

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

Response Parameters

Name	Type	Description
code	String	Document code.
name	String	Document name.
signer	Object	Signer information, present only when the status is NOTIFICATION, BLOCKED, or REJECTED.
url	String	Document URL.
status	String	Current status of the signing process (CREATE, FINISH, NOTIFICATION, REJECT, REJECTED, BLOCKED or EXPIRED).
message	String	Text content associated with the signer’s status. If the status is REJECTED, contains the individual message written by the participant. For BLOCKED, see list of blocking states.
similarity	Number	Facial identity validation similarity percentage, present when applicable.
scores	Object	Detail of identity validation scores, present when applicable.
tags	Array	List of tags assigned to the document, if defined during creation.
custom	Array	List of custom fields registered in the document, if specified.

Process Creation

JSON

{
  "code": "DOCUMENTCODE", //Código del documento
  "name": "Contrato de prueba del API", //Nombre del documento
  "status": "CREATE", //Estado del documento
  "url": "https://test.auco.ai/contrato-de-prueba-id-98-DOCUMENTCODE.pdf" // url del documento
}

Process Completion

JSON

{
  "code": "DOCUMENTCODE",
  "name": "Contrato de prueba del API",
  "status": "FINISH",
  "url": "https://test.auco.ai/contrato-de-prueba-id-98-DOCUMENTCODE.pdf" // url del documento
}

Participant Signature

JSON

{
  "code": "DOCUMENTCODE",
  "name": "Contrato de prueba del API",
  "signer": {
    "id": "participant_id",
    "name": "participant name",
    "email": "email",
    "phone": "phone"
  },
  "status": "NOTIFICATION"
}

Signer Blocked

JSON

{
  "name": "document name",
  "signer": {
    "id": "participan_id",
    "name": "participant name",
    "email": "email",
    "phone": "phone"
  },
  "status": "BLOCKED",
  "message": "OTP_CODE_INVALID",
  "tags": ["document tag"],
  "custom": ["{'info':'required', 'definition': 'urgent'}"]
}

Rejection Details

JSON

{
  "name": "document name",
  "signer": {
    "id": "participan_id",
    "name": "participant name",
    "email": "email",
    "phone": "phone"
  },
  "status": "REJECTED",
  "message": "message",
  "tags": ["document tags"]
}

Process Expiration

JSON

{
  "code": "DOCUMENTCODE",
  "name": "Contrato de prueba del API",
  "status": "EXPIRED",
  "url": "https://test.auco.ai/contrato-de-prueba-id-98-DOCUMENTCODE.pdf",
  "tags": ["document tag"],
  "custom": ["{'info':'required', 'definition': 'urgent'}"]
}