View-Only Recipients

This guide explains how to create and track view-only recipients on an eSignature transaction using the eSign360 API. A view-only recipient can access and view all documents in a transaction but cannot sign, fill in fields, or modify any document content.

When to Use

Add a view-only recipient when a person needs to see the documents but should not sign them — for example:

• A compliance officer or auditor who must review the final document
• An internal stakeholder who needs a copy of what was sent
• Any observer who should receive and open the documents without participating in signing

View-Only vs. Non-Signer

The API supports two distinct "non-signing" recipient types. Choose the one that matches your use case:

Use case	viewOnly	nonSigner
Must sign the document	false	false
Observes but doesn't sign (e.g. witness, attorney)	false	true
Only needs to view the final document (e.g. compliance officer, auditor)	true	auto-set true

Setting viewOnly: true automatically makes the participant a non-signer — the backend sets nonSigner=true for you. You do not need to send nonSigner yourself for a view-only recipient.

---

Creating a View-Only Recipient

To designate a participant as view-only, set "viewOnly": true on the participant object in your POST /transactions payload.

const axios = require("axios");

const config = {
  method: "post",
  url: "https://public-api.esign360.io/transactions",
  headers: {
    Authorization: "Bearer <accessToken>",
    "Content-Type": "application/json",
  },
  data: {
    notifyParticipants: { email: true },
    signingOrder: false,
    participants: [
      {
        id: "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        email: "signer@example.com",
        firstName: "John",
        lastName: "Doe",
        type: "signer",
        order: 0,
        primary: true,
        authenticationType: "none",
      },
      {
        id: "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
        email: "viewer@example.com",
        firstName: "Jane",
        lastName: "Smith",
        type: "signer",
        order: 1,
        primary: false,
        viewOnly: true,
      },
    ],
    documents: [
      {
        id: "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
        StoragePath: "org123/contract.pdf",
        title: "Contract",
        sessionType: "esign",
        tags: [
          {
            type: "SIGNHERETAGTEMPLATEANNOTATION",
            x: 200,
            y: 100,
            width: 150,
            height: 34,
            page: 0,
            signerId: "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
            required: true,
          },
        ],
      },
    ],
  },
};

axios(config)
  .then(function (response) {
    console.log("Transaction created:", response.data);
  })
  .catch(function (error) {
    console.log(error.response?.data || error.message);
  });

Behavior

Behavior	Description
Default	viewOnly defaults to false. Existing payloads that don't include the field are unaffected.
Email notification	The view-only recipient receives an invitation email containing a read-only link (readonly=true).
Document access	Can open and view all documents in the transaction.
Signing	Cannot sign, fill in tags, or modify documents.
Tags	Tags may not be assigned to a view-only participant. See Validation below.
Transaction completion	Does not block transaction completion — the transaction completes when all signers finish, regardless of whether the view-only recipient has viewed.
View tracking	A viewedAt timestamp is recorded the first time the recipient opens the documents (see Tracking View Activity).
Audit trail	A view-only-document-viewed audit event is emitted on first view.

Building your own emails? If you create the transaction with sendEmail: false (or notifyParticipants.email: false) and build your own emails from the URLs returned in the POST /transactions response, note that the URL returned for a view-only recipient already includes readonly=true. Use that URL as-is so the recipient lands in read-only mode.

Validation

A view-only recipient is a non-signer and therefore cannot own any tags. If you assign one or more tags to a view-only participant's signerId, the request is rejected with a 400 Bad Request:

{
  "detail": "Tags assigned to view-only participant",
  "error": "enl-api-400",
  "message": "Bad request. Validation error.",
  "help": "https://integration.esign360.io/docs/troubleshooting/enl-api-400"
}

To resolve this, remove any tags whose signerId matches a viewOnly: true participant. See Error 400: Bad Request for general guidance on 400 responses.

Because view-only recipients do not sign, the following signing-related fields are not applicable and may be omitted:

Field	Required for view-only?
email	✅ Yes — required for the invitation email
firstName / lastName	✅ Yes — required for email personalization
order	✅ Yes — position in the participant list
viewOnly	✅ Yes — must be true
authenticationType	❌ No — view-only recipients don't authenticate
kbaRequired	❌ No
credAnalysisRequired	❌ No
personalPasswordQuestion / personalPassword	❌ No

---

Tracking View Activity

When you retrieve a transaction via GET /transactions/{id} (and in the POST /transactions create response), a view-only participant exposes the following fields:

Field	Type	Description
role	string	The resolved participant role. For view-only recipients this is "view-only".
viewStatus	string	"pending" until the recipient first opens the documents, then "viewed".
viewedAt	string (ISO 8601) | null	Timestamp of the recipient's first view, or null if they have not yet viewed.

These three fields are only present on view-only participants. Regular signers and non-signers do not include viewStatus or viewedAt.

Example — Before the recipient has viewed

{
  "id": "391866a6-8ebb-4533-b6ab-c7bb4d6fbd38",
  "status": "esign_pending",
  "documents": [
    {
      "id": "8d976a23-b865-4fcd-9165-ddc0aedaf614",
      "title": "Contract",
      "sessionType": "esign"
    }
  ],
  "participants": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "email": "signer@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "order": 0,
      "role": "signer"
    },
    {
      "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "email": "viewer@example.com",
      "firstName": "Jane",
      "lastName": "Smith",
      "order": 1,
      "role": "view-only",
      "viewStatus": "pending",
      "viewedAt": null
    }
  ]
}

Example — After the recipient has viewed

Once the view-only recipient opens the documents, viewStatus becomes "viewed" and viewedAt is populated with the timestamp of that first view:

{
  "id": "391866a6-8ebb-4533-b6ab-c7bb4d6fbd38",
  "status": "esign_pending",
  "documents": [
    {
      "id": "8d976a23-b865-4fcd-9165-ddc0aedaf614",
      "title": "Contract",
      "sessionType": "esign"
    }
  ],
  "participants": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "email": "signer@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "order": 0,
      "role": "signer"
    },
    {
      "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "email": "viewer@example.com",
      "firstName": "Jane",
      "lastName": "Smith",
      "order": 1,
      "role": "view-only",
      "viewStatus": "viewed",
      "viewedAt": "2026-04-15T10:30:00.000Z"
    }
  ]
}

---

Audit / Webhook Event

When a view-only recipient first views the documents, the system emits a view-only-document-viewed audit event. If your organization is subscribed to webhooks, this event is delivered to your webhook endpoint. See Webhook Events for general webhook setup.

{
  "event": "esign.view-only-document-viewed",
  "entity": "view-only-document-viewed",
  "data": {
    "participantId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
    "transactionId": "391866a6-8ebb-4533-b6ab-c7bb4d6fbd38",
    "participantName": "Jane Smith",
    "viewedAt": "2026-04-15T10:30:00.000Z",
    "organizationId": "14a00c39-af89-47ee-b26c-f0bc523c270e",
    "isViewOnly": true
  }
}

Field	Description
event	esign.view-only-document-viewed
entity	view-only-document-viewed
data.participantId	ID of the view-only participant who viewed the documents
data.transactionId	ID of the transaction
data.participantName	Display name of the view-only participant
data.viewedAt	ISO 8601 timestamp of the view
data.organizationId	ID of the organization that owns the transaction
data.isViewOnly	Always true for this event

---

Updating a Transaction to Add a View-Only Recipient

You can also add a view-only recipient to an existing transaction via PUT /transactions/{id} by including a participant with viewOnly: true in the participants array. The same behavior, validation, and tracking apply.

---

Additional Resources

• Get Transaction by ID — Retrieve the full transaction including view-tracking fields.
• Update a Transaction — Add or change participants on an existing transaction.
• Webhook Events — Subscribe to the view-only-document-viewed event.
• API Reference

If you need further assistance or have questions, feel free to reach out to our support team.