API-Dokumentation

Inhaltsverzeichnis

Offizielles SDK
Allgemeine Informationen
Authentifizierung
- Client Credentials Grant
  - So erhältst du ein Access Token
  - Ein Access Token widerrufen
- Authorization Code Grant
Vorlagen
- Liste aller Templates abrufen
- Informationen zu einem bestimmten Template abrufen
Dokumente
Webhook für abgeschlossene Signaturprozesse
Verfügbare Credits prüfen

Offizielle SDKs

eSignBase stellt offizielle SDKs für verschiedene Programmiersprachen bereit. Diese erleichtern die Integration mit unserer REST API, indem sie Authentifizierung, Request-Handling und Fehlerbehandlung übernehmen.

Die SDKs sind optional – Sie können selbstverständlich auch direkt mit der REST API arbeiten.

Python

Quellcode & Issues: GitHub - esignbase-python-sdk
Paket: PyPI - esignbase-sdk

Installation:

pip install esignbase-sdk

Node.js

Quellcode & Issues: GitHub - esignbase-node-sdk
Paket: npm - esignbase-sdk

Installation:

npm install esignbase-sdk

Hinweis: Das Node.js SDK erfordert Node.js Version 18 oder höher.

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.

Wenn Sie nach einer Schritt-für-Schritt-Anleitung suchen, lesen Sie unseren Leitfaden: Dokumente erstellen und signieren mit der eSignBase REST API mit der eSignBase REST-API.

Authentifizierung

Die eSignBase API verwendet OAuth2 für die Authentifizierung. Je nach Anwendungsfall werden zwei Grant-Types unterstützt.

Grant Type	Anwendungsfall
Client Credentials	Server-zu-Server-Integrationen, bei denen Sie beide Seiten kontrollieren. Einfacher zu implementieren.
Authorization Code	Drittanbieter-Integrationen (z. B. Zapier, Make), bei denen Ihre App im Namen eines eSignBase-Benutzers handelt.

In beiden Fällen muss jede API-Anfrage den Access Token im Header enthalten:

Authorization: Bearer <your_access_token>

Client Credentials Grant

Bestens geeignet für direkte API-Integrationen, bei denen Sie das eSignBase-Konto kontrollieren.

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 {#revoke-a-access-token}

Request:

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

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

Authorization Code Grant

Verwenden Sie diesen Grant-Type, wenn Sie Drittanbieter-Integrationen bauen, bei denen Ihre Anwendung im Namen eines eSignBase-Benutzers handelt — zum Beispiel Integrationen mit Zapier oder Make. Der Benutzer meldet sich bei eSignBase an und genehmigt die angeforderten Berechtigungen; Ihre Anwendung verarbeitet dabei niemals das Passwort des Benutzers.

Registrieren Sie vorab Ihren OAuth2-Client unter https://app.esignbase.com/oauth2/client und tragen Sie die Redirect-URI in die erlaubten URIs ein.

Schritt 1: Benutzer zum Authorisierungs-Endpunkt weiterleiten {#schritt-1-benutzer-zum-authorisierungs-endpunkt-weiterleiten}

Leiten Sie den Browser des Benutzers weiter an:

GET https://app.esignbase.com/oauth2/authorize

mit den folgenden Query-Parametern:

Parameter	Erforderlich	Beschreibung
`client_id`	Ja	Ihre OAuth2 Client ID.
`response_type`	Ja	Muss `code` sein.
`redirect_uri`	Ja	URI, zu der nach Genehmigung weitergeleitet wird. Muss mit der registrierten URI übereinstimmen.
`scope`	Ja	Space-separierte Liste der angeforderten Scopes.
`state`	Empfehlenswert	Zufälliger String zur CSRF-Prävention; wird unverändert zurückgegeben.

Beispiel-URL:

https://app.esignbase.com/oauth2/authorize
    ?client_id=YOUR_CLIENT_ID
    &response_type=code
    &redirect_uri=https://yourapp.com/oauth/callback
    &scope=all
    &state=random_csrf_string

Nach Genehmigung wird der Benutzer zu Ihrer redirect_uri weitergeleitet mit einem Kurzlebigen Autorisierungscode:

https://yourapp.com/oauth/callback?code=AUTH_CODE&state=random_csrf_string

Schritt 2: Den Code gegen ein Access Token tauschen {#schritt-2-den-code-gegen-ein-access-token-tauschen}

Tauschen Sie den Autorisierungscode serverseitig aus:

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

Body (form-encoded):
    grant_type=authorization_code
    &code=AUTH_CODE
    &redirect_uri=https://yourapp.com/oauth/callback

Response:

{
    "access_token": "<your_access_token>",
    "refresh_token": "<your_refresh_token>",
    "token_type": "Bearer",
    "expires_in": 300
}

Access Tokens sind 5 Minuten gültig. Verwenden Sie das refresh_token, um ohne erneute Benutzerinteraktion einen neuen Access Token zu erhalten.

Schritt 3: Ein Access Token auffrischen {#schritt-3-ein-access-token-auffrischen}

Wenn ein Access Token abläuft, tauschen Sie den Refresh Token aus:

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

Body (form-encoded):
    grant_type=refresh_token
    &refresh_token=<your_refresh_token>

Response:

{
    "access_token": "<new_access_token>",
    "refresh_token": "<new_refresh_token>",
    "token_type": "Bearer",
    "expires_in": 300
}

Speichern Sie den jeweils neuen refresh_token, da Refresh-Tokens rotieren können.

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.

Dokumente

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 {#document-status}

The following table describes the possible status for a document:

Status	Beschreibung
`DRAFT`	Dokument erstellt, aber noch nicht an Empfänger gesendet.
`PARTIALLY_SENT`	An einige Empfänger gesendet, aber nicht an alle.
`SENT`	An alle Empfänger gesendet.
`PARTIALLY_SIGNED`	Von einigen Empfängern unterschrieben, aber nicht von allen.
`WAITING_FOR_PREPARATION`	Dokument wurde von allen Parteien vollständig unterschrieben, aber die Task-Queue hat noch kein PDF generiert.
`WAITING_FOR_DIGITAL_SIGNATURE`	Aus den Dokumentdaten wurde ein PDF generiert und wartet auf die Anbringung einer digitalen Signatur.
`DIGITAL_SIGNATURE_CREATED`	Dokument wurde vollständig unterschrieben und wir haben ein PDF mit einer digitalen Signatur erzeugt.
`COMPLETED`	Der Unterzeichnungsprozess 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"}

Download eines abgeschlossenen Dokuments

Lädt das finalisierte, signierte PDF eines Dokuments herunter.

Ein Dokument kann nur heruntergeladen werden, wenn es einen der folgenden Status erreicht hat:

DIGITAL_SIGNATURE_CREATED
COMPLETED

Request:

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

Response

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="yourfile.pdf"
Content-Length: <file_size_in_bytes>
Last-Modified: Tue, 18 Feb 2026 12:34:56 GMT
Accept-Ranges: bytes

<binary pdf content>

Der Endpoint unterstützt Range-Requests:

Range: bytes=0-1023 Erfolgreiche partielle Antwort:

HTTP/1.1 206 Partial Content
Content-Range: bytes 0-1023/245678

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 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}