Garrigues Signature Manager - Signature Request Operations

Introduction

Once you have the token, you can start sending requests to the Signature Manager API to manage signature requests.

Signature requests can move through the following statuses: DRAFT, ACTIVE, PARTIALLY_SIGNED, FULLY_SIGNED, CANCELLED, COMPLETED, COMPLETED_PARTIAL, COMPLETED_EXPIRED, COMPLETED_MANUAL, REJECTED, ERROR.

Operations

Create signature request

This endpoint creates a new signature request.

HTTP Request

POST /api/v1/private/signature-requests

With the following information provided as JSON:

Example Request Body

{
  "name": "Signature Request 1",
  "description": "Example description",
  "createdBy": "creator@example.com",
  "senderName": "Garrigues Digital Trust",
  "senderAddress": "no-reply@example.com",
  "signatureRequestBody": [
    {
      "status": "DRAFT",
      "content": {
        "body": "Request body content",
        "subject": "Request Subject",
        "role": "SIGNATORY",
        "additionalText": "Optional additional text"
      }
    }
  ],
  "notifications": true,
  "language": "en",
  "uniqueValidator": false,
  "provider": "NOTICEMAN_AND_WHATSAPP",
  "closeConfig": {
    "condition": "ALL_REQUIRED",
    "date": "2024-01-31T23:59:59Z"
  }
}

Where

Parameter Mandatory Datatype Description
name Yes string Name of the signature request.
description No string Description of the signature request.
createdBy Yes string Identifier (e.g., email) of the creator.
senderName No string Name of the sender displayed in notifications.
senderAddress No string (email) Sender email address used in notifications.
signatureRequestBody Yes array of objects Array containing the body details of the signature request.
signatureRequestBody[].status Yes string Status for the body template. Possible values: DRAFT, ACTIVE, REJECTED, COMPLETED, CANCELLED.
signatureRequestBody[].content.body Yes string Body content of the notification.
signatureRequestBody[].content.subject Yes string Subject for the notification.
signatureRequestBody[].content.role Yes string Participant role. Possible values: SIGNATORY, OBSERVER, VALIDATOR.
signatureRequestBody[].content.additionalText No string Additional text appended to the notification.
notifications No boolean Flag to enable notifications.
language No string Language code (e.g., "en").
uniqueValidator No boolean If true, a single validator approval is enough when multiple validators exist for a signatory.
provider No string Notification provider. Possible values: NOTICEMAN, NOTICEMAN_AND_WHATSAPP.
closeConfig.condition No string Close condition. ALL_REQUIRED ends on first rejection, PARTIAL_ALLOWED continues.
closeConfig.date No string (OffsetDateTime) Auto-close date in ISO 8601 format.

Example Response

{
  "id": "6db10639-bfd1-4a0a-bf2b-e837b715c0c8",
  "name": "Signature Request 1",
  "description": "Example description",
  "createdBy": "creator@example.com",
  "senderName": "Garrigues Digital Trust",
  "senderAddress": "no-reply@example.com",
  "signatureRequestBody": [
    {
      "status": "DRAFT",
      "content": {
        "body": "Request body content",
        "subject": "Request Subject",
        "role": "SIGNATORY",
        "additionalText": "Optional additional text"
      }
    }
  ],
  "cancellationReason": null,
  "status": "DRAFT",
  "notifications": true,
  "language": "en",
  "uniqueValidator": false,
  "provider": "NOTICEMAN_AND_WHATSAPP",
  "closeConfig": {
    "condition": "ALL_REQUIRED",
    "date": "2024-01-31T23:59:59Z"
  }
}

Error: 400 Bad request | 409 Conflict because invalid signature request close at | 500 Unexpected error

List signature requests

This endpoint retrieves a list of signature requests. You can filter the results using various query parameters.

HTTP Request

GET /api/v1/private/signature-requests

Where

Parameter Mandatory Datatype Description
ids No array of string (UUID) Filter by signature request IDs.
names No array of string Filter by signature request names.
creators No array of string Filter by creator identifiers.
statuses No array of string Filter by signature request statuses. Possible values: DRAFT, ACTIVE, PARTIALLY_SIGNED, FULLY_SIGNED, CANCELLED, COMPLETED, COMPLETED_PARTIAL, COMPLETED_EXPIRED, COMPLETED_MANUAL, REJECTED, ERROR.
cancellationReasons No array of string Filter by cancellation reasons. Possible values: REJECTED, DEADLINE.
dateFrom No string Filter requests created from this date.
dateTo No string Filter requests created until this date.
signatureTypes No array of string Filter by document signature types. Possible values: ADVANCED, INTERPOSITION.
providers No array of string Filter by document signature providers. Possible value: EADTRUST.
emailSignatories No array of string Filter by signatory email addresses.
emailObservers No array of string Filter by observer email addresses.
hashes No array of string Filter by document hashes.
closeCondition No string Filter by close condition. Possible values: ALL_REQUIRED, PARTIAL_ALLOWED.
closeAtFrom No string Filter requests with close date from this date.
closeAtTo No string Filter requests with close date until this date.
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 (e.g., requestId:ASC, createdAt:DESC).

Example Response

[
  {
    "id": "e694c179-e503-4101-992e-329700c37adc",
    "status": "DRAFT",
    "name": "Signature Request 1",
    "description": "Example description",
    "cancellationReason": null,
    "createdBy": "creator@example.com",
    "createdAt": "2023-10-23T10:34:59.483Z"
  },
  {
    "id": "55fc5ab7-2345-41fd-8688-6d04acf2b5bc",
    "status": "ACTIVE",
    "name": "Signature Request 2",
    "description": "Another description",
    "cancellationReason": null,
    "createdBy": "another@example.com",
    "createdAt": "2023-10-24T11:00:00.000Z"
  }
]

Get signature request detail

This endpoint retrieves detailed information for a specific signature request identified by its unique identifier.

HTTP Request

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

Where

Parameter Mandatory Datatype Description
signatureRequestId Yes string (UUID) Unique identifier for the signature request.

Example Response

{
  "id": "6db10639-bfd1-4a0a-bf2b-e837b715c0c8",
  "status": "ACTIVE",
  "name": "Signature Request 1",
  "description": "Example description",
  "cancellationReason": null,
  "createdBy": "creator@example.com",
  "senderName": "Garrigues Digital Trust",
  "senderAddress": "no-reply@example.com",
  "notifications": true,
  "language": "en",
  "uniqueValidator": false,
  "provider": "NOTICEMAN",
  "closeConfig": {
    "condition": "PARTIAL_ALLOWED",
    "date": "2024-01-31T23:59:59Z"
  },
  "documents": [],
  "statusHistory": [
    {
      "signatureRequestId": "6db10639-bfd1-4a0a-bf2b-e837b715c0c8",
      "registeredAt": "2023-10-23T10:34:59.483Z",
      "status": "ACTIVE"
    }
  ]
}

Update signature request

This endpoint updates a signature request.

HTTP Request

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

With the following information provided as JSON:

Example Request Body

{
  "name": "Updated Signature Request 1",
  "description": "Updated description",
  "createdBy": "creator@example.com",
  "signatureRequestBody": [
    {
      "status": "DRAFT",
      "content": {
        "body": "Updated request body",
        "subject": "Updated subject",
        "role": "SIGNATORY",
        "additionalText": "Updated additional text"
      }
    }
  ],
  "notifications": true,
  "language": "en",
  "uniqueValidator": true,
  "provider": "NOTICEMAN",
  "closeConfig": {
    "condition": "PARTIAL_ALLOWED"
  }
}

Where

Parameter Mandatory Datatype Description
signatureRequestId Yes string (UUID) Unique identifier for the signature request.
name No string Updated name of the signature request.
description No string Updated description of the signature request.
createdBy No string Updated identifier of the creator.
signatureRequestBody No array of objects Updated body details of the signature request.
notifications No boolean Flag to enable notifications.
language No string Language code (e.g., "en").
uniqueValidator No boolean If true, a single validator approval is enough when multiple validators exist for a signatory.
provider No string Notification provider. Possible values: NOTICEMAN, NOTICEMAN_AND_WHATSAPP.
closeConfig.condition No string Close condition. ALL_REQUIRED ends on first rejection, PARTIAL_ALLOWED continues.

Error: 400 Bad request | 404 Signature request not found | 409 Signature request not in draft or invalid closeAt | 422 Unprocessable entity | 500 Unexpected error

Update signature requests (bulk patch)

This endpoint updates multiple signature requests using patch operations.

HTTP Request

PATCH /api/v1/private/signature-requests

With the following information provided as JSON:

Example Request Body

{
  "ids": [
    "e694c179-e503-4101-992e-329700c37adc",
    "55fc5ab7-2345-41fd-8688-6d04acf2b5bc"
  ],
  "patch": [
    {
      "operation": "REPLACE",
      "path": "/name",
      "value": "Updated name"
    },
    {
      "operation": "REPLACE",
      "path": "/closeConfig/condition",
      "value": "PARTIAL_ALLOWED"
    },
    {
      "operation": "REPLACE",
      "path": "/signatureRequestBody/0/content/body",
      "value": "Updated body content"
    },
    {
      "operation": "REMOVE",
      "path": "/description"
    }
  ]
}

Where

Parameter Mandatory Datatype Description
ids Yes array of string (UUID) Signature request IDs to update.
patch Yes array of objects Patch operations. Use JSON Pointer paths. Operations: REPLACE, REMOVE.
patch[].path Yes string Editable paths include: /name, /description, /createdBy, /senderName, /senderAddress, /notifications, /language, /uniqueValidator, /provider, /closeConfig/condition, /signatureRequestBody/*/content/body, /signatureRequestBody/*/content/subject, /signatureRequestBody/*/content/role, /signatureRequestBody/*/content/additionalText.

Fields that cannot be edited: identifiers, statuses, and date fields (createdAt, closeConfig.date, and any other dates).

Error: 400 Bad request | 500 Unexpected error

Delete signature request

This endpoint deletes a signature request identified by its unique identifier.

HTTP Request

DELETE /api/v1/private/signature-requests/{signatureRequestId}

Where

Parameter Mandatory Datatype Description
signatureRequestId Yes string (UUID) Unique identifier for the signature request.

Error: 500 Unexpected error

Activate signature request

This endpoint activates a signature request.

HTTP Request

POST /api/v1/private/signature-requests/{signatureRequestId}/activate

Where

Parameter Mandatory Datatype Description
signatureRequestId Yes string (UUID) Unique identifier for the signature request.

Example Response

{
  "id": "86b26824-f646-406d-b039-cdb142d46cd4",
  "status": "ACTIVE"
}

Error: 400 Bad request | 404 Signature request not found | 500 Unexpected error

Cancel signature request

This endpoint cancels a signature request identified by its unique identifier.

HTTP Request

POST /api/v1/private/signature-requests/{signatureRequestId}/cancel

Where

Parameter Mandatory Datatype Description
signatureRequestId Yes string (UUID) Unique identifier for the signature request.

Example Response

{
  "id": "86b26824-f646-406d-b039-cdb142d46cd4",
  "status": "CANCELLED"
}

Error: 400 Bad request | 404 Signature request not found | 500 Unexpected error

Draft signature request

This endpoint drafts a signature request.

HTTP Request

POST /api/v1/private/signature-requests/{signatureRequestId}/draft

Where

Parameter Mandatory Datatype Description
signatureRequestId Yes string (UUID) Unique identifier for the signature request.

Example Response

{
  "id": "18bb63be-743f-47b3-a7f0-7f76ee79b89c",
  "status": "DRAFT"
}

Error: 500 Unexpected error

Close signature request

This endpoint closes a signature request manually.

HTTP Request

POST /api/v1/private/signature-requests/{signatureRequestId}/close

Where

Parameter Mandatory Datatype Description
signatureRequestId Yes string (UUID) Unique identifier for the signature request.

Example Response

{
  "id": "86b26824-f646-406d-b039-cdb142d46cd4",
  "status": "COMPLETED_MANUAL"
}

Error: 400 Bad request | 404 Signature request not found | 500 Unexpected error

Resend signature request notifications

This endpoint resends notifications for all participants in a signature request.

HTTP Request

POST /api/v1/private/signature-requests/{signatureRequestId}/resend

Where

Parameter Mandatory Datatype Description
signatureRequestId Yes string (UUID) Unique identifier for the signature request.

Response: 202 Accepted

Error: 404 Signature request not found | 409 Conflict when request state is invalid

Generate interim report

This endpoint generates an interim report for a document in a signature request. The interim report can be generated at any moment of the signature request flow.

HTTP Request

POST /api/v1/private/signature-requests/{signatureRequestId}/reports

Example Request Body

{
  "documentId": "2b066f42-8e65-4c6f-8253-ad6ded8ae436",
  "reportId": "8d8f5d2a-5b6c-4a0c-a82b-9c7f74b5b9b1",
  "additionalData": {
    "key": "value"
  }
}

Where

Parameter Mandatory Datatype Description
signatureRequestId Yes string (UUID) Unique identifier for the signature request.
documentId Yes string (UUID) Document identifier for which the report is generated.
reportId No string (UUID) Optional report identifier. If omitted, a new report ID is generated.
additionalData No object Key/value map with extra information for the interim report.

Example Response

{
  "signatureRequestId": "6db10639-bfd1-4a0a-bf2b-e837b715c0c8",
  "reportId": "8d8f5d2a-5b6c-4a0c-a82b-9c7f74b5b9b1",
  "documentId": "2b066f42-8e65-4c6f-8253-ad6ded8ae436"
}

Error: 400 Bad request | 404 Signature request or document not found | 409 Report id exists in other process | 500 Internal server error

Generate well signed appearance document

This endpoint triggers the generation of a well signed appearance document. This is an advanced operation and is usually generated automatically.

HTTP Request

POST /api/v1/private/signature-requests/{signatureRequestId}/certificates

Where

Parameter Mandatory Datatype Description
signatureRequestId Yes string (UUID) Unique identifier for the signature request.

Error: 400 Bad request | 404 Signature request not found | 409 Operation not available due the config | 500 Unexpected error