Garrigues Signature Manager - Validators Operations

Introduction

Validators approve a signature process before the signatory is notified. If uniqueValidator is set to true (at signature request or signatory level), a single validator approval is enough when multiple validators exist for the same signatory.

Operations

List validators

This endpoint retrieves a list of validators for a signature request.

HTTP Request

GET /api/v1/private/signature-requests/{signatureRequestId}/validators

Where

Parameter Mandatory Datatype Description
signatureRequestId Yes string (UUID) Unique identifier for the signature request.
page No integer Page number for pagination.
size No integer Number of items per page.
sort No array of string Sorting criteria in the format field:order.

Example Response

[
  {
    "id": "d6dd41c4-8f92-4a88-9d13-2f5a6c1e55b1",
    "name": "Validator Name",
    "surnames": "Validator Surnames",
    "phone": "123456789",
    "email": "validator@example.com",
    "documentId": "2b066f42-8e65-4c6f-8253-ad6ded8ae436",
    "signatoryId": "950fac7e-5284-42ad-8044-3f4632678324"
  }
]

Get editable validators

This endpoint retrieves editable validators for a signature request.

HTTP Request

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

Where

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

Create validator

This endpoint creates a validator for a signatory.

HTTP Request

POST /api/v1/private/documents/{documentId}/signatories/{signatoryId}/validators

Example Request Body

{
  "name": "Validator Name",
  "surnames": "Validator Surnames",
  "email": "validator@example.com",
  "phone": "123456789"
}

Where

Parameter Mandatory Datatype Description
documentId Yes string (UUID) Unique identifier for the document.
signatoryId Yes string (UUID) Unique identifier for the signatory.
name Yes string Validator name.
surnames No string Validator surnames.
email Yes string (email) Validator email address.
phone No string Validator phone number.

Error: 400 Bad request | 500 Unexpected error

Update validator

This endpoint updates a validator.

HTTP Request

PATCH /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/signatories/{signatoryId}/validators/{validatorId}

Example Request Body

{
  "name": "Updated Validator",
  "surnames": "Validator Surnames",
  "email": "validator@example.com",
  "phone": "123456789"
}

Where

Parameter Mandatory Datatype Description
signatureRequestId Yes string (UUID) Unique identifier for the signature request.
documentId Yes string (UUID) Unique identifier for the document.
signatoryId Yes string (UUID) Unique identifier for the signatory.
validatorId Yes string (UUID) Unique identifier for the validator.
name No string Updated validator name.
surnames No string Updated validator surnames.
email No string (email) Updated validator email address.
phone No string Updated validator phone number.

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

Delete validator

This endpoint deletes a validator.

HTTP Request

DELETE /api/v1/private/documents/{documentId}/signatories/{signatoryId}/validators/{validatorId}

Error: 400 Bad request | 500 Unexpected error

Resend validator notification

This endpoint resends the notification to a validator.

HTTP Request

POST /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/signatories/{signatoryId}/validators/{validatorId}/resend

Response: 202 Accepted

Error: 404 Signature request, document, signatory or validator not found | 409 Conflict when request or validator state is invalid

Bulk add or remove validators

This endpoint assigns validators to documents within a signature request or removes them in bulk.

HTTP Request

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

Example Request Body (validators by signatoryId)

{
  "documents": [
    {
      "documentId": "2b066f42-8e65-4c6f-8253-ad6ded8ae436",
      "validators": [
        {
          "email": "validator@example.com",
          "name": "Validator Name",
          "surnames": "Validator Surnames",
          "phone": "123456789",
          "signatoryId": "950fac7e-5284-42ad-8044-3f4632678324"
        }
      ],
      "operationType": "ADD"
    }
  ]
}

Example Request Body (validators inside signatories)

{
  "documents": [
    {
      "documentId": "2b066f42-8e65-4c6f-8253-ad6ded8ae436",
      "signatories": [
        {
          "email": "signatory@example.com",
          "name": "Signatory Name",
          "validators": [
            {
              "email": "validator@example.com",
              "name": "Validator Name",
              "surnames": "Validator Surnames",
              "phone": "123456789"
            }
          ]
        }
      ],
      "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[].validators No array of objects Validators to add/remove by signatoryId.
documents[].signatories No array of objects Signatories that include nested validators.
validators[].email Yes string (email) Validator email address.
validators[].name Yes string Validator name.
validators[].surnames No string Validator surnames.
validators[].phone No string Validator phone number.
validators[].signatoryId Yes (for documents[].validators) string (UUID) Identifier of the signatory to validate.
signatories[].email Yes (for documents[].signatories) string (email) Signatory email address.
signatories[].name Yes (for documents[].signatories) string Signatory name.
signatories[].validators No array of objects Validators attached to a 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 validators (v2)

This endpoint edits validators in bulk using patch operations.

HTTP Request

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

Example Request Body

{
  "participants": [
    {
      "where": {
        "email": "validator@example.com",
        "documentId": "2b066f42-8e65-4c6f-8253-ad6ded8ae436"
      },
      "patch": [
        {
          "operation": "REPLACE",
          "path": "/name",
          "value": "Updated Validator"
        },
        {
          "operation": "REPLACE",
          "path": "/phone",
          "value": "987654321"
        }
      ]
    }
  ]
}

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.

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 validators

This endpoint edits validators 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": "validator@example.com",
        "role": "VALIDATOR"
      },
      "patch": [
        {
          "operation": "REPLACE",
          "path": "/name",
          "value": "Updated Validator"
        }
      ]
    }
  ]
}

Where

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

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