API Documentation

Official SDKs

eSignBase provides an official Python client that wraps the REST API and simplifies authentication, request handling, and error processing.

The SDK is optional — all functionality is available via the REST API — but it can significantly reduce integration effort for Python-based systems.

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

install via: pip install esignbase-sdk

General Information

All dates in this documentation follow the ISO 8601 format: YYYY-MM-DDTHH:MM:SS+00:00. For example: 2025-08-25T13:49:00+00:00.

IDs such as the document ID or template ID are currently UUIDs. However, we recommend not relying on any specific format and treating them simply as unique strings.

Authentication

The eSignBase API is using OAuth2 for authentication. You need to include the OAuth2 access token in the header of every call made to our API.

How to get a Access Token

First, retrieve your Client ID and Client Secret at https://app.esignbase.com/oauth2/client by creating an OAuth2 Client.

Next, base64-encode the concatenation of the Client ID and Client Secret, separated by a colon (:):

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

With this, you can retrieve an access token.

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

scope can be:

all
read
create_document
delete
sandbox

The sandbox scope has a special significance. When included, the session is created in the sandbox environment. This means:

No credits will be consumed.
Only templates you created in the sandbox environment will be available.

Note: The all scope does not include the sandbox scope.

You can request multiple scopes by providing a space-separated list:

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

You use the access token in future API calls. The access token is valid for 5 minutes, after which a new one must be retrieved.

Revoke A Access Token

Request:

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

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

Templates

Templates are used to generate documents from which customer clients can fill out and sign. You can upload PDF’s to be used as templates here: https://app.esignbase.com/dashboard Once uploaded you should see the template in the template table at the dashboard. The action menu allows you to access the template editor where you can add form fields and signature fields to the template.

Get A List Of All Templates:

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

Supported Page Standards Are:

page_standard	Description
A4	A standard paper size commonly used internationally, measuring 210mm x 297mm (8.27in x 11.69in).
letter	A common paper size used in the United States and Canada, measuring 8.5in x 11in (216mm x 279mm).

Get Infos For One Specific Template:

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

For each value in form_role_names defined in a template, a corresponding recipient must be specified in the “Create Document” request by using the role_name field. You can define template role_name in the Web Application using the template editor.

Documents

Get A List Of All Documents:

Retrieval of documents is paginated. You can retrieve a maximum of 100 documents at a time by setting the limit parameter. The offset parameter specifies the starting point for the retrieval.

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
}

The count field in the response let you know how many documents are available and with this what should be the maximum offset during pagination.

Document Status

The following table describes the possible status for a document:

Status	Description
`DRAFT`	Document created but not yet sent to any recipients.
`PARTIALLY_SENT`	Sent to some of the recipients but not all.
`SENT`	Sent to all recipients.
`PARTIALLY_SIGNED`	Signed by some signees but not all.
`WAITING_FOR_ESIGNATURE`	Fully signed by all parties, and generating a PDF with an electronic signature is in work.
`ESIGNATURE_CREATED`	Fully signed by all parties, and a PDF with an electronic signature has been generated.
`COMPLETED`	Document signing procedure is complete.
`VOIDED`	Document has been voided.

user_defined_metadata is an optional field represented as a JSON object where each value must be a string. It can be used to include additional information relevant to the document signing process. A document can have a maximum of 10 fields in a user_defined_metadata object. Each field can have up to 500 characters the keys can be up to 25 characters.

Get Infos For One Specific Document:

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

Create A New Document

Creating a new document means that we use an existing template, define who will be the recipients for the document. Calling this API endpoint will result in a new signing request.

A template definition has the field form_role_names., For example"form_role_names": ["signee_1"]. If you want to create a new document from this template you need one recipient with this role_name. In the example case would this be: "role_name": "signee_1".

The document creation allows optionally to store user defined data in user_defined_metadata. The value is a json object where keys and values are strings. Recipients must match the required signee roles assigned to the template. A locale can be defined for a recipient. The locale will be used when sending e-mails to the recipient. If no locale is defined en will be used as default.

Supported locales:

Locale	Language
en	English
de	German
es	Spanish

The expiration_date field is optional. Once a document expires the document status will be VOIDED. Once a document was created it can not edited anymore.

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

Delete A Existing Document

Request:

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

If the operation is successful, an HTTP 200 OK status will be returned.

Webhook for Completed Signature Processes

To be notified when a signature process is completed, activate the “Document Completed Hook” in the API Settings.

Security Validation: Each webhook request includes a signature header for validation. Use the displayed “Document Completed Hook Secret” to verify the authenticity of the request.

Configuration:

Enter the callback URL that should be called when a document is completed
Requests are made via the POST method
Validate each request using the signature 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>"
}

Check How Many Document Credits Are Available

One credit is required to start the signing process for a document, regardless of the number of signatures or recipients involved.

Request:

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

Response:

{"credits": 100}