API-Dokumentation

Offizielles SDKs

eSignBase stellt einen offizielles Python SDK bereit. Dieses erlaubt die REST API zu verwenden und erleichtert authentifizierung, request handling, und Fehlerbehandlung.

Das SDK ist optional — sämtliche funktionalität ist verfügbar über die REST API.

Python SDK (GitHub): https://github.com/matt-the-midnight-hacker/esignbase-python-sdk
Python SDK (PyPI): https://pypi.org/project/esignbase-sdk/

Es kann installiert werden mit pip install esignbase-sdk

Allgemeine Informationen

Alle Datumsangaben in dieser Dokumentation folgen dem ISO-8601-Format: YYYY-MM-DDTHH:MM:SS+00:00. Zum Beispiel: 2025-08-25T13:49:00+00:00.

IDs wie die Document ID oder Template ID sind derzeit UUIDs. Es wird jedoch empfohlen, sich nicht auf ein bestimmtes Format zu verlassen und sie lediglich als eindeutige Zeichenketten zu behandeln.

Authentifizierung

Die eSignBase API verwendet OAuth2 für die Authentifizierung. Der OAuth2 access token muss im Header jeder API-Anfrage enthalten sein.

So erhältst du ein Access Token

Zuerst kannst du deine Client ID und deinen Client Secret unter https://app.esignbase.com/oauth2/client erstellen und abrufen.

Danach wird die Kombination aus Client ID und Client Secret, getrennt durch einen Doppelpunkt (:), base64-kodiert:

basic_auth_credentials = base64(client_id + ":" + client_secret)

Mit diesen Zugangsdaten kannst du ein access token anfordern.

Request:

POST: /oauth2/token
headers:
  Authorization Basic <basic_auth_credentials>
  Content-Type: application/x-www-form-urlencoded

POST Body (form encoded):
grant_type=client_credentials&scope=all

Mögliche Werte für scope:

all
read
create_document
delete
sandbox

Der Scope sandbox hat eine besondere Bedeutung. Wenn er enthalten ist:

Wird die Sitzung in der Sandbox-Umgebung erstellt.
Es werden keine Credits verbraucht.
Nur die Vorlagen, die du zuvor in der Sandbox erstellt hast, stehen zur Verfügung.

Hinweis: Der Scope all enthält nicht den scope sandbox.

Mehrere Scopes anfordern Du kannst mehrere Scopes anfordern, indem du eine durch Leerzeichen getrennte Liste angibst:

POST /oauth2/token
Headers:
  Authorization: Basic <basic_auth_credentials>
  Content-Type: application/x-www-form-urlencoded

Body (form-encoded):
  grant_type=client_credentials&scope=all sandbox

Response:

{ "access_token": "<your_access_token>" }

Der access token muss in allen nachfolgenden API-Calls verwendet werden. Er ist 5 Minuten gültig. Danach muss ein neuer token angefordert werden.

Revoke eines Access Tokens

Request:

POST: /oauth2/revoke
headers:
Content-Type: application/x-www-form-urlencoded

POST Body (form encoded):
token=<your_access_token>

Templates

Templates dienen dazu, Dokumente zu erstellen, die von Endkunden ausgefüllt und unterschrieben werden können. Du kannst PDFs als Templates unter https://app.esignbase.com/dashboard

Liste aller Templates abrufen:

Request:

GET /api/templates
headers:
Authentication: Bearer <your_access_token>

Response:

[
    {
        "id": "the_template_id",
        "ctime": "2025-08-25T13:49:00+00:00",
        "filename": "my_file.pdf",
        "num_of_pages": 2,
        "page_standard": "a4",
        "form_role_names": ["signee_1"]
    },
    {
        "id": "another_template_id",
        "ctime": "2025-08-25T14:49:00+00:00",
        "filename": "my_other_file.pdf",
        "num_of_pages": 1,
        "page_standard": "letter",
        "form_role_names": ["signee_1", "viewer_1"]
    }
]

Unterstützte Seitenformate:

page_standard	Beschreibung
A4	International genutztes Standardformat, 210mm x 297mm (8.27in x 11.69in).
letter	In den USA und Kanada gängiges Format, 8.5in x 11in (216mm x 279mm).

Informationen zu einem bestimmten Template abrufen:

Request:

GET /api/template/<template_id>
headers:
Authentication: Bearer <your_access_token>

Response:

    {
        "id": "<template_id>",
        "ctime": "2025-08-25T13:49:00+00:00",
        "filename": "my_file.pdf",
        "num_of_pages": 2,
        "page_standard": "a4",
        "form_role_names": ["signee_1"]
    }

Für jeden form_role_name in einem Template muss beim Erstellen eines Dokuments ein passender recipient mit dem entsprechenden role_name angegeben werden. Diese Rollen können im Template-Editor der Webanwendung definiert werden.

Documents

Liste aller Dokumente abrufen:

Die Dokumentliste ist paginated. Maximal 100 Dokumente können gleichzeitig durch den Parameter limit abgerufen werden. Der Parameter offset definiert den Startpunkt für den Abruf.

Request:

GET /api/documents?limit=1&offset=0
headers:
Authentication: Bearer <your_access_token>

Response:

{
    "documents": [
        {
            "id": "the_document_id",
            "template_id": "template_id_this_document_is_based_of",
            "name": "Employee Contract",
            "owner": "name used in mails if send to signees",
            "ctime": "2025-08-25T13:49:00+00:00",
            "mtime": "2025-09-25T13:49:00+00:00",
            "expiration_date": "2025-10-25T13:49:00+00:00",
            "page_standard": "a4",
            "num_of_pages": 2,
            "completed_date": null,
            "status": "SENT",
            "recipients": [
                {
                    "email": "signee@mail.com",
                    "first_name": "John",
                    "last_name": "Doe",
                    "days_before_voided": 5,
                    "form_role": "signee_1",
                    "locale": "en"
                }
            ],
            "user_defined_metadata" {
                "internal_id": "42",
                "internal-name": "contract-developer"
            }
        }
    ],
    "count": 1
}

Das Feld count im response gibt an, wie viele Dokumente vorhanden sind und hilft bei der Bestimmung des maximalen offset-Werts für die Paginierung.

Document Status

The following table describes the possible status for a document:

Status	Beschreibung
`DRAFT`	Dokument wurde erstellt, aber noch nicht versendet.
`PARTIALLY_SENT`	An einige, aber nicht alle Empfänger versendet.
`SENT`	An alle Empfänger versendet.
`PARTIALLY_SIGNED`	Von einigen, aber nicht allen Empfängern unterschrieben.
`WAITING_FOR_ESIGNATURE`	Vollständig unterschrieben, PDF mit elektronischer Signatur wird erstellt.
`ESIGNATURE_CREATED`	PDF mit elektronischer Signatur wurde erfolgreich erstellt.
`COMPLETED`	Der Signaturprozess ist abgeschlossen.
`VOIDED`	Dokument wurde für ungültig erklärt.

Das Feld user_defined_metadata ist optional und enthält ein JSON-Objekt mit frei definierbaren Feldern.

Maximal 10 Felder
Schlüssel bis zu 25 Zeichen
Werte bis zu 500 Zeichen
Alle Werte müssen Strings sein

Informationen zu einem bestimmten Dokument abrufen:

Request:

GET /api/document/<document_id>
headers:
Authentication: Bearer <your_access_token>

Response:

{
    "id": "<document_id>",
    "template_id": "template_id_this_document_is_based_of",
    "name": "Employee Contract",
    "owner": "name used in mails if send to signees",
    "ctime": "2025-08-25T13:49:00+00:00",
    "mtime": "2025-09-25T13:49:00+00:00",
    "expiration_date": "2025-10-25T13:49:00+00:00",
    "page_standard": "a4",
    "num_of_pages": 2,
    "completed_date": null,
    "status": "COMPLETED",
    "recipients": [
        {
            "email": "signee@mail.com",
            "first_name": "John",
            "last_name": "Doe",
            "days_before_voided": 5,
            "form_role": "signee_1",
            "locale": "de"
        }
    ],
    "user_defined_metadata" {
        "internal_id": 42,
        "more_info": "some text"
    }
}

Ein neues Dokument erstellen

Ein neues Dokument wird auf Basis eines Templates erstellt. Dabei werden die Empfänger und optional Metadaten definiert. Durch den API-Call wird eine neue Signaturanfrage erzeugt.

Ein Template hat form_role_names, z. B. "form_role_names": ["signee_1"]. Um ein Dokument daraus zu erzeugen, muss ein Empfänger mit passendem role_name angegeben werden, z. B. "role_name": "signee_1".

Zusätzlich kann user_defined_metadata angegeben werden – ein JSON-Objekt mit String-Werten.

Der locale eines Empfängers definiert die Sprache für die E-Mails. Standard ist en. Unterstützte Sprachen:

Locale	Sprache
en	English
de	Deutsch
es	Spanisch

Das Feld expiration_date ist optional. Nach Ablauf ist der Status des Dokuments VOIDED, kann ein erstelltes Dokument nicht mehr bearbeitet werden.

Request:

POST /api/document
headers:
Content-Type: application/json
Authentication: Bearer <your_access_token>

Request data:

{
    "name":  "Your Contract",
    "template_id": "id_of_template_used_for_document",
    "recipients": [
        {
            "email": "signee@mail.com",
            "first_name": "John",
            "last_name": "Doe",
            "role_name": "signee_1",
            "locale": "es"
        }
    ],
    "user_defined_metadata": {
        "any_key": "any string value",
    },
    "expiration_date": "2025-09-25T13:49:00+00:00"
}

Response:

{"document_id": "new_doc_id", "status": "DRAFT"}

Ein bestehendes Dokument löschen

Request:

DELETE /api/document/<document_id>
headers:
Authentication: Bearer <your_access_token>

Bei Erfolg wird ein HTTP 200 OK zurückgegeben.

Webhook für abgeschlossene Signaturprozesse

Um über den Abschluss eines Signaturprozesses benachrichtigt zu werden, aktivieren Sie den “Dokument Abgeschlossen Hook” in den API Einstellungen.

Sicherheitsvalidierung: Jeder Webhook-Request enthält einen Signatur-Header zur Validierung. Verwenden Sie das angezeigte “Dokument Abgeschlossen Hook Secret”, um die Authentizität der Request zu überprüfen.

Konfiguration:

Tragen Sie die Callback-URL ein, die bei Dokumentabschluss aufgerufen werden soll
Requests erfolgen via POST-Methode
Validieren Sie jeden Request mit dem Signatur-Header

Request

POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
X-Signature-Secret: your_hook_secret_here

{
  "document_id": "<id of the document>",
  "status": "<the document status>"
}

Verfügbare Document Credits abfragen

Ein Credit wird benötigt, um einen Signaturprozess zu starten – unabhängig von der Anzahl an Empfängern oder Unterschriften.

Request:

GET /api/credits
headers:
Authentication: Bearer <your_access_token>

Response:

{"credits": 100}