esignbase-sdk 1.1.0

Python SDK for eSignBase – eIDAS-compliant digital signatures and GDPR-ready electronic signing via REST API.

eSignBase Python SDK

Official Python SDK for integrating eIDAS-compliant digital signatures into your application using the eSignBase REST API.

eSignBase provides GDPR-ready electronic signatures with EU-based infrastructure and flexible pay-as-you-go pricing — no subscriptions, no per-seat licenses.

This SDK offers a simple, synchronous client for creating signing requests, managing templates, and retrieving signed documents programmatically.

Why eSignBase?

• ✅ eIDAS-compliant electronic signatures
• ✅ GDPR-aligned EU data hosting
• ✅ Simple REST API
• ✅ No subscriptions — pay-as-you-go credits
• ✅ Lightweight and easy to integrate

Documentation

Full REST API documentation: https://esignbase.com/en/api_documentation

A step-by-step integration guide: https://esignbase.com/en/blog/rest-api-guide

Classes

GrantType (Enum)

Defines the available OAuth2 grant types:

• CLIENT_CREDENTIALS: For server-to-server authentication
• AUTHORIZATION_CODE: For user-specific authentication

Scope (Enum)

Defines the available API permission scopes:

• ALL: Full access to all API endpoints
• READ: Read-only access
• CREATE_DOCUMENT: Permission to create documents
• DELETE: Permission to delete documents
• SANDBOX: Access to the sandbox environment, use this scope for testing

OAuth2Client

Main client class that stores authentication credentials and state.

Attributes:

id (str) # Client ID from ESignBase
secret (str) # Client secret from ESignBase
grant_type (GrantType) # OAuth2 grant type to use
user_name (Optional[str]) # Username (required AUTHORIZATION_CODE)
password (Optional[str]) # Password (required AUTHORIZATION_CODE)
scope (list[Scope]) # List of requested API scopes

Retrieve your Client ID and Client Secret at https://app.esignbase.com/oauth2/client by creating an OAuth2 Client Configuration.

Recipient

Represents a document recipient/signer. role_name value is defined during template creation in the template editor.

Attributes:

email (str) # Recipient's email address
first_name (str) # Recipient's first name
last_name (str) # Recipient's last name
role_name (str) # Role name (e.g., "Signer", "Viewer")
locale (str) # Locale code ("de", "en", "es")

ESignBaseSDKError (Exception)

Custom exception class for API-related errors.

Functions

def connect(client: OAuth2Client) -> None

Authenticates with the ESignBase API

Parameters:

client: Configured OAuth2Client instance

Raises:

ESignBaseSDKError: If authentication fails or validation fails

Example:

client = OAuth2Client(
    id="your_client_id",
    secret="your_client_secret",
    grant_type=GrantType.CLIENT_CREDENTIALS,
    scope=[Scope.ALL],
)
connect(client)

---

def get_templates(client: OAuth2Client) -> list[dict[str, Any]]

Retrieves a list of available document templates.

Parameters:

client: Authenticated OAuth2Client instance

Returns A list of dictionaries containing template data.

Raises:

ESignBaseSDKError: If the API request fails

---

def get_template(client: OAuth2Client, template_id: str) -> dict[str, Any]

Retrieves details of a specific template.

Parameters:

client: Authenticated OAuth2Client instance
template_id: Unique identifier of the template

Returns: Dictionary containing template details

Raises: ESignBaseSDKError: If the API request fails

---

def get_documents(client: OAuth2Client, limit: int, offset: int) -> dict[str, Any]

Retrieves a paginated list of documents.

Parameters:

client: Authenticated OAuth2Client instance
limit: Maximum number of documents to return
offset: Pagination offset

Returns:

Dictionary containing document list and pagination info `{documents: [...]}`

Raises:

ESignBaseSDKError: If the API request fails

---

def get_document(client: OAuth2Client, document_id: str) -> dict[str, Any]

Retrieves details of a specific document.

Parameters:

client: Authenticated OAuth2Client instance
document_id: Unique identifier of the document

Returns:

Dictionary containing document details

Raises:

ESignBaseSDKError: If the API request fails

---

def create_document(
    client: OAuth2Client,
    *,
    template_id: str,
    document_name: str,
    recipients: list[Recipient],
    user_defined_metadata: Optional[dict[str, str | int]] = None,
    expiration_date: Optional[datetime] = None
) -> dict[str, Any]

Creates a new document from a template.

Parameters:

client: Authenticated OAuth2Client instance
template_id: ID of the template to use
document_name: Name for the new document
recipients: List of Recipient objects
user_defined_metadata: Optional metadata to attach to the document
expiration_date: Optional expiration date for the document

Returns:

Dictionary containing the created document id and current document status

Raises:

ESignBaseSDKError: If the API request fails

Example:

recipients = [
    Recipient(
        email="[e-mail]",
        first_name="John",
        last_name="Doe",
        role_name="signer",
        locale="de"
    )
]

document = create_document(
    client=client,
    template_id="template_123",
    document_name="Contract Agreement",
    recipients=recipients,
    user_defined_metadata={"contract_id": "CTR-2024-001"},
    expiration_date=datetime(2024, 12, 31)
)

---

def delete_document(client: OAuth2Client, document_id: str) -> None

Deletes a specific document.

Parameters:

client: Authenticated OAuth2Client instance
document_id: Unique identifier of the document to delete

Raises:

ESignBaseSDKError: If the API request fails

---

def download_document(client: OAuth2Client, document_id: str) -> Generator[bytes]

Download a completed document.

Parameters:

client: Authenticated OAuth2Client instance
document_id: Unique identifier of the document to download

Raises:

ESignBaseSDKError: If the API request fails

Example Usage:

    with open(f"document.pdf", "wb") as f:
        for chunk in esignbase_sdk.download_document(client, "695e4a4d869ba75efa33aa07"):
            f.write(chunk)

---

def get_credits(client: OAuth2Client) -> dict[str, Any]

Retrieves credit balance information.

Parameters:

client: Authenticated OAuth2Client instance

Returns:

Dictionary containing credit balance data

Raises:

ESignBaseSDKError: If the API request fails

Error Handling

All functions raise ESignBaseSDKError exceptions for API errors, network issues, or validation failures. Always wrap API calls in try-except blocks:

try:
    templates = get_templates(client)
except ESignBaseSDKError as e:
    print(f"API Error: {e}")

Complete Example

from datetime import datetime
import esignbase_sdk

# Setup client
client = esignbase_sdk.OAuth2Client(
    id="your_client_id",
    secret="your_client_secret",
    grant_type=GrantType.CLIENT_CREDENTIALS,
    scope=[Scope.CREATE_DOCUMENT, Scope.READ]
)

# Authenticate
esignbase_sdk.connect(client)

# Get available templates
templates = esignbase_sdk.get_templates(client)

# Create a document
recipients = [
    esignbase_sdk.Recipient(
        email="[e-mail]",
        first_name="Alice",
        last_name="Smith",
        role_name="Signer",
        locale="en"
    )
]
template_id = templates[0]["id"]

document = esignbase_sdk.create_document(
    client=client,
    template_id=template_id,
    document_name="NDA Agreement",
    recipients=recipients
)

# Check document status
document_details = esignbase_sdk.get_document(client, document["id"])

# Delete the document (if needed)
esignbase_sdk.delete_document(client, document["id"])

Developer Notes:

To build the package, run the following commands inside a virtual environment from the directory containing this README file.

python -m pip install --upgrade build
python -m build --wheel