---

name: digisign description: Czech electronic signature API integration for DigiSign. Use when the user needs to create, send, and manage digital signature envelopes, upload documents for signing, track signature status, or integrate embedded signing flows. Supports multiple signature types, webhooks for status tracking, and Czech Bank iD verification. Triggers on mentions of DigiSign, elektronicky podpis, digital signatures, envelope signing, or document signing workflows.

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

| Environment | URL | Purpose | |-------------|-----|---------| | Production | https://api.digisign.org | Live operations | | Staging | https://api.staging.digisign.org | Testing (contact podpora@digisign.cz for access) | | OpenAPI Docs | https://api.digisign.org/api/docs | Interactive documentation | | OpenAPI JSON | https://api.digisign.org/api/docs.json | Import to Postman |

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:

| Operator | Example | Description | |----------|---------|-------------| | [eq] | status[eq]=completed | Equals | | [neq] | status[neq]=draft | Not equals | | [in] | status[in][]=sent&status[in][]=completed | In array | | [contains] | name[contains]=contract | Contains string | | [starts_with] | email[starts_with]=john | Starts with | | [gt] | createdAt[gt]=2024-01-01 | Greater than | | [gte] | createdAt[gte]=2024-01-01 | Greater than or equal | | [lt] | validTo[lt]=2024-12-31 | Less than | | [lte] | validTo[lte]=2024-12-31 | Less than or equal |

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

| Status | Meaning | |--------|---------| | 200 | Success | | 201 | Created | | 204 | No content (successful delete) | | 400 | Bad request - check violations field | | 401 | Authentication failed - get new token | | 403 | Forbidden - insufficient permissions | | 404 | Resource not found | | 422 | Validation error - check violations | | 429 | Rate limit exceeded |

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:

| # | Step | Endpoint | |---|------|----------| | 1 | Authenticate | POST /api/auth-token | | 2 | Create envelope | POST /api/envelopes | | 3 | Add documents | POST /api/files + POST /api/envelopes/{id}/documents | | 4 | Add recipients | POST /api/envelopes/{id}/recipients | | 5 | Add signature tags | POST /api/envelopes/{id}/tags or /tags/by-placeholder | | 6 | Send envelope | POST /api/envelopes/{id}/send | | 7 | Download signed docs | GET /api/envelopes/{id}/download |

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

| Status | Description | |--------|-------------| | draft | Not yet sent, can be edited | | sent | Sent, waiting for signatures | | completed | All recipients signed | | expired | Deadline passed without completion | | declined | Signer declined to sign | | disapproved | Approver disapproved | | cancelled | Cancelled by sender |

Recipient Roles

| Role | Description | |------|-------------| | signer | Remote signer - receives email with signing link | | in_person | Signs in person on intermediary's device | | cc | Copy recipient - receives completed documents only | | approver | Approves or rejects document | | autosign | Automatic signature with company seal | | semi_autosign | Triggered automatic signature via API call |

Recipient Statuses

| Status | Description | |--------|-------------| | draft | Not yet sent | | sent | Invitation sent | | delivered | Opened the signing link | | signed | Completed signing | | declined | Declined to sign | | disapproved | Disapproved (for approvers) | | cancelled | Cancelled | | authFailed | Authentication failed (3 attempts exhausted) |

Signature Types

| Type | Description | |------|-------------| | simple | Simple electronic signature | | biometric | Handwritten signature capture | | bank_id_sign | Bank iD Sign (qualified, Czech) | | certificate | Certificate-based signature |

Authentication Methods

| Method | Description | |--------|-------------| | none | No authentication required | | sms | SMS code verification | | bank_id | Bank iD verification (Czech national identity) |

Tag Types

| Type | Description | |------|-------------| | signature | Signature field (required for signers) | | approval | Approval stamp field | | text | Text input field | | document | ID document photos field | | attachment | File attachment field | | checkbox | Checkbox field | | radio_button | Radio button (use with group) | | date_of_signature | Auto-filled signature date |

Tag Positioning

| Position | Description | |----------|-------------| | top_left | Tag top-left at placeholder top-left | | top_center | Tag top-center at placeholder top-center | | top_right | Tag top-right at placeholder top-right | | middle_left | Tag middle-left at placeholder middle-left | | center | Tag center at placeholder center | | middle_right | Tag middle-right at placeholder middle-right | | bottom_left | Tag bottom-left at placeholder bottom-left | | bottom_center | Tag bottom-center at placeholder bottom-center | | bottom_right | Tag bottom-right at placeholder bottom-right |

Channels

| Channel | Description | |---------|-------------| | email | Notifications via email | | sms | Notifications via SMS |

Webhook Events

Envelope Events

| Event | Description | |-------|-------------| | envelopeSent | Envelope was sent | | envelopeCompleted | All signatures completed | | envelopeExpired | Deadline passed | | envelopeDeclined | Signer declined | | envelopeDisapproved | Approver disapproved | | envelopeCancelled | Cancelled by sender | | envelopeDeleted | Envelope deleted |

Recipient Events

| Event | Description | |-------|---------