Step by step guide

Step by Step Guide for Signature Request Workflow

Step 1: Create Signature Request
Step 2: Add Documents
Step 3: Upload document file (single upload)
Step 4: Upload document file (multipart upload)
Step 5: Add Signatories, Validators, and Observers
Step 6: Configure sequence and validation
Step 7: Update Signatory Coordinates
Step 8: Activate Signature Request
Step 9: Signature flow and outcomes
Step 10: Reports and downloads
Step 11: Optional actions (resend, cancel, close, draft)

Step 1: Create Signature Request

Begin by creating a new signature request. This call initializes the workflow by registering a new request with all the basic details.

HTTP Request

POST /api/v1/private/signature-requests

With the following information provided as JSON:

Example Request Body

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

Notes:

provider controls notification channels: NOTICEMAN (burofax digital) or NOTICEMAN_AND_WHATSAPP (burofax + WhatsApp if signatory phone is present).
uniqueValidator means a single validator approval is enough when multiple validators exist for a signatory.
closeConfig controls rejection behavior and optional auto-close date.

Step 2: Add Documents

Next, add one or more documents to the signature request. This allows you to attach the files that will be signed.

HTTP Request

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

With the following information provided as JSON:

Example Request Body

{
  "filename": "document.pdf",
  "title": "Document Title",
  "description": "Document description",
  "hash": "64-character-hex-string",
  "signatureDeadline": "2023-10-25T12:00:00.000Z",
  "provider": "EADTRUST",
  "signatureType": "ADVANCED",
  "evidenceId": "1d6d735d-0383-42d1-bfb9-6d4cf71aa739",
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  },
  "certificateFiles": {
    "originalDocument": true,
    "signedDocument": false
  },
  "sequence": 1,
  "fileSize": 102400,
  "detached": false,
  "convertToPdf": true
}

Notes:

sequence defines the order of documents within the request.
detached requests a detached signature when supported.
convertToPdf converts the document to PDF before signing.

Step 3: Upload document file (single upload)

Obtain a pre-signed URL and upload the document file. Use this flow for standard file sizes.

HTTP Request

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

Use the returned URL to upload the file with a standard HTTP PUT request.

Step 4: Upload document file (multipart upload)

For large files, use the multipart upload flow.

Start multipart

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

Get upload link for each part

GET /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/uploads/{uploadId}?partNumber=1

Complete multipart

POST /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/uploads/{uploadId}?partCounts=3

Cancel multipart

DELETE /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/uploads/{uploadId}

Step 5: Add Signatories, Validators, and Observers

Add participants to each document. Signatories sign the document, validators approve the signing process before notifications reach signatories, and observers receive documentation without actions.

HTTP Request (bulk)

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

You can also manage signatories and observers individually using the specific endpoints in their sections.

Step 6: Configure sequence and validation

Configure parallel or phased signing and validation rules:

Parallel: Use the same sequence value for all signatories.
Phased: Assign increasing sequence values. Signatories with sequence 2 only receive notifications after all signatories with sequence 1 have signed.
Validation: If validators are configured, the signatory is notified only after validation completes.
uniqueValidator: If true, a single validator approval is enough for the signatory; otherwise, all validators must approve.
closeConfig.condition: ALL_REQUIRED closes the process on the first rejection; PARTIAL_ALLOWED continues even if someone rejects.
closeConfig.date: Optional auto-close date for the signature request.

Step 7: Update Signatory Coordinates

Update signing coordinates once documents are ready. Coordinates define where the signature is placed.

HTTP Request

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

Step 8: Activate Signature Request

Activate the signature request to start the notification process.

HTTP Request

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

Step 9: Signature flow and outcomes

Once active, the request progresses through its lifecycle:

Validators (if any) validate the document before signatories are notified.
Signatories receive notifications based on sequence order.
Statuses may become PARTIALLY_SIGNED or FULLY_SIGNED as signatures are completed.
If a signatory rejects, the process ends immediately when closeConfig.condition is ALL_REQUIRED; if PARTIAL_ALLOWED, the process can continue.
If the auto-close date is reached, the process is closed automatically.
Completed outcomes may include COMPLETED, COMPLETED_PARTIAL, COMPLETED_EXPIRED, or COMPLETED_MANUAL depending on how the process ended.

Step 10: Reports and downloads

You can generate reports at any moment of the signature request flow and download documents during or after the process.

Generate interim report

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

Download signed document

GET /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/links/signed/download

Download final report

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

Step 11: Optional actions (resend, cancel, close, draft)

Depending on the situation, you can perform additional actions:

Resend notifications to all participants: POST /api/v1/private/signature-requests/{signatureRequestId}/resend
Resend to a signatory: POST /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/signatories/{signatoryId}/resend
Resend to a validator: POST /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/signatories/{signatoryId}/validators/{validatorId}/resend
Cancel a request: POST /api/v1/private/signature-requests/{signatureRequestId}/cancel
Close a request manually: POST /api/v1/private/signature-requests/{signatureRequestId}/close
Return a request to draft: POST /api/v1/private/signature-requests/{signatureRequestId}/draft