DigiSign API

Czech electronic signature service REST API integration. This skill provides both CLI scripts for quick operations and comprehensive API documentation for implementing DigiSign into your applications.

API Overview

Base URLs

Authentication

DigiSign uses Bearer token authentication (RFC 6750).

Step 1: Exchange credentials for token

POST /api/auth-token
Content-Type: application/json

{
  "accessKey": "your-access-key",
  "secretKey": "your-secret-key"
}

Response:

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "exp": 1682572132,
  "iat": 1682485732
}

Step 2: Use token in all subsequent requests

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...

Token is valid for ~24 hours. Get a new one when expired.

API Key Setup

1. Log into DigiSign selfcare at https://app.digisign.org
2. Go to Settings > For Developers > API Keys
3. Click "New API Key" and configure permissions
4. Save accessKey and secretKey securely (shown only once)

Response Formats

Pagination

All list endpoints return paginated responses:

{
  "items": [...],
  "count": 127,
  "page": 1,
  "itemsPerPage": 30
}

Query parameters:

• page - Page number (default: 1)
• itemsPerPage - Items per page (default: 30, max: 500)

Filtering

List endpoints support filter operators as query parameters:

Sorting

order[createdAt]=desc
order[updatedAt]=asc

Available sort fields: createdAt, updatedAt, validTo, completedAt, cancelledAt, declinedAt

Error Responses

{
  "type": "https://tools.ietf.org/html/rfc2616#section-10",
  "title": "An error occurred",
  "status": 400,
  "violations": [
    {
      "propertyPath": "email",
      "message": "This value is not a valid email address."
    }
  ]
}

HTTP Status Codes

Important API Notes

• Omitting an attribute in request body = don't change it (for updates)
• Sending null = explicitly set to null (may error if not nullable)
• HATEOAS: Responses include _actions and _links for navigation
• Localization: Set Accept-Language: en|cs|sk|pl for localized error messages

Core Workflow

The typical envelope signing workflow has 7 steps:

Example: Create and Send Envelope

// 1. Authenticate
const tokenRes = await fetch('https://api.digisign.org/api/auth-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    accessKey: process.env.DIGISIGN_ACCESS_KEY,
    secretKey: process.env.DIGISIGN_SECRET_KEY
  })
});
const { token } = await tokenRes.json();

const headers = {
  'Authorization': `Bearer ${token}`,
  'Content-Type': 'application/json'
};

// 2. Create envelope
const envelopeRes = await fetch('https://api.digisign.org/api/envelopes', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'Contract Agreement',
    emailBody: 'Please review and sign the attached contract.'
  })
});
const envelope = await envelopeRes.json();

// 3. Upload file
const formData = new FormData();
formData.append('file', fs.createReadStream('contract.pdf'));
const fileRes = await fetch('https://api.digisign.org/api/files', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}` },
  body: formData
});
const file = await fileRes.json();

// 4. Add document to envelope
await fetch(`https://api.digisign.org/api/envelopes/${envelope.id}/documents`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    file: `/api/files/${file.id}`,
    name: 'Contract'
  })
});

// 5. Add recipient
const recipientRes = await fetch(`https://api.digisign.org/api/envelopes/${envelope.id}/recipients`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    role: 'signer',
    name: 'John Doe',
    email: 'john@example.com'
  })
});
const recipient = await recipientRes.json();

// 6. Add signature tag (by placeholder)
await fetch(`https://api.digisign.org/api/envelopes/${envelope.id}/tags/by-placeholder`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    recipient: `/api/envelopes/${envelope.id}/recipients/${recipient.id}`,
    type: 'signature',
    placeholder: '{{sign_here}}',
    positioning: 'center'
  })
});

// 7. Send envelope
await fetch(`https://api.digisign.org/api/envelopes/${envelope.id}/send`, {
  method: 'POST',
  headers
});

Enums Reference

Envelope Statuses

Recipient Roles

Recipient Statuses

Signature Types

Authentication Methods

Tag Types

Tag Positioning

Channels

Webhook Events

Envelope Events

Recipient Events

Webhook Payload Format

{
  "id": "3974d252-b027-46df-9fd8-ddae54bc9ab9",
  "event": "envelopeCompleted",
  "name": "envelope.completed",
  "time": "2021-06-07T14:07:23+02:00",
  "entityName": "envelope",
  "entityId": "4fcf171c-4522-4a53-8a72-784e1dd36c2a",
  "data": {
    "status": "completed"
  }
}

Webhook Signature Verification

Header format: Signature: t={timestamp},s={signature}

import hmac
import hashlib
import time

def verify_webhook(signature_header, body, secret):
    # Parse header
    parts = dict(p.split('=') for p in signature_header.split(','))
    timestamp = int(parts['t'])
    signature = parts['s']

    # Check timestamp (5 minute window)
    if abs(time.time() - timestamp) > 300:
        raise Exception('Request too old - possible replay attack')

    # Verify signature
    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.{body}".encode(),
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        raise Exception('Invalid signature')

    return True

Webhook Retry Schedule

12 attempts over ~7 days if delivery fails:

CLI Scripts Reference

For quick operations, use the bundled Python scripts:

Environment Variables

export DIGISIGN_ACCESS_KEY="your-access-key"
export DIGISIGN_SECRET_KEY="your-secret-key"
# Optional: use staging for testing
export DIGISIGN_API_URL="https://api.staging.digisign.org"

Quick Start with Scripts

# Authenticate
python scripts/auth.py get-token --save

# List envelopes
python scripts/envelope.py list

# Create and send envelope
python scripts/envelope.py create --name "Contract" --email-body "Please sign"
python scripts/document.py upload contract.pdf
python scripts/document.py add <envelope_id> --file-id <file_id> --name "Contract"
python scripts/recipient.py add <envelope_id> --role signer --name "John Doe" --email "john@example.com"
python scripts/tag.py add-by-placeholder <envelope_id> --recipient <rec_id> --type signature --placeholder "{{sign}}"
python scripts/envelope.py send <envelope_id> --yes

Czech-Specific Notes

Bank iD (Bankovni identita)

Czech national identity verification system through participating banks.

• Use authenticationOnOpen: "bank_id" or authenticationOnSignature: "bank_id"
• Verifies signer identity through their online banking
• Required for qualified electronic signatures

Qualified Electronic Signature

For legally binding signatures in Czech Republic:

• Set signatureType: "bank_id_sign"
• Requires Bank iD verification
• Compliant with eIDAS regulation

Audit Log (Protokol)

Every envelope includes a detailed audit log:

• Download with GET /api/envelopes/{id}/download?include_log=true
• Or get only the log: GET /api/envelopes/{id}/download?output=only_log

Timestamping

Enable qualified timestamps on documents:

• Set timestampDocuments: true in envelope properties
• Available authorities: ica_tsa (I.CA)

Cost Warning

DigiSign charges per envelope sent. These operations are FREE:

• Creating/editing draft envelopes
• Uploading documents
• Managing recipients and tags
• Webhook setup
• Generating embed URLs
• Listing and reading resources

BILLING TRIGGER: POST /api/envelopes/{id}/send - sends real emails and incurs charges.

References

Detailed documentation for each resource:

• authentication.md - Token exchange and management
• api-reference.md - Complete endpoint reference
• envelopes.md - Envelope lifecycle and attributes
• recipients.md - Recipient roles and options
• tags.md - Tag positioning and types
• webhooks.md - Event list and verification
• embedding.md - Embedded signing integration