Garrigues Signature Manager - Signatories Operations

Introduction

This section covers all operations related to managing signatories for a document in a signature request.

Operations

Get list of signatories

This endpoint retrieves a list of signatories associated with a specific document in a signature request.

HTTP Request

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

Example Response

[
  {
    "id": "950fac7e-5284-42ad-8044-3f4632678324",
    "name": "Signatory Name",
    "surnames": "Signatory Surnames",
    "email": "signatory@example.com",
    "phone": "123456789",
    "signatureStatus": "READY_TO_SIGN",
    "coordinates": {
      "x": 100.5,
      "y": 200.75,
      "page": 1
    },
    "sequence": 1,
    "uniqueValidator": false,
    "registeredAt": "2023-10-23T10:34:59.483Z"
  }
]

Where

Parameter Mandatory Datatype Description
signatureRequestId Yes string (UUID) Unique identifier for the signature request.
documentId Yes string (UUID) Unique identifier for the document.
ids No array of string (UUID) Filter signatories by their IDs.
emails No array of string Filter signatories by their email addresses.
hasCoordinates No boolean Filter signatories by whether they have coordinates.
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.

Get list of signatories in a signature request

This endpoint retrieves a list of signatories associated with a signature request across all documents.

HTTP Request

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

Where

Parameter Mandatory Datatype Description
signatureRequestId Yes string (UUID) Unique identifier for the signature request.
ids No array of string (UUID) Filter signatories by their IDs.
emails No array of string Filter signatories by their email addresses.
documentId No string (UUID) Filter signatories by document ID.
hasCoordinates No boolean Filter signatories by whether they have coordinates.
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.

Create signatory

This endpoint creates a signatory for a document in a signature request.

HTTP Request

POST /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/signatories

Example Request Body

{
  "name": "Signatory Name",
  "surnames": "Signatory Surnames",
  "email": "signatory@example.com",
  "phone": "123456789",
  "sequence": 1,
  "uniqueValidator": false,
  "coordinates": [
    {
      "x": 100.5,
      "y": 200.75,
      "page": 1
    }
  ]
}

Where

Parameter Mandatory Datatype Description
signatureRequestId Yes string (UUID) Unique identifier for the signature request.
documentId Yes string (UUID) Unique identifier for the document.
name Yes string Signatory name.
surnames No string Signatory surnames.
email Yes string (email) Signatory email address.
phone No string Signatory phone number.
sequence No integer Sequence number for phased signing.
uniqueValidator No boolean If true, a single validator approval is enough for this signatory.
coordinates No array of objects Signature coordinates.
coordinates[].x Yes (if provided) number X coordinate for the signature.
coordinates[].y Yes (if provided) number Y coordinate for the signature.
coordinates[].page Yes (if provided) integer Page number for the signature.

Update signatory

This endpoint updates a signatory.

HTTP Request

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

Example Request Body

{
  "name": "Updated Name",
  "surnames": "Updated Surnames",
  "email": "signatory@example.com",
  "phone": "123456789",
  "sequence": 2,
  "uniqueValidator": true
}

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.
name No string Updated signatory name.
surnames No string Updated signatory surnames.
email No string (email) Updated signatory email address.
phone No string Updated signatory phone number.
sequence No integer Updated sequence number for phased signing.
uniqueValidator No boolean If true, a single validator approval is enough for this signatory.

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

Update signatory coordinates

This endpoint updates the signatory coordinates.

HTTP Request

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

Example Request Body

{
  "coordinates": [
    {
      "x": 120.0,
      "y": 240.0,
      "page": 1
    }
  ]
}

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.
coordinates Yes array of objects Signature coordinates.
coordinates[].x No number X coordinate for the signature.
coordinates[].y No number Y coordinate for the signature.
coordinates[].page No integer Page number for the signature.

Update signatory sequence

This endpoint updates the signatory sequence for phased signing.

HTTP Request

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

Example Request Body

{
  "sequence": 2
}

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.
sequence Yes integer New sequence number for phased signing.

Delete signatory

This endpoint deletes a signatory.

HTTP Request

DELETE /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/signatories/{signatoryId}

Error: 400 Bad request | 500 Unexpected error

Resend signatory notification

This endpoint resends the notification to a signatory.

HTTP Request

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

Response: 202 Accepted

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