Retrieve the Traceability of a Process

GET /document/roadmap

This service returns the full traceability of a signature process: who created it, who takes part in it, and what happened at every point in time. It is the service you use to audit a process, to reconstruct its history in response to a claim, or to feed a tracking dashboard.

The response contains the process data, the list of participants, and an activity log sorted in ascending chronological order, from the oldest event to the most recent one. It has no pagination and no filters: the whole process is returned in a single call.

What this page covers

This page documents the traceability of the process: notification, reminder, read, signature, approval, rejection, cancellation, and reactivation events. To query the current status of the process and of each participant, use GET /document; to read the individual messages of a WhatsApp conversation, use GET /whatsapp/records.

Authentication

Include your public key in the Authorization header.

Authorization: puk_xxx...

Query Parameters

Name	Type	Required	Description
`code`	String	Required	Code of the process you want the traceability of. Either 9 or 10 characters.

code accepts the code of a contract (9 characters) or of a document (10 characters); it is the same value GET /document returns in the code field.

The process must belong to your company

The query is limited to the company that owns the public key. A code that does not exist and a code that belongs to another company return the same error, DOCUMENT_NOT_FOUND.

🧪 Usage Examples

tip

You can copy any of the examples depending on your preferred language.

🔹 Retrieve the traceability of a process

curl
Python
Node.js

curl --location 'https://api.auco.ai/v1.5/ext/document/roadmap?code=CODEDOCUM' \
  --header 'Authorization: puk_yourPublicKey'

import requests

response = requests.get(
  "https://api.auco.ai/v1.5/ext/document/roadmap",
  headers={"Authorization": "puk_yourPublicKey"},
  params={"code": "CODEDOCUM"}
)
print(response.json())

const axios = require('axios');

axios
  .get('https://api.auco.ai/v1.5/ext/document/roadmap', {
    headers: { Authorization: 'puk_yourPublicKey' },
    params: { code: 'CODEDOCUM' },
  })
  .then((response) => console.log(response.data));

📥 Response Examples

🔹 Process signed over WhatsApp

{
  "name": "Service Agreement",
  "documentCode": "CODEDOCUM",
  "createdAt": "2026-06-26T21:48:42.755Z",
  "author": {
    "name": "Sarah Miller",
    "email": "example@auco.ai"
  },
  "participants": [
    {
      "id": "01",
      "name": "John Smith",
      "role": "SIGNER",
      "phone": "+573001234567"
    }
  ],
  "activityLog": [
    {
      "action": "NOTIFICATION_SIGN",
      "platform": "WHATSAPP",
      "participant": "01",
      "timestamp": "2026-06-26T21:48:44.307Z",
      "by": "+573001234567"
    },
    {
      "action": "PARTICIPANT_READ",
      "platform": "WHATSAPP",
      "participant": "01",
      "timestamp": "2026-06-26T21:49:47.523Z",
      "by": "+573001234567"
    },
    {
      "action": "PARTICIPANT_SIGN",
      "platform": "WHATSAPP",
      "participant": "01",
      "timestamp": "2026-06-26T21:50:10.940Z",
      "by": "+573001234567"
    }
  ]
}

🔸 Process with several participants, a rejection, and a cancellation

{
  "name": "Service Agreement",
  "documentCode": "CODEDOCUM",
  "createdAt": "2026-02-10T14:02:11.418Z",
  "author": {
    "name": "Sarah Miller",
    "email": "example@auco.ai"
  },
  "participants": [
    {
      "id": "01",
      "name": "John Smith",
      "role": "SIGNER",
      "email": "john@example.com",
      "phone": "+573001234567",
      "location": {
        "lat": 4.6533326179999995,
        "lng": -74.05834928765297,
        "street": "Calle 98 15-17, 110221 Bogotá, Colombia"
      },
      "ipAddress": "190.24.10.55 Bogotá, Bogota D.C., Colombia"
    },
    {
      "id": "02",
      "name": "Emily Clark",
      "role": "APPROVER",
      "email": "emily@example.com"
    },
    {
      "name": "Internal Audit",
      "role": "READER",
      "email": "audit@example.com"
    }
  ],
  "activityLog": [
    {
      "action": "NOTIFICATION_SIGN",
      "platform": "EMAIL",
      "participant": "01",
      "timestamp": "2026-02-10T14:02:13.902Z",
      "by": "john@example.com"
    },
    {
      "action": "PARTICIPANT_READ",
      "platform": "EMAIL",
      "participant": "01",
      "timestamp": "2026-02-10T15:31:08.114Z",
      "by": "john@example.com",
      "ip": "190.24.10.55"
    },
    {
      "action": "PARTICIPANT_SIGN",
      "platform": "EMAIL",
      "participant": "01",
      "timestamp": "2026-02-10T15:33:44.660Z",
      "by": "john@example.com",
      "ip": "190.24.10.55"
    },
    {
      "action": "NOTIFICATION_APPROVER",
      "platform": "EMAIL",
      "participant": "02",
      "timestamp": "2026-02-10T15:33:47.201Z",
      "by": "emily@example.com"
    },
    {
      "action": "REMINDER_APPROVE",
      "platform": "EMAIL",
      "participant": "02",
      "timestamp": "2026-02-11T15:33:47.318Z",
      "by": "emily@example.com"
    },
    {
      "action": "PARTICIPANT_REJECT",
      "platform": "EMAIL",
      "participant": "02",
      "timestamp": "2026-02-11T16:10:29.775Z",
      "by": "emily@example.com",
      "message": "Exhibit 2 does not match the contracted service."
    },
    {
      "action": "CANCEL_SIGN",
      "platform": "ARCHIVE",
      "participant": "ARCHIVE",
      "timestamp": "2026-02-11T16:44:02.031Z",
      "by": "example@auco.ai"
    }
  ]
}

🔸 Process created without notifying

A process created with notification: false exists and has participants, but has not generated any event yet: activityLog comes back empty.

{
  "name": "Service Agreement",
  "documentCode": "CODEDOCUM",
  "createdAt": "2026-02-10T14:02:11.418Z",
  "author": {
    "name": "Sarah Miller",
    "email": "example@auco.ai"
  },
  "participants": [
    {
      "id": "01",
      "name": "John Smith",
      "role": "SIGNER",
      "email": "john@example.com"
    }
  ],
  "activityLog": []
}

📋 Response Fields

Field	Type	Description
`name`	String	Name of the process, as it was defined when the process was created.
`documentCode`	String	Code of the queried process. It matches the `code` you sent.
`createdAt`	String	Date and time the process was created, in ISO 8601 format and UTC.
`author`	Object	Optional. User of your company who created the process. It does not appear if the creator no longer exists as a user.
`author.name`	String	Name of the process creator.
`author.email`	String	Optional. Email address of the process creator.
`participants`	Array<Object>	People involved in the process: signers, approvers, and viewers. Comes back empty (`[]`) if the process has no participants.
`participants[].id`	String	Optional. Identifier of the participant within the process. It is the value `activityLog[].participant` points to. Viewers do not include it, and neither do participants with no recorded activity yet.
`participants[].name`	String	Optional. Name of the participant.
`participants[].role`	String	Role of the participant in the process. See Roles.
`participants[].email`	String	Optional. Email address of the participant.
`participants[].phone`	String	Optional. Participant's phone number in international format, with country code and the `+` sign.
`participants[].location`	Object	Optional. Location recorded for the participant during the process. It only appears if Auco captured it.
`participants[].location.lat`	Number	Latitude, in decimal degrees.
`participants[].location.lng`	Number	Longitude, in decimal degrees.
`participants[].location.street`	String	Approximate address derived from the coordinates.
`participants[].ipAddress`	String	Optional. Free-form text with the IP address recorded for the participant. It may arrive in several formats: the IP alone, or the IP followed by the approximate location derived from it. Do not parse it as a clean IP address.
`activityLog`	Array<Object>	Events of the process, sorted in ascending chronological order: the first element is the oldest one. Comes back empty (`[]`) if there is no activity.
`activityLog[].action`	String	Event that took place. See Actions.
`activityLog[].platform`	String	Channel through which the event took place. See Platforms.
`activityLog[].participant`	String	`id` of the participant the event belongs to, or the special value `ARCHIVE` when the event belongs to the process and not to a person.
`activityLog[].timestamp`	String	Date and time of the event, in ISO 8601 format and UTC.
`activityLog[].by`	String	Optional. Identifier the action was performed with or delivered to: the email address when `platform` is `EMAIL`, and the phone number when it is `WHATSAPP`.
`activityLog[].ip`	String	Optional. IP address the event was recorded from. It only appears when Auco received it.
`activityLog[].message`	String	Optional. Text associated with the event, for example the reason the participant wrote when rejecting.

Optional fields only arrive when there is data

author, id, name, email, phone, location, ipAddress, by, ip, and message are omitted from the response when there is no value: they do not arrive as null or as an empty string. Your integration should check whether the key exists before reading it, instead of assuming the object always has the same shape.

participant is not always a person

activityLog[].participant is usually the id of an element of participants[], but events that affect the whole process arrive with participant: "ARCHIVE". That value does not cross-reference participants[].id: if you try to resolve it against the participant list you will not find a match. See Process-level events.

📖 Traceability Dictionary

The three columns you interpret for every event are action (what happened), platform (through which channel), and participant (to whom). These tables list the values Auco emits today.

The catalog is not closed

Values of action, platform, and role that are not in these tables may show up: the catalog grows with the product. Do not build your integration assuming the list is closed. Treat an unknown value as an event you cannot classify yet — display it as is, log it — instead of discarding it or letting your processing fail.

Actions (`activityLog[].action`)

Notifications sent by Auco

`action`	Meaning
`NOTIFICATION_SIGN`	Invitation to Sign Sent
`NOTIFICATION_APPROVER`	Invitation to Approve Sent
`NOTIFICATION_FINISH`	Completion Notification Sent
`NOTIFICATION_FAILED_SIGN`	Sign Invitation Failed

Reminders

`action`	Meaning
`REMINDER_SIGN`	Signature Reminder Sent
`REMINDER_APPROVE`	Approval Reminder Sent
`REMINDER_UPLOAD`	Upload Reminder
`REMINDER_PAYMENT`	Payment Reminder

Reminders may come from the automatic schedule of the process or from a manual send with POST /document/reminder.

Participant actions

`action`	Meaning
`PARTICIPANT_READ`	Document Viewed
`PARTICIPANT_SIGN`	Document Signed
`PARTICIPANT_APPROVE`	Document Approved
`PARTICIPANT_REJECT`	Document Rejected
`READ_PARTICIPANT`	Document Viewed

READ_PARTICIPANT is equivalent to PARTICIPANT_READ

Some processes record the read event as READ_PARTICIPANT. It means exactly the same as PARTICIPANT_READ: the participant opened the document. If you classify events by their action value, treat both as the same event.

Changes to the process

`action`	Meaning
`UPDATE_SIGNER`	Participant Updated
`UPDATE_SIGN`	Signature Updated
`CANCEL_SIGN`	Process Cancelled
`REACTIVATION_SIGN`	Process Reactivated

Roles (`participants[].role`)

Value	Meaning	Description
`SIGNER`	Signer	Must sign the document. It is the default role.
`APPROVER`	Approver	Must approve or reject the document, without signing it.
`READER`	Viewer	Receives the document to review it; does not sign or approve.

The role is defined when the process is created and returned as is, so you may also find values specific to your integration.

Platforms (`activityLog[].platform`)

Value	Description
`EMAIL`	The event took place over email.
`WHATSAPP`	The event took place over WhatsApp.
`ARCHIVE`	The event was performed from the Auco web archive, not from a channel to a participant.

When platform is WHATSAPP you can get the detail of the conversation — the messages and their delivery statuses — with GET /whatsapp/records.

Process-level events (`participant: "ARCHIVE"`)

Some events do not belong to a participant but to the process as a whole: a cancellation performed from the Auco web archive, for example. Those events arrive with participant: "ARCHIVE", and their by field identifies the user of your company who performed the action, not a signer.

Treat them as process-level events: do not try to resolve ARCHIVE against participants[].id, because there will never be a match.

⚠️ Error Responses

Code	Description
400	Validation error on the `code` parameter (missing, or its length is not between 9 and 10 characters), or process not found (`DOCUMENT_NOT_FOUND`).
401	Invalid or missing authentication

DOCUMENT_NOT_FOUND is returned when the process does not exist or when it does not belong to the company of the public key you are querying with.

Authentication​

Query Parameters​

🧪 Usage Examples​

🔹 Retrieve the traceability of a process​

📥 Response Examples​

🔹 Process signed over WhatsApp​

🔸 Process with several participants, a rejection, and a cancellation​

🔸 Process created without notifying​

📋 Response Fields​

📖 Traceability Dictionary​

Actions (activityLog[].action)​

Roles (participants[].role)​

Platforms (activityLog[].platform)​

Process-level events (participant: "ARCHIVE")​

⚠️ Error Responses​