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.
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 or adoc.cedoc . For already formed and signed ADoc containers, use adoc .
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;receiver– Will have access to view and download 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 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.
annotation_position – sets the position of signature annotations on a PDF document.
allow_video_identification – allows signing using video-based identification (ElectronicID).
allowed_signing_methods[0] – allows the specification of available eID methods for signing participants.
signers[0][notifications_language] – allows setting signing invitation language.
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:
- POST /api/signing/{token}/share – allows adding additional participants to the document signing.
- POST /api/signing/{token}/signers/delete – allows removing the participant from the participant list only if a person has not signed the document yet.
- POST /api/signing/{token}/delete – allows removing the document signing from your Portal API account. However, the document signing is still accessible to other users you have shared it with. Deletion is permanent and cannot be undone.
- POST /api/signing/{token}/delete-all – allows removing the document signing from your Portal API 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.
- POST /api/signing/{token}/remind.json – allows sending a reminder to the participant if the person has not signed the document yet.
- POST /api/signing/{token}/update.json - allows updating existing signing parameters.
- GET /api/signing/{token}/download – allows downloading signed document.
- GET /api/signing/{token}/status.json – allows checking the document signing status. Returns all information about signing, files, signers and their certificates.