PKIsigning (Preview)

Automate your document signing needs with the PKIsigning platform connector. Send documents to the PKIsigning platform; send invites and retrieve the signed documents.

This connector is available in the following products and regions:

Service	Class	Regions
Logic Apps	Standard	All Logic Apps regions except the following:      -   Azure Government regions      -   Azure China regions      -   US Department of Defense (DoD)
Power Automate	Premium	All Power Automate regions except the following:      -   US Government (GCC)      -   US Government (GCC High)      -   China Cloud operated by 21Vianet      -   US Department of Defense (DoD)
Power Apps	Premium	All Power Apps regions except the following:      -   US Government (GCC)      -   US Government (GCC High)      -   China Cloud operated by 21Vianet      -   US Department of Defense (DoD)

Contact
Name	PKIsigning support
URL	https://pkisigning.nl/support
Email	support@pkisigning.nl

Connector Metadata
Publisher	SBRS B.V.
Website	https://pkisigning.nl
Privacy policy	https://pkisigning.nl/privacy
Categories	Collaboration;Productivity

PKIsigning enables organisations to automate, simplify and secure the process of approving, signing, and sending documents to customers and third parties. The platform supports all eIDAS personal signing certificates from Dutch Qualified Trusted Service Providers and is ISO27001 certified. This makes PKIsigning an ideal partner for legal, finance and healthcare organisations and governments. Connect with PKisigning to automate, simplify, and secure your document signing process.

Prerequisites

To use the PKIsigning connector, an account to the PKIsigning platform is required within a "professional" subscription. Please contact PKIsigning to register for a paid subscription.

How to get credentials

After registering for a subscription, users will receive an email with an invitation to set-up their account. After registering, that account can directly be used with this connector.

Get started with your connector

The default flow to start signing documents is as follows:

1. Create dossier
2. Add document(s)
3. Add actor(s)
4. Start workflow
5. Use a trigger to get notified of status changes
6. Download dossier

Dossiers

PKIsigning expects you to always create a dossier first. A dossier acts as a container for documents and actors. A dossier can be created with the Dossiers_Create action. After a dossier is created, please use the returned PkisId as a reference for future actions.

Documents

After a dossier has been created you can add documents with the Documents_Add action using the correct dossierId. The action does not need any other parameters as they are distracted from the document files themselves. There is no limit for the number of documents in a dossier. All documents will be viewable and downloadable for all added actors.

Important: The document needs one or more unique textual placeholders, depending on the number of signatures, to indicate where a signature must be placed and by what actor. This can be any text in any place in the document. When adding actors, you can define the placeholder with the placeholder parameter. Eg: signature1, signature2, etc...

Actors

The third step consist of adding actors to the documents. This is done with the Actor_Create Action using the correct dossierId and documentId.

Start workflow

To start a workflow and effectively send out invites to all actors to sign or download documents in the provided order, use the Dossiers_StartWorkflow action with the correct dossierId.

Use a trigger to get notified of status changes

To obtain the document after it has been signed, subscribe notifications using a trigger. To receive status notification, specify 'status' in the Events field.

Download dossier

When the trigger is notified of a status update, check if the status of the document is 'Completed'. As of that moment, it is possible to download all documents in the dossier in a single zipfile. If it is specified in the settings within the PKIsigning platform that an audittrail should be generated, this will be included as well.

Known issues and limitations

No issues are known at the moment of publication.

Common errors and remedies

No status updates through trigger

If the trigger does not respond to status updates, please check if the value 'status' was supplied in the Events field.

HTTP error 402 Payment Required

The PKIsigning platform required credits to perform actions. When actors are added, credits are reserved to ensure that the action can take place and invitees are not confronted with issues regarding an insufficient number of credits available. If a lot of invites are sent to actors, it can occur that the credit bundle has no more credits left to be reserved. At that moment, a HTTP 402 error will be returned.

To resolve the issue, either PKIsigning support to top-up the credit balance, or clean up any unsent dossiers with actors in the recyclebin on the platform. Unused credits will then become available again.

FAQ

Please see our knowledgebase or contact us at support@pkisigning.nl

Throttling Limits

Name	Calls	Renewal Period
API calls per connection	100	60 seconds

Actions

Create actor	Creates a new actor and adds it to a document.
Create document	Creates a new document and add it to a specific request.
Create request	Create a new request.
Delete a request	Permanently deletes a specific request.
Delete actor	Permanently deletes a specific actor.
Delete document	Permanently deletes a specific document.
Download request	Downloads a requests and its contents as a .zip file.
Get actor data	Returns all data for a specific actor.
Get actor data by document	Returns all data of all actors for a specific document.
Get actor data by request	Returns all data of all actors for a specific request.
Get document data	Returns all (meta)data for a specific document.
Get request data	Returns all (meta)data for a specific request.
Get workgroups for organisation	Returns a list of all workgroups for a specific organisation.
Get workgroups for user	Returns a list of all workgroups for a specific user of a specific organisation.
Resend invite	Resends the invite for the current actor in line for a specific request.
Send request	Starts the workflow and sends an invite to the first actor in line for a specific request.
Update actor	Changes data for a specific actor.
Update document	Changes data for a specific document.
Update request	Changes data for a specific request.
Withdraw invite	Withdraws the invite for the current actor in line for a specific request.

Create actor

Operation ID:

Actors_Create

Creates a new actor and adds it to a document.

Parameters

Name	Key	Required	Type	Description
Request ID	requestId	True	guid	Unique ID of a request.
Document ID	documentId	True	guid	Unique ID of a document.
Action	action	True	string	Action that the actor must perform.
First name	firstname	True	string	First name of the actor.
Prefix	prefix		string	Prefix of the actor.
Last name	lastname	True	string	Last name of the actor.
Email address	email	True	string	Email address of the actor.
Mobile phone number	mobile	True	string	Mobile phone number of the actor.
Deadline	deadline	True	date-time	The date and time by when the action must have been performed by the actor.
Language	language	True	string	Language for the invite.
Use strong verification	validateRealIdentity	True	boolean	Use a stronger method of identification for this actor.
dossierPersonId	dossierPersonId		integer
message	message		string
Signing field	fieldName		string	The name of an existing signing field in the document for this actor to sign.
Placeholder	placeholder		string	The text of a specific placeholder in the document where the actor must place a signature.

Returns

Body

ExtendedSignerModel

Create document

Operation ID:

Documents_Create

Creates a new document and add it to a specific request.

Parameters

Name	Key	Required	Type	Description
Request ID	requestId	True	guid	Unique ID of a request where this document will belong to.
File	file	True	file	The file to be processed (only specific filetypes).

Returns

General metadata of the document

Body

DocumentMetaDataModel

Create request

Operation ID:

Requests_Create

Create a new request.

Parameters

Name	Key	Required	Type	Description
Request name	name	True	string	Name for a specific request.
Workgroup ID	workgroupId		guid	Unique ID of a workgroup.
Security clearance level	clearancelevel	True	integer	Level of security clearance for a specific request.
Request owner	owner		email	User who is the owner of a specific request.

Returns

Body

RequestModel

Delete a request

Operation ID:

Requests_Delete

Permanently deletes a specific request.

Parameters

Name	Key	Required	Type	Description
Request ID	requestId	True	guid	Unique ID of a request.

Delete actor

Operation ID:

Actors_Delete

Permanently deletes a specific actor.

Parameters

Name	Key	Required	Type	Description
Request ID	requestId	True	guid	Unique ID of a request.
Document ID	documentId	True	guid	Unique ID of a document.
Actor ID	actorId	True	guid	Unique ID of an actor.

Delete document

Operation ID:

Documents_Delete

Permanently deletes a specific document.

Parameters

Name	Key	Required	Type	Description
Request ID	requestId	True	guid	Unique ID of a request.
Document ID	documentId	True	guid	Unique ID of a document.

Download request

Operation ID:

Requests_Download

Downloads a requests and its contents as a .zip file.

Parameters

Name	Key	Required	Type	Description
Request ID	requestId	True	guid	Unique ID of a request.

Returns

response

file

Get actor data

Operation ID:

Actors_Get

Returns all data for a specific actor.

Parameters

Name	Key	Required	Type	Description
Request ID	requestId	True	guid	Unique ID of a request.
Document ID	documentId	True	guid	Unique ID of a document.
Actor ID	actorId	True	guid	Unique ID of an actor.

Returns

Body

ExtendedSignerModel

Get actor data by document

Operation ID:

Actors_List

Returns all data of all actors for a specific document.

Parameters

Name	Key	Required	Type	Description
Request ID	requestId	True	guid	Unique ID of a request.
Document ID	documentId	True	guid	Unique ID of a document.
Action completed	hasActed		boolean	Only returns actors that have or haven't completed their action, leave blank to return all actors.

Returns

response

array of ExtendedSignerModel

Get actor data by request

Operation ID:

Actors_RequestActors

Returns all data of all actors for a specific request.

Parameters

Name	Key	Required	Type	Description
Request ID	requestId	True	guid	Unique ID of a request.
Has actor acted on the request	hasActed		boolean	Read only value to check if an actor has acted on the document already.

Returns

response

array of ExtendedSignerModel

Get document data

Operation ID:

Documents_Get

Returns all (meta)data for a specific document.

Parameters

Name	Key	Required	Type	Description
Request ID	requestId	True	guid	Unique ID of a request.
Document ID	documentId	True	guid	Unique ID of a document.

Returns

General metadata of the document

Body

DocumentMetaDataModel

Get request data

Operation ID:

Requests_Get

Returns all (meta)data for a specific request.

Parameters

Name	Key	Required	Type	Description
Request ID	requestId	True	guid	Unique ID of a request.
Authentication key	callbackAuthenticationKey		string	Authentication key as supplied by trigger.

Returns

Body

RequestModel

Get workgroups for organisation

Operation ID:

Organisations_GetWorkgroups

Returns a list of all workgroups for a specific organisation.

Parameters

Name	Key	Required	Type	Description
Organisation ID	organisationId	True	guid	Unique ID of an organisation.

Returns

response

array of OrganisationWorkgroup

Get workgroups for user

Operation ID:

Organisations_GetWorkgroupsByUser

Returns a list of all workgroups for a specific user of a specific organisation.

Parameters

Name	Key	Required	Type	Description
Organisation ID	organisationId	True	guid	Unique ID of an organisation.
Username	username	True	email	Emailaddress of the user

Returns

response

array of OrganisationWorkgroup

Resend invite

Operation ID:

Actors_ResendCurrentInvite

Resends the invite for the current actor in line for a specific request.

Parameters

Name	Key	Required	Type	Description
Request ID	requestId	True	guid	Unique ID of a request.

Send request

Operation ID:

Requests_Send

Starts the workflow and sends an invite to the first actor in line for a specific request.

Parameters

Name	Key	Required	Type	Description
Request ID	requestId	True	guid	Unique ID of a request.

Update actor

Operation ID:

Actors_Update

Changes data for a specific actor.

Parameters

Name	Key	Required	Type	Description
Request ID	requestId	True	guid	Unique ID of a request.
Document ID	documentId	True	guid	Unique ID of a document.
Actor ID	actorId	True	guid	Unique ID of an actor.
Action	action	True	string	Action that the actor must perform.
First name	firstname	True	string	First name of the actor.
Prefix	prefix		string	Prefix of the actor.
Last name	lastname	True	string	Last name of the actor.
Email address	email	True	string	Email address of the actor.
Mobile phone number	mobile	True	string	Mobile phone number of the actor.
Deadline	deadline	True	date-time	The date and time by when the action must have been performed by the actor.
Language	language	True	string	Language for the invite.
Use strong verification	validateRealIdentity	True	boolean	Use a stronger method of identification for this actor.
dossierPersonId	dossierPersonId		integer
message	message		string

Returns

Body

ExtendedSignerModel

Update document

Operation ID:

Documents_Update

Changes data for a specific document.

Parameters

Name	Key	Required	Type	Description
Request ID	requestId	True	guid	Unique ID of a request.
Document ID	documentId	True	guid	Unique ID of a document.
Document name	name		string	Name for a specific document
Document file name	filename		string	File name for a specific document
Document type	documentType	True	string	The type for a specific document. (E.g. Regular PDF, fiscal statement, auditors report, etc..).

Returns

General metadata of the document

Body

DocumentMetaDataModel

Update request

Operation ID:

Requests_Update

Changes data for a specific request.

Parameters

Name	Key	Required	Type	Description
Request ID	requestId	True	guid	Unique ID of a request.
Request name	name	True	string	Name for a specific request.
Workgroup ID	workgroupId		guid	Unique ID of a workgroup.
Security clearance level	clearancelevel	True	integer	Level of security clearance for a specific request.
Request owner	owner		email	User who is the owner of a specific request.

Returns

Body

RequestModel

Withdraw invite

Operation ID:

Actors_WithdrawCurrentInvite

Withdraws the invite for the current actor in line for a specific request.

Parameters

Name	Key	Required	Type	Description
Request ID	requestId	True	guid	Unique ID of a request.

Triggers

When an event occurs on a request

Register an url for callback upon a statuschange. The PKIsigning platform will report any statusupdates of dossiers within this organisation to this url.

When an event occurs on a request

Operation ID:

Webhooks_CreateWebhook

Register an url for callback upon a statuschange. The PKIsigning platform will report any statusupdates of dossiers within this organisation to this url.

Parameters

Name	Key	Required	Type	Description
Event types	Events	True	array of string	A list of event types that occur on a request of which this trigger will be notified
Organisation ID	organisationId	True	guid	Unique ID of an organisation.

Returns

Name	Path	Type	Description
Request ID	PkisId	guid	Unique ID of a request.
Request status	DossierStatus	string	Status of the dossier.
Reason	Reason	string	Reason of the change.
Authentication key	AuthenticationKey	string	Header to obtain metadata on the request.

Definitions

ExtendedSignerModel

Name	Path	Type	Description
Signing field	fieldName	string	The name of an existing signing field in the document for this actor to sign.
Placeholder	placeholder	string	The text of a specific placeholder in the document where the actor must place a signature.
Action	action	string	Action that the actor must perform.
First name	firstname	string	First name of the actor.
Prefix	prefix	string	Prefix of the actor.
Last name	lastname	string	Last name of the actor.
Email address	email	string	Email address of the actor.
Mobile phone number	mobile	string	Mobile phone number of the actor.
Deadline	deadline	date-time	The date and time by when the action must have been performed by the actor.
Language	language	string	Language for the invite.
Use strong verification	validateRealIdentity	boolean	Use a stronger method of identification for this actor.
dossierPersonId	dossierPersonId	integer
message	message	string
Actor ID	id	guid	Unique ID of a specific actor.
Date of completion	signingDate	date-time	The date and time when the actor has performed its action.
Action completed	hasSigned	boolean
Full name	fullName	string	Combined first name, prefix and last name of the actor.
Status information	emailActivity	array of EmailActivity	Status information about the process of performing the action by the actor.
documentId	documentId	guid

EmailActivity

Metadata of email message send to an actor

Name	Path	Type	Description
Email activity	event	string	Email activity for a specific request and actor.
SMTP information	reason	string	SMTP information for an email sent to a specific actor as part of a request.
Email date	timestamp	date-time	Date for an email sent to a specific actor as part of a request.
Email type	pkisMessageType	string	Type for an email sent to a specific actor as part of a request (E.g. Invite, Reminder, etc).
Email request ID	pkisInviteId	string	Unique ID for an email sent to a specific actor as part of a request.
Email address	email	string	Email address for an email sent to a specific actor as part of a request.

SignerModel

Special type of actor

Name	Path	Type	Description
Action	action	string	Action that the actor must perform.
First name	firstname	string	First name of the actor.
Prefix	prefix	string	Prefix of the actor.
Last name	lastname	string	Last name of the actor.
Email address	email	string	Email address of the actor.
Mobile phone number	mobile	string	Mobile phone number of the actor.
Deadline	deadline	date-time	The date and time by when the action must have been performed by the actor.
Language	language	string	Language for the invite.
Use strong verification	validateRealIdentity	boolean	Use a stronger method of identification for this actor.
dossierPersonId	dossierPersonId	integer
message	message	string
Signing field	fieldName	string	The name of an existing signing field in the document for this actor to sign.
Placeholder	placeholder	string	The text of a specific placeholder in the document where the actor must place a signature.

DocumentMetaDataModel

General metadata of the document

Name	Path	Type	Description
Document name	name	string	Name for a specific document.
Last document update	lastUpdate	date-time	Date of last update for a specific document.
Number of document pages	pages	integer	Number of pages for a specific document.
Document creation date	created	date-time	Date of creation for a specific document.
Document ID	id	guid	Unique ID of a document.
Document status	status	string	Status for a specific document. (E.g. new, completed, etc..).
Document contains signature	signed	boolean	Indicates whether a specific document already contains one or more signatures.
Document signatures	signatures	array of SignatureData	List of all signatures for a specific document.
Document blank signature fields	emptySignatureFields	array of SignatureField	List of all empty signature fields for a specific document.
Blank signature fields	containsBlankSignatureFields	boolean	Indicates whether a specific document contains blank signature fields.
Document actors	actors	array of ExtendedSignerModel	List of all actors for a specific document.
Request ID	requestId	guid	Unique ID of a request.
Request index	dossierIndex	integer	The index of all documents belonging to a specific request.
documentSize	documentSize	integer	The size of a document belonging to a specific request.
documentType	documentType	string	The type of a document belonging to a specific request.

SignatureData

Name	Path	Type	Description
Certificate subject fields	subject	array of KeyValuePairOfStringAndString	Fields from the subject line of the certificate used for a specific signature.
Certificate issuer fields	issuer	array of KeyValuePairOfStringAndString	Fields from the issuer line of the certificate used for a specific signature.
Signature date	date	date-time	Date and time when a specific signature has been placed.
Signing location	location	string	The geographical location of a specific actor at the time of signing.
Signing reason	reason	string	The reason for signing as provided by a specific actor at the time of signing.
Qualified Electronic Signature	euQualified	boolean	Indicates whether a specific signature is qualified (QeS) conform eIDAS regulations.
Advanced Electronic Signature	advanced	boolean	Indicates whether a specific signature is advanced (AeS) conform eIDAS regulations.
Qualified eSeal	eSeal	boolean	Indicates whether a specific certificate used for signing or sealing is a Qualified eSeal conform eIDAS regulations.
Actor IP address	ipAddress	string	The IP address for a specific actor
Signature field	signatureField	string	The field that has been signed
Signature image	signatureImage	string	The image file that was used for a specific signature as chosen by an actor.

KeyValuePairOfStringAndString

Name	Path	Type	Description
key	key	string
value	value	string

SignatureField

Name	Path	Type	Description
Signature field name	name	string	Name for a specific signature field
Signature field page	page	integer	Page where a specific signature field is placed for a specific document.
Signature field width coordinate	x	double	Width value of the position for a specific signature field relative to the page it is placed in a specific document.
Signature field hight coordinate	y	double	Hight value of the position for a specific signature field relative to the page it is placed in a specific document.
Signature field hight	height	double	Hight value for a specific signature field.
Signature field width	width	double	Width value for a specific signature field.

OrganisationWorkgroup

A workgroup that is used within a dossier

Name	Path	Type	Description
Workgroup ID	id	guid	Unique ID of a workgroup
Workgroup name	name	string	Name for a specific workgroup

RequestModel

Name	Path	Type	Description
Request ID	id	guid	Unique ID of a request
Request name	dossierName	string	Name for a specific request.
Request documents	documents	array of DocumentModel	List of documents included in this request.
Request status	status	string	Status for a specific request. (E.g. new, completed, etc..).
Request actors	actors	array of ExtendedSignerModel	List of all actors for a specific request.
Document signatures	signatures	array of SignatureData	List of all signatures for a specific request.
Request type	dossierType	string	The type for a specific request. (E.g. PDF, SBR Assurance, etc..).
Cancelation reason	reasons	string	Reason of cancelation for a specific request by a user or an actor.
Signer note	signerNote	string	Note for one or more actor(s) that have no other action than sign.
Recipient Note	recipientNote	string	Note for one or more actor(s) that have no other action than download.
Approver note	accorderNote	string	Note for one or more actor(s) that have no other action than approve request.
Request expire date	expires	date-time	Date and time of expiration for a specific request.
Status information	emailActivity	array of EmailActivity	Status information about the process of performing the action by the actor.
My request	myDossier	boolean	Indicates whether you are the owner of a specific request.
Workgroup ID	workgroup	guid	Unique ID of a workgroup.
Security clearance level	clearancelevel	integer	Level of security clearance for a specific request.

DocumentModel

Name	Path	Type	Description
Document ID	id	guid	Unique ID of a document
Document name	name	string	Name of a specific document
Document type	documentType	string	Type for a specific document.
Request index	dossierIndex	integer	The index of all documents belonging to a specific request.
Document status	documentstatus	string	Status for a specific document. (E.g. new, completed, etc..).
Document actors	actors	array of SignerModel	List of all actors for a specific document.

file

This is the basic data type 'file'.