Signature Requests

Understanding signature requests and how they work

A signature request is the core concept in the Skribble SDK that manages the electronic signature process for one or more documents. It defines who needs to sign, in what order, and under what conditions.

Signer Configuration

There are two ways to configure signers in a signature request:

1. Account-Based Signing (Requires Skribble Account)

Only specify account_email if you want to force the signer to use or create a Skribble account:

{
    "account_email": "[e-mail]"
}

2. No-Account Signing (Recommended)

Specify both account_email and signer_identity_data to allow signing without requiring a Skribble account:

{
    "account_email": "[e-mail]",
    "signer_identity_data": {
        "email_address": "[e-mail]",
        "first_name": "John",      # Optional
        "last_name": "Doe",        # Optional
        "language": "en",          # Optional
        "mobile_number": "+1234"   # Optional
    }
}

When using signer_identity_data, Skribble generates a unique signing URL that allows direct access without account creation. This is the recommended approach for most use cases.

Callback Integration

Skribble provides three types of callbacks to track the signature request lifecycle:

Callback Types

1. Success Callback (callback_success_url)

   • Triggered when all signatures are completed
   • Receives the final document ID
   • Use this to download the signed document

2. Error Callback (callback_error_url)

   • Triggered when an error occurs
   • Provides error details

3. Update Callback (callback_update_url)

   • Triggered after each individual signature
   • Includes the signature ID that was just completed

Dynamic URL Parameters

Skribble automatically replaces these placeholders in your callback URLs:

• SKRIBBLE_SIGNATURE_REQUEST_ID: The ID of the signature request
• SKRIBBLE_DOCUMENT_ID: The ID of the final signed document
• SKRIBBLE_SIGNATURE_ID: The ID of the completed signature (only for update callbacks)

Example Implementation

Python

# Create signature request with callbacks
signature_request = {
    "title": "Contract Signature",
    "message": "Please sign this contract",
    "file_url": "https://example.com/contract.pdf",
    "signatures": [...],
    # Callbacks with dynamic parameters
    "callback_success_url": "https://api.your-domain.com/webhooks/signature-success/SKRIBBLE_SIGNATURE_REQUEST_ID/SKRIBBLE_DOCUMENT_ID",
    "callback_error_url": "https://api.your-domain.com/webhooks/signature-error/SKRIBBLE_SIGNATURE_REQUEST_ID",
    "callback_update_url": "https://api.your-domain.com/webhooks/signature-update/SKRIBBLE_SIGNATURE_REQUEST_ID/SKRIBBLE_SIGNATURE_ID"
}

# Webhook endpoint example (using Flask)
@app.route('/webhooks/signature-success/<request_id>/<document_id>', methods=['POST'])
def handle_signature_success(request_id, document_id):
    # Download the signed document
    document = skribble.document.download(document_id)
    
    # Save the document
    with open(f'signed_{request_id}.pdf', 'wb') as f:
        f.write(document)
    
    return {'status': 'success'}

@app.route('/webhooks/signature-update/<request_id>/<signature_id>', methods=['POST'])
def handle_signature_update(request_id, signature_id):
    # Get signature request status
    status = skribble.signature_request.get(request_id)
    
    # Process the update
    print(f"Signature {signature_id} completed")
    print(f"Overall status: {status['status_overall']}")
    
    return {'status': 'success'}

Best Practices for Callbacks

URL Configuration

• Use HTTPS endpoints for security
• Include request/document IDs in the URL for easy routing
• Keep URLs under 2048 characters
• Handle URL encoding properly

Error Handling

• Implement proper error handling in your webhook endpoints
• Return appropriate HTTP status codes
• Log webhook events for debugging
• Set up retry logic for failed webhook deliveries

Document Handling

• Download and store signed documents promptly
• Implement proper file storage security
• Update your database with document status
• Clean up temporary files

Key Components

Document

The PDF file that needs to be signed. Can be provided as a URL, base64 content, or existing document ID.

Signers

One or more people who need to sign the document, with optional signing sequence.

Visual Signature

The appearance and position of signatures on the document.

Workflow

The signing process including notifications, reminders, and completion handling.

Signature Request Lifecycle

1. Creation

   Create a signature request by specifying the document and signers

2. Notification

   Signers receive email notifications with signing instructions or direct signing URLs

3. Signing

   Signers review and sign the document in sequence (if specified)

4. Completion

   All parties receive the final signed document

Example Structure

Here’s what a typical signature request looks like:

Python

signature_request = {
    "title": "Employment Contract",
    "message": "Please review and sign your contract",
    "file_url": "https://example.com/contract.pdf",
    "signatures": [
        {
            "account_email": "[e-mail]",
            "signer_identity_data": {
                "email_address": "[e-mail]",
                "first_name": "John",
                "last_name": "Doe",
                "language": "en"
            },
            "sequence": 1
        },
        {
            "account_email": "[e-mail]",
            "signer_identity_data": {
                "email_address": "[e-mail]"
            },
            "sequence": 2
        }
    ],
    "cc_email_addresses": ["[e-mail]"],
    "callback_success_url": "https://your-domain.com/webhook/success/SKRIBBLE_SIGNATURE_REQUEST_ID/SKRIBBLE_DOCUMENT_ID",
    "callback_update_url": "https://your-domain.com/webhook/update/SKRIBBLE_SIGNATURE_REQUEST_ID/SKRIBBLE_SIGNATURE_ID"
}

Best Practices

Document Preparation

• Verify base64 content is valid if applicable
• Ensure document is not password protected and/or URL is public
• Optimize file size (recommended max: 40MB)

Signer Configuration

• Always provide both account_email and signer_identity_data unless you specifically need to force account creation
• Use the same email address in both account_email and signer_identity_data.email_address
• Add optional signer details (name, language) in signer_identity_data for better user experience
• Consider using sequence for ordered signing when document order matters

Status Handling

A signature request can have the following overall statuses:

• OPEN: The signature request is active and waiting for signatures
• SIGNED: All required signatures have been completed
• WITHDRAWN: The signature request was cancelled

Best Practice for Document Handling

The recommended workflow for handling signed documents is:

1. Configure a success callback endpoint that receives the document ID
2. When the callback is triggered, use the provided document ID to retrieve the signed document
3. Process and store the document as needed

Example success callback handling:

Python

@app.route('/webhooks/signature-success/<request_id>/<document_id>', methods=['POST'])
def handle_signature_success(request_id, document_id):
    # Use the document_id from the callback URL to download the signed document
    document = skribble.document.download(document_id)
    
    # Process and store the document
    save_document(document, request_id)
    
    return {'status': 'success'}

Error Handling

For detailed error handling guidance, please refer to our Error Handling Guide. Here’s a basic example of handling common signature request errors:

Python

try:
    response = skribble.signature_request.create(request_data)
except SkribbleValidationError as e:
    print(f"Invalid request data: {e.message}")
except SkribbleAPIError as e:
    print(f"API error ({e.status_code}): {e.message}")

Implementation

Choose your preferred SDK to see detailed implementation guides:

Signature Requests Guide

Learn how to implement signature requests

API Reference

For detailed API documentation, see:

API Reference

Browse the complete API reference