Signature Requests

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": "signer@company.com"
}

2. No-Account Signing (Recommended)

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

{
    "account_email": "signer@company.com",
    "signer_identity_data": {
        "email_address": "signer@company.com",
        "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

Success Callback (callback_success_url)
- Triggered when all signatures are completed
- Receives the final document ID
- Use this to download the signed document
Error Callback (callback_error_url)
- Triggered when an error occurs
- Provides error details
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

# 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

Creation

Create a signature request by specifying the document and signers

Notification

Signers receive email notifications with signing instructions or direct signing URLs

Signing

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

Completion

All parties receive the final signed document

Example Structure

Here’s what a typical signature request looks like:

signature_request = {
    "title": "Employment Contract",
    "message": "Please review and sign your contract",
    "file_url": "https://example.com/contract.pdf",
    "signatures": [
        {
            "account_email": "employee@company.com",
            "signer_identity_data": {
                "email_address": "employee@company.com",
                "first_name": "John",
                "last_name": "Doe",
                "language": "en"
            },
            "sequence": 1
        },
        {
            "account_email": "hr@company.com",
            "signer_identity_data": {
                "email_address": "hr@company.com"
            },
            "sequence": 2
        }
    ],
    "cc_email_addresses": ["manager@company.com"],
    "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:

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

Example success callback handling:

@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:

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: