The PKIsigning platform is a separate product which is in fact in front of our signing engine. It
used the API as described on previous pages to sign documents, but will also provide you
with a more user-friendly userinterface and email workflow .
As a different product, there are different API calls. The API is authorized in the same way by
using the accesstoken as acquired by identity server.
| Informatie |
|---|
Next to this documentation, please refer to our swagger documentation as well on https://accplatformapi.pkisigning.io/swagger/index.html#/Share/Share_StartSignFlow |
Submitting a document for signing
To submit a document for signing to the PKIsigning platform a post request can be send to
the following URL: https://platformapi.pkisigning.io/api/share/startsignflow for our
production environment.
Please use https://accplatformapi.pkisigning.io/api/share/startsignflow for our staging environment.
The contents of this call are displayed below.
| Codeblok | ||
|---|---|---|
| ||
{
"callbackUrl": "https://www.callback.com",
"signatureNote": "A optional note to display to the signer",
"dossierName": "A descriptive name for the dossier",
"workgroupId": null,
"clearanceLevel": 1,
"documents": [
{
"contents":"JVBE…<<base64 encoded document>>…Ri0x =",
"filename": "dummy.pdf",
"name": "a descriptive name",
"mimeType":1,
"documentType":1,
"signers": [
{
"ordinal": 1,
"deadline": "2019-04-24T23:59:59.000Z",
"firstname": "Wim",
"lastname": "Zoet",
"mobile": "0612345678",
"email": "wim@pkisigning.nl",
"placeholder": "SIGNATURE1",
"signatureFieldName": "Signature1"
"extendedIdentityVerification": false,
"language": "nl"
},
{…}
],
"recipients": [
{
"deadline": "2019-04-24T23:59:59.000Z",
"firstname": "Wim",
"lastname": "Zoet",
"mobile": "0612345678",
"email": "wim@pkisigning.nl",
"extendedIdentityVerification": false,
"language": "nl"
},
{…}
],
"formFieldValues":[
{
"formFieldName":"FormField1",
"value":"SomeValue"
}
]
},
{…}
]
} |
...
workgroupId: optional Id of a workgroup. Please see Workgroups
documents: an array of documents that are automatically combined in a single dossier.
contents: the document to sign in base64 encoding.
filename: the filename of the document
name: a descriptive name for the document
mimetype: the mimetype of the document, based on the list of mimetypes at the bottom of this document
documenttype: the documenttype of the document, based on the list of documenttypes at the bottom of this document (for now only pdf, xml and xbrl documents are supported).
documents/signers: a collection of persons that should sign the document.
Ordinal: ordinal of the signature
Deadline: the document should be signed by this date
Firstname: first name of the signer
Prefix: prefix of the last name of the signer
Lastname: last name of the signer
Email: email address of the signer
Mobile: mobile phone number of the signer in international format (e.g. +316xxxxx, numbers starting with 00 are not supported)
Placeholder: text to be searched for in the document and marked as placeholder for
the signature (can be empty if SignatureFieldName is used)SignatureFieldName: the name of an existing signature field name if applicable (prefers over a signature field created by placeholder)
ExtendedIdentityVerification: whether or not the identity of the signer should be
verified more thoroughly (e.g. using IDIN). (Extra credits will be charged for using this
service)Language: the language of the email request that will be send
| Informatie |
|---|
Although ordinal is required, order is set firstly based on the deadline. If the deadline is the same for multiple signers, the ordinal is used. |
documents/recipients: a collection of persons that are required to download the document
Deadline: the document should be downloaded by this date
Firstname: first name of the signer
Prefix: prefix of the last name of the signer
Lastname: last name of the signer
Email: email address of the signer
Mobile: mobile phone number of the signer in format 06xxxxx or +316xxxxx
ExtendedIdentityVerification: whether or not the identity of the signer should be
verified more thoroughly (e.g. using IDIN). (Extra credits will be charged for using this
service)Language: the language of the email request that will be send
documents/formFieldValues: a collection of values that should be filled-in into existing formfields in the document
FormFieldName: the name of the field
Value: the value to be put into the field (only text-fields supported for now)
The call will result in the following response
| Codeblok | ||
|---|---|---|
| ||
{
"pkisId": "453…72e86"
} |
The pkisId is the documentId within our platform. It will be put into the callback body when
the POST method is used.
| Urgent |
|---|
As PKIsigning charges credits for requests when fulfilled, however credits are being reserved at the moment of submitting the request to prevent running out of credits while actually fulfilling it. If the amount of credits is insufficient to fulfill the request, a HTTP status 402 (Payment required) is returned. During development phase, please use either short deadlines or delete documents from the platform dashboard and clean up the recyblebin to prevent running out of credits. If a document is not signed nor downloaded by a recipient, any credits that were reserved for that request will become available again for new requests. |
Callback
Upon changes in the status of a document, callbacks will occur. These callback will have the following payload:
| Codeblok | ||
|---|---|---|
| ||
{
"pkisId": "453…72e86",
"dossierStatus": "Completed",
"declineReason": "optional value indicating the reason of declining a document"
} |
The pkisId can be compared to the pkisId as obtained from the call to the startSignFlow endpoint. The dossierStatus property indicates the status of the document. Available statuses are:
Active: the dossier is available on the platform, but has no signers attached
Completed: the dossier has been signed
Error: an error has occurred while converting, sending invitations, or publishing to Digipoort/AFAS
Expired: the document has been moved to the recyclebin
Filing: the dossier is being published to Chamber of Commerce
InvitationExpired: the signing invitation of this dossier has been expired
New: the dossier is new on the platform and has not been viewed yet
PendingApproval: the dossier is awaiting adoption by the client
PendingDigipoort: the dossier is being processed by Digipoort
PendingDownload: the dossier is waiting to be downloaded by a client
PendingFiling: the dossier is awaiting publication
PendingSbrNexus: the dossier is being processed by SBR Nexus
PendingSignature: invitations for the document have been set and the document is awaiting signing
Processing: the dossier is being converted
Rejected: the dossier has been rejected
Withdrawn: the dossier has been revoked for signing
Retrieving documents
Please use the following URL to retrieve the document from our platform:
https://platformapi.pkisigning.io/api/share/retrieveDocument/{{pkisId}} for production and
https://accplatformapi.pkisigning.io/api/share/retrieveDocument/{{pkisId}} for staging.
The document will be returned as a file, not as a json result.
| Waarschuwing |
|---|
Please do not use scheduled polling on this url to check the status of your document. Connections to this url are rate-limited based on IP-address. Please specify a callback url in your request and wait for our callback with status Completed on that url before retrieving the document. |
Workgroups
At https://platformapi.pkisigning.io/api/share/getworkgroupswithclearancelevel, a list can be downloaded of all workgroups that the authorized user has access to. This list will have the following structure:
| Codeblok | ||
|---|---|---|
| ||
[
{
"guid": "string",
"name": "string",
"clearancelevel": 1
}
] |
The guid of the workgroup can be used in the StartSignFlow call to add a document to the specific workgroup. The mentioned clearance level is the maximum clearance level to be used. By default all members of a workgroup have clearance level 1, therefore if a document should be visible to all members of a workgroup, please specify clearance level 1. If a higher clearance level is specified, only members with a clearance level of the same level or higher can view the document.
DOCUMENT TYPES
1. PDF
2. XBRL publication document (Dutch taxonomy)
3. XBRL auditors report
4. XML detached signature (output only)
5. XBRL preparer extension document
6. PDF audit trail document (output only)
7. XBRL composition statement
8. XBRL financial report (Dutch taxonomy)
9. DNB-staat
10. Regular XML-document
11. Non-specified file-type (handled as binary)
14. Generic text file
15. VAT declaration
16. VAT EU Recapulative statement
17. Income tax declaration
18. Corporate tax declaration
19. XBRL financial report - financial taxonomy,
22. XBRL auditors report - summarized financial overviews,
23. XBRL assessment statement,
256. SHA256 hash
257. SHA256 hash-signature (output only)
...
MIMETYPES
...
PDF-document
...
XML-document
...
ZIP-file
...
Hash-value (to be used with documenttype 256)
...
Signature-value (output only, to be used with documenttype 257)
...
JPeG image
...
Excel file (xlsx)
...
PNG image
...
GIF image
...
Other filetype
...
automatically inviting actors.