Document signing and signature gathering with Universal API – Support

Universal API is a versatile tool that enables signing documents internally, within your system, and collecting signatures from 3rd parties outside your system, using a wide variety of eID tools (eIDs supported in the Dokobit portal by countries).

Signing takes place in the accountless Dokobit signing interface. With your organization’s branding setup, the transition from your system to the signing page is made seamless and straightforward. Document signing invitations to 3rd parties also adapt to the styling you set.

A wide selection of optional parameters and supplementary API methods allow you to build a reliable document signing solution tailored to your needs.

API parameters used in initiating internal and external document signing flows

type – sets the signed document format. Multiple files can be uploaded. For already formed and signed ADoc containers, use adoc .
files[0][content] - Base64 encoded file content.
files[0][digest] - Hex encoded SHA256 checksum of raw file content.
postback_url - Postback URL where webhooks will be sent.
signers[0][external_id] - Unique signer identifier from your system. You can generate random identifiers if you do not have one.
signers[0][role] – enables you to manage the actions participants' can perform with a specific signing:
- signer – will require to sign the document;
- viewer – will only have access to view the document.
require_qualified_signatures - allows signing only by using eID tools with qualified electronic signatures.
allow_video_identification - allow signing using video-based identification. More details can be found here: How to sign documents using video-based identification?
allowed_signing_methods[0] – allows the specification of available eID methods for signing participants.
annotation_position – sets the position of signature annotations on a PDF document.
flatten_pdf - the file will be flattened so that the form fields become part of the document content and cannot be edited after signing. This parameter is only applicable for PDF type signing.
signers[0][custom_reason] - a custom signature reason that will be included in PDF's signature annotation. Only applicable for PDF type signing.

Signature annotation can be customised further with the below parameters:

signers[0][annotation][page] - sets page index of signature annotations on a PDF document. Only applicable for PDF type signing;
signers[0][annotation][top] - sets position from the top of the document for signature annotations on a PDF document. Only applicable for PDF type signing;
signers[0][annotation][left] - sets position from the left of the document for signature annotations on a PDF document. Only applicable for PDF type signing;
signers[0][annotation][language] - sets the language of the annotation. The default language is used based on access token configuration.

Internal signing

POST /api/signing-internal/create.json generates a unique internal signing URI.

signers[0][language] – allows setting UI language.

redirect_uri is a required parameter. It will be used for redirecting the participant after the action (according to set signers[0][role] ) is completed.

Example of the request:

REQUEST
URL : "https://beta.dokobit.com/api/signing-internal/create.json?access_token=YOUR_API_ACCESS_TOKEN"
METHOD : POST
BODY:
{
    "type": "pdf",
    "name": "Agreement",
    "files": [
    {
        "name": "test.pdf",
        "content": "--- RBL ---",
        "digest": "1d879e6248e4dc553b286fc5f81dc52bf841ead031287228548551a70cf06560"
    }],
    "redirect_uri": "http://example.com?postback",
    "signers": [
    {
        "external_id": "user1",
        "role": "signer"
    }]
}

Note: Your access token can be delivered as a header attribute (X-Access-Token) instead of a GET URL parameter.

Example of the response:

RESPONSE
{
    "status": "ok",
    "token": "7dde4cb5d993b16fcee70e63a65c22e90c4bec56",
    "signers": [
    {
        "external_id": "user1",
        "token": "f20f38b384d2cf8ddea2cc8bf0289f47ddad78b4",
        "redirect_uri": "https://beta.dokobit.com/en/public/signing/f20f38b384d2cf8ddea2cc8bf0289f47ddad78b4/5e0a0842df7fffd413620203c995b9420ef8b4dfeb20be2b3a62d15902d7bbc9"
    }]
}

Generated redirect_uri from API response should be used to redirect the user from your system to the accountless Dokobit signing interface. After taking the necessary action, the participant will be automatically redirected to the redirect_uri provided in your API request.

At this point GET /api/signing-internal/{token}/status.json method should be used to check the signing status if webhooks are not being used.

Example of the response:

RESPONSE
{
    "name": "Agreement",
    "type": "pdf",
    "status": "completed",
    "date_created": "2022-12-13T14:09:54+02:00",
    "files": [
    {
        "name": "test.pdf",
        "url": "https://beta.dokobit.com/file/37379504cd4020f0e52641b5f4111522e781bcf1ad4565c6c81eb38cfe52ee6c/download",
        "type": null,
        "mime_type": "application/pdf"
    }],
    "signers": [
    {
        "token": "f20f38b384d2cf8ddea2cc8bf0289f47ddad78b4",
        "type": "signer",
        "status": "signed",
        "signature":
        {
            "signing_time": "2022-12-13T14:35:53+02:00",
            "certificate":
            {
                "owner": "OK TESTNUMBER",
                "issuer": "TEST of EID-SK 2016, AS Sertifitseerimiskeskus, EE",
                "valid_from": "2022-11-28 15:40:22",
                "valid_to": "2030-12-18 01:59:59",
                "qualified": true,
                "value": "Base64 encoded certificate"
            },
            "level": "PAdES-LT",
            "timestamp":
            {
                "qualified": true
            },
            "timemark": [],
            "seal": false,
            "errors": [],
            "warnings": []
        },
        "meta_information":
        {
            "company": null,
            "position": null,
            "signing_purpose": null,
            "signing_location": null,
            "country": null,
            "city": null,
            "postal_code": null,
            "subdivision": null
        },
        "is_qualified_electronic_signature": true,
        "first_name": "Ok",
        "last_name": "Testnumber",
        "code": "30303039914",
        "country": "lt",
        "email": null,
        "is_in_trash_bin": false
    },
    {
        "token": "d968a9e083515c6176c7a72293337b27b719202b",
        "type": "viewer",
        "status": "pending",
        "signature": [],
        "meta_information":
        {
            "company": null,
            "position": null,
            "signing_purpose": null,
            "signing_location": null,
            "country": null,
            "city": null,
            "postal_code": null,
            "subdivision": null
        },
        "is_qualified_electronic_signature": false,
        "first_name": "Sandbox",
        "last_name": "",
        "code": null,
        "country": null,
        "email": null,
        "is_in_trash_bin": false
    }],
    "is_qualified_signature_required": false,
    "signed_file": [
    {
        "url": "https://beta.dokobit.com/signing/7dde4cb5d993b16fcee70e63a65c22e90c4bec56/download"
    }]
}

Note: You will notice an additional participant "token": "d968a9e083515c6176c7a72293337b27b719202b" in the GET /api/signing-internal/{token}/status.json response. It represents your Universal API access token account as an owner of the document.

Once the signing is completed, you can use GET /api/signing-internal/{token}/download to download the signed document.

External signing

POST /api/signing-external/create.json send a signing invitation to the provided signers[0][email] .

signers[0][notifications_language] – allows setting signing invitation language.

Example of the request:

REQUEST
URL : "https://beta.dokobit.com/api/signing-external/create.json?access_token=YOUR_API_ACCESS_TOKEN"
METHOD : POST
BODY:
{
    "type": "pdf",
    "name": "Agreement",
    "files": [
    {
        "name": "test.pdf",
        "content": "--- RBL ---",
        "digest": "1d879e6248e4dc553b286fc5f81dc52bf841ead031287228548551a70cf06560"
    }],
    "signers": [
    {
        "external_id": "external1",
        "email": "test+external@dokobit.com",
        "role": "signer",
        "notifications_language": "en"
    }],
    "postback_url": "http://your-public-host/postback-handler.php",
    "deadline": "2023-01-05T12:00:00+02:00",
    "hard_deadline": "true",
    "allow_document_saving": "false",
    "comment": "Please sign at your earliest convenience"
}

Note: Your access token can be delivered as a header attribute (X-Access-Token) instead of a GET URL parameter.

Example of the response:

RESPONSE
{
    "status": "ok",
    "token": "193841f25ab3331ddb7608826c69f11bc66309c4",
    "signers": [
    {
        "external_id": "external1",
        "token": "c53fddc4577406624fe806fb46654f7ccfb35204",
        "first_name": null,
        "last_name": null,
        "code": null,
        "country": "",
        "email": "test+external@dokobit.com"
    }]
}

After a successful API request, the participant will receive a signing invitation to the provided e-mail address containing the URL for signing. Users will open an accountless Dokobit signing interface where the document can be previewed and signed.

After the participant signs the document, we will send a webhook to your provided postback_url .

Example of the webhook:

{
    "action": "signing_completed",
    "token": "193841f25ab3331ddb7608826c69f11bc66309c4",
    "file": "https://beta.dokobit.com/api/signing/193841f25ab3331ddb7608826c69f11bc66309c4/download",
    "name": "Agreement",
    "type": "pdf",
    "status": "completed",
    "date_created": "2023-01-03T15:33:56+02:00",
    "deadline": "2023-01-05T12:00:00+02:00",
    "categories": [],
    "files": [
    {
        "name": "test.pdf",
        "url": "https://beta.dokobit.com/file/cec0cedc3b61030f5304fe5f60b698a2828ba65e965bfd60f18124514fb8b2d9/download",
        "type": null,
        "mime_type": "application/pdf"
    }],
    "signers": [
    {
        "token": "c53fddc4577406624fe806fb46654f7ccfb35204",
        "type": "signer",
        "status": "signed",
        "signature":
        {
            "signing_time": "2023-01-03T15:35:52+02:00",
            "certificate":
            {
                "owner": "OK TESTNUMBER",
                "issuer": "TEST of EID-SK 2016, AS Sertifitseerimiskeskus, EE",
                "valid_from": "2022-11-28 15:40:22",
                "valid_to": "2030-12-18 01:59:59",
                "qualified": true,
                "value": "Base64 encoded certificate"
            },
            "level": "PAdES-LT",
            "timestamp":
            {
                "qualified": true
            },
            "timemark": [],
            "seal": false,
            "errors": [],
            "warnings": []
        },
        "meta_information":
        {
            "company": null,
            "position": null,
            "signing_purpose": null,
            "signing_location": null,
            "country": null,
            "city": null,
            "postal_code": null,
            "subdivision": null
        },
        "is_qualified_electronic_signature": true,
        "first_name": "Ok",
        "last_name": "Testnumber",
        "code": "30303039914",
        "country": "lt",
        "email": "test+external@dokobit.com",
        "is_in_trash_bin": false
    },
    {
        "token": "7f9b8bab048944c302e7488544d89037bef6b3a0",
        "type": "viewer",
        "status": "pending",
        "signature": [],
        "meta_information":
        {
            "company": null,
            "position": null,
            "signing_purpose": null,
            "signing_location": null,
            "country": null,
            "city": null,
            "postal_code": null,
            "subdivision": null
        },
        "is_qualified_electronic_signature": false,
        "first_name": "CompanyName",
        "last_name": "",
        "code": null,
        "country": null,
        "email": null,
        "is_in_trash_bin": false
    }],
    "is_qualified_signature_required": false,
    "signing_deadline":
    {
        "date": "2023-01-05 12:00:00.000000",
        "timezone_type": 3,
        "timezone": "Europe/Vilnius"
    },
    "signed_file": [
    {
        "url": "https://beta.dokobit.com/signing/193841f25ab3331ddb7608826c69f11bc66309c4/download"
    }]
}

Note: You will notice an additional participant "token": "7f9b8bab048944c302e7488544d89037bef6b3a0" in the webhook. It represents your Universal API access token account as an owner of the document.

For more information about our webhooks, please check Dokobit Webhooks.

Other useful API external signing attributes

deadline - setting a date will enable reminders to participants who have not yet signed the document 24 hours before the set date. However, participants will still be able to sign after the deadline. Additional reminders will not be sent if the deadline is the same day as the signing creation date.
hard_deadline - will forbid signing after a set deadline . Participants who have not signed will get a reminder 24 hours before the deadline that a document is waiting for them. They will not be able to sign the document after the due date.
allow_document_saving - allows users to save documents to their Dokobit Portal account.
comment - Message for signers. It will be placed in the signing invitation.
signers[0][phone] - Signer's phone number for sending signing invitation SMS. Required if the signers[0][email] is not set. SMS will be sent only when the e-mail is not provided.
signers[0][code] - if the personal code was provided in the request, the user will be asked to confirm their identity before viewing the document's contents and signing.
signers[0][country_code] - signer's country code. Required if signers[0][code] is provided.
signers[0][notifications_language] - sets the language of e-mail notifications.
signers[0][sequence] - helps you create a signature gathering order by establishing who should sign first and who should be notified only afterwards. Combining this functionality with the role would allow you to set up a document approving and signing actions workflow.

Additional Universal API methods

After you have successfully initiated a document signing, you can manage it using the API methods below:

POST /api/e-delivery/create.json - allows sharing documents securely. Participants will be authenticated before the document is made available.
POST /api/signing-internal/{token}/signers/add.json - allows adding additional participants to the document signing.
POST /api/signing-internal/{token}/signers/delete.json - allows removing the participant from the participant list only if a person has not signed the document yet.
POST /api/signing-internal/{token}/delete.json - allows removing the document signing from your account and from other users you have shared it with if a person has not signed the document yet. Deletion is permanent and cannot be undone.
GET /api/signing-internal/{token}/status.json - allows checking the document signing status. Returns all information about signing, files, signers and their certificates.
POST /api/signing-internal/{token}/update.json - allows updating existing signing parameters.
GET /api/signing-internal/{token}/download - allows downloading signed documents.
POST /api/signing-external/{token}/remind.json - allows sending a reminder to the participant if the person has not signed the document yet.
POST /api/signing-external/{token}/signers/add.json - allows adding additional participants to the document signing.
POST /api/signing-external/{token}/signers/delete.json - allows removing the participant from the participant list only if a person has not signed the document yet.
POST /api/signing-external/{token}/delete.json - allows removing the document signing from your account and from other users you have shared it with if a person has not signed the document yet. Deletion is permanent and cannot be undone.
GET /api/signing-external/{token}/status.json - allows checking the document signing status. Returns all information about signing, files, signers and their certificates.
POST /api/signing-external/{token}/update.json - allows updating existing signing parameters.
GET /api/signing-external/{token}/download - allows downloading signed documents.

Please also check our detailed Universal API documentation here.

Related articles