✍️eSign Dispatch

Learn how to send documents for electronic signature through Docs-Dispatcher with Universign, Signaturit, and Yousign.

Overview

This recipe covers:

1. Sending documents for signature

2. Multiple signature providers (Universign, Signaturit)

3. Signature workflows (simple, advanced, qualified)

4. Multiple signers and signature order

5. Webhooks for signature events

6. Complete examples in 4 languages

What You'll Learn

• Structure eSign dispatch requests

• Configure signature workflows

• Add multiple signers

• Handle signature events

• Provider-specific features

• Complete working examples

Prerequisites

• Docs-Dispatcher account with JWT

• eSign provider configured (Universign, Signaturit, or Yousign)

• Template created

• Basic REST API knowledge

eSign Service Overview

Supported providers:

Provider	Signature Types	Multi-signer	Qualified Signature
Universign	Simple, Advanced, Qualified	✅	✅
Signaturit	Simple, Advanced	✅	❌
Yousign	Simple, Advanced	✅	❌

Step 1: Authentication

Dispatcher API uses HTTP Basic Authentication. You'll need your Dispatcher account email and password for all API calls.

Setup Credentials

# Store credentials as environment variables
export EMAIL="[email protected]"
export PASSWORD="your-password"

No token management needed! Unlike JWT-based APIs, Basic Auth doesn't require separate authentication endpoints or token refresh. Your credentials are sent with each request.

Quick links:

• Full authentication guide

• Using Basic Auth with Dispatcher

Step 2: Prepare eSign Request

Basic eSign Structure

{
  "providerName": "universign",
  "template": {
    "id": 126,
    "data": {
      "contractTitle": "Service Agreement 2026",
      "clientName": "Acme Corp",
      "startDate": "2026-03-01",
      "amount": 50000.00
    }
  },
  "esign": {
    "documentName": "Service Agreement - Acme Corp",
    "signatureType": "ADVANCED",
    "signers": [
      {
        "firstName": "Jane",
        "lastName": "Smith",
        "email": "[email protected]",
        "position": "CEO",
        "order": 1
      },
      {
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "position": "Sales Director",
        "order": 2
      }
    ],
    "expiresIn": 30,
    "reminderFrequency": 7,
  },
  "metadata": {
    "contractId": "CONTRACT-2026-001",
    "dealId": "DEAL-456"
  }
}

Required Fields

Field	Type	Description
providerName	string	universign, signaturit, or yousign
template.id	number	Template ID for document
esign.documentName	string	Document display name
esign.signers	array	List of signers (min 1)
esign.signers[].email	string	Signer email address

Signature Types

Type	Description	Legal Value	Provider Support
SIMPLE	Basic e-signature	Low	All
ADVANCED	EU eIDAS compliant	Medium	All
QUALIFIED	Highest legal value	High	Universign only

Step 3: Send for Signature

Single Signer Request

curl -X POST https://api.docs-dispatcher.io/api/esign \
  -u "$EMAIL:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "providerName": "universign",
    "template": {
      "id": 126,
      "data": {
        "contractTitle": "NDA Agreement",
        "recipientName": "Acme Corp"
      }
    },
    "esign": {
      "documentName": "NDA - Acme Corp",
      "signatureType": "ADVANCED",
      "signers": [
        {
          "firstName": "Jane",
          "lastName": "Smith",
          "email": "[email protected]",
          "phone": "[phone]"
        }
      ],
      "expiresIn": 15,
      "language": "en"
    }
  }'

Success Response:

{
  "success": true,
  "dispatchId": "disp_esign_abc123",
  "providerResponse": {
    "transactionId": "univ_trans_xyz789",
    "documentId": "doc_456",
    "status": "pending",
    "signers": [
      {
        "id": "signer_001",
        "email": "[email protected]",
        "status": "pending",
        "signatureUrl": "https://sign.universign.com/sign/abc123def456",
        "invitedAt": "2026-02-13T12:30:00Z"
      }
    ],
    "expiresAt": "2026-02-28T23:59:59Z",
    "createdAt": "2026-02-13T12:30:00Z"
  },
  "generatedDocument": {
    "url": "https://storage.docs-dispatcher.io/contracts/NDA-Acme.pdf",
    "size": 189456
  },
  "executionTime": 2.7
}

Multiple Signers with Order

{
  "providerName": "yousign",
  "template": {
    "id": 126,
    "data": {
      "contractTitle": "Partnership Agreement"
    }
  },
  "esign": {
    "documentName": "Partnership Agreement",
    "signatureType": "ADVANCED",
    "signers": [
      {
        "firstName": "Jane",
        "lastName": "Smith",
        "email": "[email protected]",
        "order": 1,
        "role": "Party A Representative"
      },
      {
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "order": 2,
        "role": "Party B Representative"
      },
      {
        "firstName": "Alice",
        "lastName": "Johnson",
        "email": "[email protected]",
        "order": 3,
        "role": "Witness"
      }
    ],
    "sequential": true,
    "expiresIn": 30
  }
}

Step 4: Handle Signature Events

Webhook Events

Signature providers send webhook notifications for:

• signature_pending - Document sent for signature

• signer_viewed - Signer opened the document

• signer_signed - Individual signer completed

• signature_completed - All signers completed

• signature_declined - Signer declined to sign

• signature_expired - Signature period expired

Webhook Payload Example

{
  "event": "signature_completed",
  "transactionId": "univ_trans_xyz789",
  "dispatchId": "disp_esign_abc123",
  "documentName": "Service Agreement - Acme Corp",
  "status": "completed",
  "completedAt": "2026-02-20T15:45:00Z",
  "signers": [
    {
      "id": "signer_001",
      "email": "[email protected]",
      "status": "signed",
      "signedAt": "2026-02-15T10:30:00Z"
    },
    {
      "id": "signer_002",
      "email": "[email protected]",
      "status": "signed",
      "signedAt": "2026-02-20T15:45:00Z"
    }
  ],
  "signedDocument": {
    "url": "https://universign.com/signed-docs/abc123.pdf",
    "certificate": "https://universign.com/certificates/abc123.pdf"
  },
  "metadata": {
    "contractId": "CONTRACT-2026-001"
  }
}

Webhook Handler (Node.js)

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/esign', async (req, res) => {
  const webhook = req.body;
  const { event, transactionId, status } = webhook;

  console.log('eSign webhook:', event, transactionId);

  // Return 200 OK immediately
  res.status(200).json({ received: true });

  // Process async
  try {
    switch (event) {
      case 'signature_completed':
        await handleSignatureCompleted(webhook);
        break;

      case 'signer_signed':
        await handleSignerSigned(webhook);
        break;

      case 'signature_declined':
        await handleSignatureDeclined(webhook);
        break;

      case 'signature_expired':
        await handleSignatureExpired(webhook);
        break;
    }
  } catch (error) {
    console.error('Webhook processing error:', error);
  }
});

async function handleSignatureCompleted(webhook) {
  const { transactionId, signedDocument, metadata } = webhook;

  console.log('✓ All signatures completed:', transactionId);

  // Download signed document
  await downloadSignedDocument(signedDocument.url);

  // Update database
  await database.updateContract(metadata.contractId, {
    status: 'signed',
    signedAt: new Date(),
    signedDocumentUrl: signedDocument.url,
    certificateUrl: signedDocument.certificate
  });

  // Notify stakeholders
  await notificationService.send({
    type: 'contract_signed',
    contractId: metadata.contractId,
    signedDocumentUrl: signedDocument.url
  });
}

async function handleSignerSigned(webhook) {
  const { transactionId, signer } = webhook;
  console.log(`Signer ${signer.email} signed at ${signer.signedAt}`);

  // Update progress tracking
  await updateSignatureProgress(transactionId, signer);
}

async function handleSignatureDeclined(webhook) {
  const { transactionId, signer, reason } = webhook;

  console.error(`Signature declined by ${signer.email}: ${reason}`);

  // Alert admin
  await alertService.notify({
    level: 'warning',
    message: `Contract signature declined by ${signer.email}`,
    data: webhook
  });
}

async function handleSignatureExpired(webhook) {
  const { transactionId } = webhook;

  console.warn('Signature expired:', transactionId);

  // Mark as expired and potentially resend
  await handleExpiredSignature(transactionId);
}

app.listen(3000);

Complete Examples

curl (Complete Flow)

#!/bin/bash

# Authenticate
AUTH_RESPONSE=$(curl -s -X POST https://api.docs-dispatcher.io/auth \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-secure-password"
  }')

JWT_TOKEN=$(echo $AUTH_RESPONSE | jq -r '.token')

# Send for signature
ESIGN_REQUEST='{
  "providerName": "universign",
  "template": {
    "id": 126,
    "data": {
      "contractTitle": "Service Agreement 2026",
      "clientName": "Acme Corp",
      "amount": 50000.00
    }
  },
  "esign": {
    "documentName": "Service Agreement - Acme Corp",
    "signatureType": "ADVANCED",
    "signers": [
      {
        "firstName": "Jane",
        "lastName": "Smith",
        "email": "[email protected]"
      }
    ],
    "expiresIn": 30,
  }
}'

# Validate
VALIDATION=$(curl -s -X POST https://api.docs-dispatcher.io/api/esign/validate \
  -u "$EMAIL:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d "$ESIGN_REQUEST")

if [ "$(echo $VALIDATION | jq -r '.valid')" = "true" ]; then
  # Send for signature
  RESULT=$(curl -s -X POST https://api.docs-dispatcher.io/api/esign \
    -u "$EMAIL:$PASSWORD" \
    -H "Content-Type: application/json" \
    -d "$ESIGN_REQUEST")

  if [ "$(echo $RESULT | jq -r '.success')" = "true" ]; then
    echo "Sent for signature!"
    echo "Transaction ID: $(echo $RESULT | jq -r '.providerResponse.transactionId')"
    echo "Signature URL: $(echo $RESULT | jq -r '.providerResponse.signers[0].signatureUrl')"
  else
    echo "Failed:"
    echo $RESULT | jq
  fi
else
  echo "Validation failed:"
  echo $VALIDATION | jq '.errors'
fi

Node.js (Complete Flow)

const fetch = require('node-fetch');

async function sendForSignature() {
  // Authenticate
  const authResponse = await fetch('https://api.docs-dispatcher.io/auth', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email: '[email protected]',
      password: 'your-secure-password'
    })
  });

  const { token } = await authResponse.json();

  // Send for signature
  const esignData = {
    providerName: 'universign',
    template: {
      id: 126,
      data: {
        contractTitle: 'Service Agreement 2026',
        clientName: 'Acme Corp',
        amount: 50000.00
      }
    },
    esign: {
      documentName: 'Service Agreement - Acme Corp',
      signatureType: 'ADVANCED',
      signers: [
        {
          firstName: 'Jane',
          lastName: 'Smith',
          email: '[email protected]'
        }
      ],
      expiresIn: 30,
    }
  };

  const response = await fetch('https://api.docs-dispatcher.io/api/esign', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(esignData)
  });

  const result = await response.json();

  if (result.success) {
    console.log('Sent for signature!');
    console.log('Transaction ID:', result.providerResponse.transactionId);
    console.log('Signature URL:', result.providerResponse.signers[0].signatureUrl);

    // Share signature URL with signer
    return result.providerResponse.signers[0].signatureUrl;
  } else {
    console.error('Failed:', result.message);
    throw new Error(result.message);
  }
}

sendForSignature().catch(console.error);

PHP (Complete Flow)

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

// Authenticate
$authResponse = $client->post('https://api.docs-dispatcher.io/auth', [
    'json' => [
        'email' => '[email protected]',
        'password' => 'your-secure-password'
    ]
]);

$authData = json_decode($authResponse->getBody(), true);
$jwtToken = $authData['token'];

// Send for signature
$esignData = [
    'providerName' => 'universign',
    'template' => [
        'id' => 126,
        'data' => [
            'contractTitle' => 'Service Agreement 2026',
            'clientName' => 'Acme Corp',
            'amount' => 50000.00
        ]
    ],
    'esign' => [
        'documentName' => 'Service Agreement - Acme Corp',
        'signatureType' => 'ADVANCED',
        'signers' => [
            [
                'firstName' => 'Jane',
                'lastName' => 'Smith',
                'email' => '[email protected]'
            ]
        ],
        'expiresIn' => 30,
    ]
];

$response = $client->post('https://api.docs-dispatcher.io/api/esign', [
    'headers' => [
        'auth' => [$email, $password],
        'Content-Type' => 'application/json'
    ],
    'json' => $esignData
]);

$result = json_decode($response->getBody(), true);

if ($result['success']) {
    echo "Sent for signature!\n";
    echo "Transaction ID: {$result['providerResponse']['transactionId']}\n";
    echo "Signature URL: {$result['providerResponse']['signers'][0]['signatureUrl']}\n";
} else {
    echo "Failed: {$result['message']}\n";
}

Java (Complete Flow)

import java.net.URI;
import java.net.http.*;
import com.google.gson.Gson;
import java.util.*;

public class ESignDispatcher {
    private final HttpClient client;
    private final Gson gson;

    public ESignDispatcher() {
        this.client = HttpClient.newHttpClient();
        this.gson = new Gson();
    }

    public String authenticate(String email, String password) throws Exception {
        Map<String, String> auth = new HashMap<>();
        auth.put("email", email);
        auth.put("password", password);

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.docs-dispatcher.io/auth"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(gson.toJson(auth)))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        Map data = gson.fromJson(response.body(), Map.class);
        return (String) data.get("token");
    }

    public Map sendForSignature(String jwtToken, Map<String, Object> esignData) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.docs-dispatcher.io/api/esign"))
            .header("Authorization", authHeader)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(gson.toJson(esignData)))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        return gson.fromJson(response.body(), Map.class);
    }

    public static void main(String[] args) throws Exception {
        ESignDispatcher dispatcher = new ESignDispatcher();
        String jwtToken = dispatcher.authenticate("[email protected]", "password");

        Map<String, Object> esignData = new HashMap<>();
        // Build esign data...

        Map result = dispatcher.sendForSignature(jwtToken, esignData);
        System.out.println("Sent for signature: " + result.get("success"));
    }
}

Provider-Specific Features

Universign

Unique features:

• Qualified signatures (highest legal value)

• Advanced certificate options

• French market leader

Signaturit

Unique features:

• Multi-language support (30+ languages)

• Certified email integration

• SMS authentication

Yousign

Unique features:

• Affordable pricing

• Simple API

• EU-based

Best Practices

1. Set Reasonable Expiration

{
  "expiresIn": 30 // days
}

2. Use Sequential Signing When Order Matters

{
  "sequential": true,
  "signers": [
    { "order": 1, "email": "[email protected]" },
    { "order": 2, "email": "[email protected]" }
  ]
}

3. Implement Reminders

{
  "reminderFrequency": 7 // days
}

Error Handling

Common Errors

Invalid Signer Email

{
  "error": "invalid_signer",
  "message": "Invalid email address for signer: invalid-email"
}

Signature Type Not Supported

{
  "error": "unsupported_signature_type",
  "message": "QUALIFIED signature not supported by Yousign"
}

Next Steps

Related Recipes

• Async Flow - Handle signature webhooks

• Upload - Upload signed documents

Summary

You've learned:

• ✅ Send documents for electronic signature

• ✅ Configure multiple signers and order

• ✅ Handle signature events via webhooks

• ✅ Provider-specific features

• ✅ Complete implementations in 4 languages

Electronic signatures streamline contract workflows!