Signature gathering with Portal API

Portal API can be integrated into your Document Management System or other internal information systems to collect signatures from 3rd parties using Dokobit portal UX.

Portal APIs offer multiple attributes that can be tailored to your needs or specific use-case scenarios.

Here are some of the available options for initiating document signing (POST /api/signing/create.json):

type – sets the signed document format. If the value is set to pdf , only a single PDF document will be accepted in the files  object. However, multiple files will be accepted, if the value is set to one of the container formats, such as asice.

postback_url – allows you to enable webhooks for your integration. Our system will send notifications to your defined URL to inform you about signing events if the attribute is set. Using webhooks will allow you to trigger actions or workflows in your system as soon as they happen in the Dokobit portal. More can be found here: Dokobit Webhooks.

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;
  • approver  – Will have access to consent to a document's content. The internal company regulations should define the validity of the approval within the organisation.

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.

require_account – enables you to securely share a document with a specific person and allows this person to access the document without registering to the Dokobit portal. Sharing the document for accountless signing together with a personal code ensures that only this person can access the document as the user is authenticated before viewing the document. It is worth mentioning that the e-mail notification language and company name used in the signing invitation is based on your access token configuration. More information about accountless signing can be found here: Sharing for accountless signing with authentication.

deadline – setting a date will enable the portal to send out reminders to participants who have yet not 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.

annotation_position – sets the position of signature annotations on a PDF document.

If you want the participant to receive an e-mail notification about being added to a signing, you should specify the participant's e-mail address in the request email attribute.

Example of the request and response for POST /api/signing/create.json method:
REQUEST
URL : "https://beta.dokobit.com/api/signing/create.json?access_token=YOUR_API_ACCESS_TOKEN"
METHOD : POST
BODY:
{
    "type": "pdf",
    "name": "Agreement",
    "signers": [
    {
        "name": "First",
        "surname": "Signer",
        "email": "test+first@dokobit.com",
        "code": "51501017710",
        "country_code": "ee",
        "role": "signer",
        "position": "Director",
        "sequence": "1"
    },
    {
        "name": "Second",
        "surname": "Signer",
        "email": "test+second@dokobit.com",
        "code": "51501017721",
        "country_code": "ee",
        "role": "signer",
        "position": "Director",
        "sequence": "2"
    }],
    "files": [
    {
        "name": "Agreement.pdf",
        "digest": "1d879e6248e4dc553b286fc5f81dc52bf841ead031287228548551a70cf06560",
        "content": "--- RBL ---"
    }],
    "postback_url": "http://your-public-host/postback-handler.php",
    "deadline": "2022-04-13T09:01:35Z",
    "comment": "Please sign at your earliest convenience",
    "require_qualified_signatures": "1",
    "require_account": "0"
}

RESPONSE
{
    "status": "ok",
    "token": "a81ee457d2ea6555c59aad0dc14aaa58d32fda97",
    "signers": [
    {
        "token": "5d09e050a0dd931a2a0b70406bd3351704e8241c",
        "first_name": "First",
        "last_name": "Signer",
        "code": "51501017710",
        "country": "ee",
        "email": "test+first@dokobit.com"
    },
    {
        "token": "1825216beb14397ad8aff1e2db273757ed62e608",
        "first_name": "Second",
        "last_name": "Signer",
        "code": "51501017721",
        "country": "ee",
        "email": "test+second@dokobit.com"
    }]
}

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

A webhook has been sent to your postback_url after the first participant has signed the document:
{
    "action": "signer_signed",
    "token": "a81ee457d2ea6555c59aad0dc14aaa58d32fda97",
    "signer_token": "5d09e050a0dd931a2a0b70406bd3351704e8241c",
    "file": "https://beta.dokobit.com/api/signing/a81ee457d2ea6555c59aad0dc14aaa58d32fda97/download",
    "name": "Agreement",
    "type": "pdf",
    "status": "pending",
    "date_created": "2022-04-06T12:01:37+03:00",
    "deadline": "2022-04-13T12:01:35+03:00",
    "categories": [],
    "files": [
    {
        "name": "Agreement.pdf",
        "url": "https://beta.dokobit.com/file/48a4bc1170432dbbb1409f3012744e5319443ec5d415e74dc7119f785560bf9b/download",
        "type": null,
        "mime_type": "application/pdf"
    }],
    "signers": [
    {
        "token": "5d09e050a0dd931a2a0b70406bd3351704e8241c",
        "type": "signer",
        "status": "signed",
        "signature":
        {
            "signing_time": "2022-04-06T12:17:28+03:00",
            "certificate":
            {
                "owner": "FIRST SIGNER",
                "issuer": "TEST of ESTEID-SK 2015, AS Sertifitseerimiskeskus, EE",
                "valid_from": "2020-11-16 08:58:22",
                "valid_to": "2025-11-15 23:59:59",
                "qualified": true,
                "value": "Base64 encoded certificate"
            },
            "level": "PAdES-LT",
            "timestamp":
            {
                "qualified": true
            },
            "timemark": [],
            "seal": false,
            "errors": [],
            "warnings": []
        },
        "meta_information":
        {
            "company": null,
            "position": "Director",
            "signing_purpose": null,
            "signing_location": null,
            "country": null,
            "city": null,
            "postal_code": null,
            "subdivision": null
        },
        "is_qualified_electronic_signature": true,
        "first_name": "First",
        "last_name": "Signer",
        "code": "51501017710",
        "country": "ee",
        "email": "test+first@dokobit.com"
    },
    {
        "token": "1825216beb14397ad8aff1e2db273757ed62e608",
        "type": "signer",
        "status": "pending",
        "signature": [],
        "meta_information":
        {
            "company": null,
            "position": "Director",
            "signing_purpose": null,
            "signing_location": null,
            "country": null,
            "city": null,
            "postal_code": null,
            "subdivision": null
        },
        "is_qualified_electronic_signature": false,
        "first_name": "Second",
        "last_name": "Signer",
        "code": "51501017721",
        "country": "ee",
        "email": "test+second@dokobit.com"
    },
    {
        "token": "9b1ae03e8101f2cda4c0b60f207075e789be4a60",
        "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 Company",
        "last_name": "",
        "code": null,
        "country": null,
        "email": null
    }],
    "is_qualified_signature_required": true,
    "signing_deadline":
    {
        "date": "2022-04-13 12:01:35.000000",
        "timezone_type": 3,
        "timezone": "Europe/Vilnius"
    }
}

As the signing sequence was set in the POST /api/signing/create.json request, the second participant receives an e-mail invitation only after the first participant has signed. Your company branding would be applied in the production environment.

In this scenario, our 2nd participant does not have a Dokobit account.

The "require_account": false was set when the signing was initiated. In this case, the participant is presented with an accountless signing interface when accessing the document. The personal code was also provided in the request. Therefore, the user is asked to confirm the identity before viewing the document's contents. More information about accountless signing can be found here: Sharing for accountless signing with authentication.

Once all participants have completed the required actions, the signing_completed webhook is sent to your system, informing you about the completed signing.
{
    "action": "signing_completed",
    "token": "a81ee457d2ea6555c59aad0dc14aaa58d32fda97",
    "file": "https://beta.dokobit.com/api/signing/a81ee457d2ea6555c59aad0dc14aaa58d32fda97/download",
    "name": "Agreement",
    "type": "pdf",
    "status": "completed",
    "date_created": "2022-04-06T12:01:37+03:00",
    "deadline": "2022-04-13T12:01:35+03:00",
    "categories": [],
    "files": [
    {
        "name": "Agreement.pdf",
        "url": "https://beta.dokobit.com/file/48a4bc1170432dbbb1409f3012744e5319443ec5d415e74dc7119f785560bf9b/download",
        "type": null,
        "mime_type": "application/pdf"
    }],
    "signers": [
    {
        "token": "5d09e050a0dd931a2a0b70406bd3351704e8241c",
        "type": "signer",
        "status": "signed",
        "signature":
        {
            "signing_time": "2022-04-06T12:17:28+03:00",
            "certificate":
            {
                "owner": "FIRST SIGNER",
                "issuer": "TEST of ESTEID-SK 2015, AS Sertifitseerimiskeskus, EE",
                "valid_from": "2020-11-16 08:58:22",
                "valid_to": "2025-11-15 23:59:59",
                "qualified": true,
                "value": "Base64 encoded certificate"
            },
            "level": "PAdES-LT",
            "timestamp":
            {
                "qualified": true
            },
            "timemark": [],
            "seal": false,
            "errors": [],
            "warnings": []
        },
        "meta_information":
        {
            "company": null,
            "position": "Director",
            "signing_purpose": null,
            "signing_location": null,
            "country": null,
            "city": null,
            "postal_code": null,
            "subdivision": null
        },
        "is_qualified_electronic_signature": true,
        "first_name": "First",
        "last_name": "Signer",
        "code": "51501017710",
        "country": "ee",
        "email": "test+first@dokobit.com"
    },
    {
        "token": "1825216beb14397ad8aff1e2db273757ed62e608",
        "type": "signer",
        "status": "signed",
        "signature":
        {
            "signing_time": "2022-04-06T12:54:42+03:00",
            "certificate":
            {
                "owner": "SECOND SIGNER",
                "issuer": "TEST of ESTEID-SK 2015, AS Sertifitseerimiskeskus, EE",
                "valid_from": "2020-11-16 09:11:01",
                "valid_to": "2025-11-15 23:59:59",
                "qualified": true,
                "value": "Base64 encoded certificate"
            },
            "level": "PAdES-LT",
            "timestamp":
            {
                "qualified": true
            },
            "timemark": [],
            "seal": false,
            "errors": [],
            "warnings": []
        },
        "meta_information":
        {
            "company": null,
            "position": "Director",
            "signing_purpose": null,
            "signing_location": null,
            "country": null,
            "city": null,
            "postal_code": null,
            "subdivision": null
        },
        "is_qualified_electronic_signature": true,
        "first_name": "Second",
        "last_name": "Signer",
        "code": "51501017721",
        "country": "ee",
        "email": "test+second@dokobit.com"
    },
    {
        "token": "9b1ae03e8101f2cda4c0b60f207075e789be4a60",
        "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 Company",
        "last_name": "",
        "code": null,
        "country": null,
        "email": null
    }],
    "is_qualified_signature_required": true,
    "signing_deadline":
    {
        "date": "2022-04-13 12:01:35.000000",
        "timezone_type": 3,
        "timezone": "Europe/Vilnius"
    },
    "signed_file": [
    {
        "url": "https://beta.dokobit.com/signing/a81ee457d2ea6555c59aad0dc14aaa58d32fda97/download"
    }]
}

A signed file can be downloaded using the URL form file attribute together with your API access token.

Signing management

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

Please also check our detailed Portal API documentation here.

Still need help? Contact us Contact us