PKIsigning (Preview)

  • Reference

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