API¶

Prerequisites¶

Before using the eSign API, ensure the following setup requirements are met:

User Access Requirements¶

API User Setup: Make sure you have an appropriate API user and it's corresponding authentication method. This can be done in Lime Admin by your administrator. The settings are found under System -> Security -> Users.
User Group Membership: The user making API calls must be a member of the Lime eSign users group (or the group configured in the eSign settings).
Coworker Link: The user must have a linked coworker record in the system. The API operations require access to coworker information for proper signing workflow execution.

Authentication¶

API calls must include appropriate authentication headers as per your Lime CRM configuration.

For detailed installation and configuration instructions, see the Installation Guide.

Create Signing¶

eSign has a simple API to be able to programmatically create signings. It's available both as a Python module and as REST.

Use the signing method option keys when setting the signing method(s).

Python¶

from limepkg_esign.api import EsignSigning

# Create signing based on document ids.
# Passing the language as third parameter is optional,
# otherwise default language is used.
signing = EsignSigning(app, [7458])

# At least one signer is required.
# Signers will be on order=1 as default.
signing.add_signer("Katja", "[email protected]")

# This signer is on second and linked to a parent limeobject.
signing.add_signer("Joelito", "[email protected]", 2, "person", 3001)

# At least one signing method is required
signing.add_method("bankid_se")
signing.add_method("checkbox")

# The signing properties will be prefilled, exactly as in the web client.
# Can be overriden as shown below.
signing.title = "Sign this this document, or else..."
signing.language = "da"
signing.message = "...you're in for a big surprise."

# More documents can be added
signing.add_document(6129)

# Save and start the signing process by creating the signing. 
# It will be created using checkpoints, just as every other signing.
signing_id = signing.create()

REST¶

The REST API is using the Python API module internally. Parameters are the same, but camel cased. Post JSON to limepkg-esign/api/signing/ with appropriate authentication headers. Will return the id of the created signing if succesful.

{
    "language": "da",
    "title": "Sign this this document, or else...",
    "message": "...you're in for a big surprise.",
    "documentIds": [
        7458, 6129
    ],
    "methods": [
        "bankid_se",
        "checkbox"
    ],
    "signers": [
        {
            "name": "Katja",
            "email": "[email protected]"
        },
        {
            "name": "Joelito",
            "email": "[email protected]",
            "limetype": "person",
            "id": 3001,
            "order": 2
        },
    ]
}

Cancel Signing¶

eSign provides an API to cancel existing signings that are in a cancelable state. It's available both as a Python module and as REST.

Python¶

from limepkg_esign.api import cancel_signing

# Cancel an existing signing
cancel_signing(app, 1234)

REST¶

Cancel an existing signing by making a POST request to limepkg-esign/api/signing/{signing_id}/cancel/ with appropriate authentication headers.

Endpoint: POST /limepkg-esign/api/signing/{signing_id}/cancel/

Parameters: - signing_id (path parameter): The ID of the signing to cancel

Cancelable Statuses: A signing can only be canceled if it's in one of the following statuses: - sent - Signing has been sent to signers - opened - At least one signer has opened the signing - partly_signed - Some signers have signed, but not all - error - Signing is in an error state

Responses:

Success (200 OK):

{
    "message": "The signing 'Title' (ID: {signing_id}) has been cancelled successfully. Potential signers have been notified."
}

Forbidden (403): User does not have required permissions or is not a member of the eSign user group.

Bad Request (400): The signing cannot be canceled due to its current status (e.g., already fully signed, already canceled, etc.).

Not Found (404): The signing with the specified ID does not exist.