Garrigues Signature Manager - Participants Operations

---

---

Introduction

This section covers all operations related to managing participants for a signature request. There are three participant profiles: signatories (who sign), validators (who validate a signature process before the signatory is notified), and observers (who receive documentation but cannot perform any action).

Validator-specific operations are documented in the Validators operations section.

---

Operations

Bulk add or remove participants

This endpoint assigns participants (signatories and observers) to documents within a signature request or removes them in bulk. Validator use cases are covered in the Validators operations section.

HTTP Request

PATCH /api/v1/private/signature-requests/{signatureRequestId}/documents

With the following information provided as JSON:

Example Request Body

{
  "documents": [
    {
      "documentId": "2b066f42-8e65-4c6f-8253-ad6ded8ae436",
      "signatories": [
        {
          "email": "signatory@example.com",
          "name": "Signatory Name",
          "surnames": "Signatory Surnames",
          "phone": "123456789",
          "sequence": 1,
          "uniqueValidator": false,
          "coordinates": [
            {
              "x": 100.5,
              "y": 200.75,
              "page": 1
            }
          ]
        }
      ],
      "observers": [
        {
          "email": "observer@example.com",
          "name": "Observer Name",
          "surnames": "Observer Surnames"
        }
      ],
      "operationType": "ADD"
    }
  ]
}

Where

Parameter	Mandatory	Datatype	Description
documents	Yes	array of objects	List of document participant objects.
documents[].documentId	Yes	string (UUID)	Identifier of the document.
documents[].operationType	Yes	string	Operation to perform. Possible values: ADD, DELETE.
documents[].signatories	No	array of objects	List of signatory participants to add/remove.
documents[].observers	No	array of objects	List of observer participants to add/remove.
documents[].emails	No	array of string (email)	List of participant emails to add or delete in bulk.
signatories[].email	Yes	string (email)	Signatory email address.
signatories[].name	Yes	string	Signatory name.
signatories[].surnames	No	string	Signatory surnames.
signatories[].phone	No	string	Signatory phone number.
signatories[].sequence	No	integer	Sequence number for phased signing.
signatories[].uniqueValidator	No	boolean	If true, a single validator approval is enough for this signatory.
signatories[].coordinates	No	array of objects	Signature coordinates for the signatory.

Error: 400 Bad request | 422 Signature request status should be draft or participant not in document or observer existing in this document | 500 Unexpected error

---

Bulk edit participants (v2)

This endpoint edits participants in bulk using patch operations.

HTTP Request

PATCH /api/v1/private/signature-requests/{signatureRequestId}/bulkedit/v2

Example Request Body

{
  "participants": [
    {
      "where": {
        "email": "signatory@example.com",
        "documentId": "2b066f42-8e65-4c6f-8253-ad6ded8ae436",
        "sequence": 1
      },
      "patch": [
        {
          "operation": "REPLACE",
          "path": "/name",
          "value": "Updated Name"
        },
        {
          "operation": "REPLACE",
          "path": "/sequence",
          "value": 2
        },
        {
          "operation": "REPLACE",
          "path": "/coordinates/0/x",
          "value": 120.0
        }
      ]
    }
  ]
}

Where

Parameter	Mandatory	Datatype	Description
participants	Yes	array of objects	List of bulk edit operations.
participants[].where	Yes	object	Search criteria: email, documentId, sequence.
participants[].patch	Yes	array of objects	Patch operations. Operations: REPLACE, REMOVE.
participants[].patch[].path	Yes	string	Editable paths include: /name, /surnames, /email, /phone, /sequence, /uniqueValidator, /coordinates/*/x, /coordinates/*/y, /coordinates/*/page.

Fields that cannot be edited: identifiers, statuses, and date fields.

Error: 400 Bad request | 422 Signature request status should be draft | 500 Unexpected error

---

Bulk edit editable participants

This endpoint edits editable participants using patch operations and a role filter.

HTTP Request

PATCH /api/v1/private/signature-requests/{signatureRequestId}/bulkedit/editable-participants

Example Request Body

{
  "participants": [
    {
      "where": {
        "email": "observer@example.com",
        "role": "OBSERVER"
      },
      "patch": [
        {
          "operation": "REPLACE",
          "path": "/name",
          "value": "Updated Observer"
        }
      ]
    }
  ]
}

Where

Parameter	Mandatory	Datatype	Description
participants	Yes	array of objects	List of bulk edit operations.
participants[].where.email	Yes	string (email)	Email of the participant to edit.
participants[].where.role	Yes	string	Role of the participant. Possible values: SIGNATORY, VALIDATOR, OBSERVER.
participants[].patch	Yes	array of objects	Patch operations. Operations: REPLACE, REMOVE.

Fields that cannot be edited: identifiers, statuses, and date fields.

Error: 400 Bad request | 422 Signature request status should be draft | 500 Unexpected error

---

Get editable signatories

This endpoint retrieves editable signatories for a signature request.

HTTP Request

GET /api/v1/private/signature-requests/{signatureRequestId}/signatories/editables

Where

Parameter	Mandatory	Datatype	Description
signatureRequestId	Yes	string (UUID)	Unique identifier for the signature request.
emails	No	array of string (email)	Filter by participant emails.

---

Get editable observers

This endpoint retrieves editable observers for a signature request.

HTTP Request

GET /api/v1/private/signature-requests/{signatureRequestId}/observers/editables

Where

Parameter	Mandatory	Datatype	Description
signatureRequestId	Yes	string (UUID)	Unique identifier for the signature request.
emails	No	array of string (email)	Filter by participant emails.