Del via


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

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

Create document

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

Create request

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

Delete a request

Permanently deletes a specific request.

Parameters

Name Key Required Type Description
Request ID
requestId True guid

Unique ID of a request.

Delete actor

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

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

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

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

Get actor data by document

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

Get actor data by request

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

Get document data

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

Get request data

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

Get workgroups for organisation

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

Get workgroups for user

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

Resend invite

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

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

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

Update document

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

Update request

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

Withdraw invite

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

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'.