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. For specialized operations, please see our V2 API interface. It is possible to use V2 API calls after calling StartSignFlow.

The PKIsigning API consists of four operations:

1. StartSignFlow

2. RetrieveDocument

3. RemoveDocument

4. GetWorkgroupWithClearanceLevel

StartSignFlow

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.

For each document, a document type and mime type have to be specified. Please see our list of Document types and Mime types for valid values.

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.

Callback

It is possible to subscribe to status events on the PKIsigning platform. To subscribe, specify a callbackUrl in the StartSignFlow call. For each change in status, this url will be called using HTTP POST with a body like the following example:

{
	"pkisId": "453…72e86",
	"dossierStatus": "Completed",
	"reason": "optional value indicating the reason of a status change",
    "authenticationKey": "92d5ba9f…9202377"
}

When the status is Completed, the RetrieveDocument call can be executed to obtain all signed documents.

The authentication key is only available for use in the V2 API.

To validate the origin of the callback, the callback is signed using three values in the HTTP header.

1. x-pkisigning-timestamp: the value of this header prevents against replay attacks and should be checked by the receiver. Normally there should not be more than a few seconds difference in time when the time of receiving system is synced through NTP.

2. x-pkisigning-publickey: This value contains a PKCS7 encoded certificate that was used to sign the callback request. Validate if the certificate is provided by a valid trusted service provider, is not revoked, is within its validity period and most important if the certificate contains a PKIsigning domain (we use the top level domains PKIsigning.io and PKIsigning.nl).

3. x-pkisigning-signature: this value contains the RSASHA256 signature of the contents combined with the timestamp. To check the signature follow the following procedure:

   1. obtain the raw bytes of the payload (UTF-8 encoding)

   2. obtain the bytes of the timestamp (UTF-8 encoding)

   3. concatenate both byte sequences into one byte sequence

   4. verify the signature against the certificate

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.

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.

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.