The V1 API is the encouraged choice for sending one or more documents in a single request for signing or downloading and obtaining the result afterwards.
PKIsigning is using Swagger for API documentation. Please look at the API documentation in our Swagger interface.
The PKIsigning API consists of four operations:
StartSignFlow
RetrieveDocument
RemoveDocument
GetWorkgroupWithClearanceLevel
StartSignFlow
The API documentation is showing several fields in the request that are only present for backwards compatibility.
/document
/documentName
/filename
/recipients
/signers
These properties have been replaced by their successors in the /documents array and therefore allow for sending multiple files.
The StartSignFlow operation is the most important operation of the API. It can be used to create a new request and send one or more documents to the PKIsigning platform. At the same time, it can be used to bind actors (e.g. signers and receivers) to the document. These actors will receive an invite to perform an action at the document.
A feature not available on the platform, but already present in the API is to automatically fill form fields of a PDF document. If a document contains form fields, these can be filled by data specified in the request. This makes it easier to perform simple mail merge features.
After the document has been processed, invites are automatically sent to actors.
The following remarks have to be taken into account:
For each signer an ordinal is required. The order of signers is based on the deadline specified. In case where deadlines of signers are equal, the ordinal is used to create an order.
As the request is sent after processing, at least one signer or recipient has to be specified for a document.
When creating a new request, a workgroup together with a clearance level can be specified. When specifying these values, a request is immediately added to a workgroup and available for other members of the workgroup to see. To prevent all members of a workgroup to see a specific request, a clearance level can be specified. Only users with the same clearance level or a clearance level that is higher than specified will be able to see and open the request.
To obtain a list of possible workgroup id’s together with their respective clearance levels, please see GetWorkgroupWithClearanceLevel.
It is not possible to set a higher clearance level than specified in the list retrieved from GetWorkgroupWithClearanceLevel.
RetrieveDocument
The RetrieveDocument call can be used to obtain a zip-file containing all documents of a single request. When a callback url was specified during the StartSignFlow call, this url is called upon status updates, after which RetrieveDocument may be called.
The RetrieveDocument can be called on requests with any status. Please note that this could lead to obtaining documents which are not completely signed.
RemoveDocument
The RemoveDocument call can be used to permanently remove a request from the PKIsigning platform. As requests expire after 30 days, this call is not required to be implemented. Upon expiration, reminder emails are sent to the owner of the request. To prevent this from happening, the request can be removed after reaching either the Completed status or an error status.
The RemoveDocument call can only be called upon requests with statuses New, Active, Completed and Expired.
GetWorkgroupWithClearanceLevel
This method can be used to obtain a list of workgroups available to the authenticated user, together with the highest possible clearance level for that workgroup.
Workgroup IDs can be used in the StartSignflow call to create a new request.