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 |
| 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:
- Create dossier
- Add document(s)
- Add actor(s)
- Start workflow
- Use a trigger to get notified of status changes
- 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
|
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
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 |
User who is the owner of a specific request. |
Returns
- Body
- RequestModel
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
- Body
- ExtendedSignerModel
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
- response
- array of ExtendedSignerModel
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
- response
- array of ExtendedSignerModel
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
- Body
- RequestModel
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
- response
- array of OrganisationWorkgroup
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 |
Emailaddress of the user |
Returns
- response
- array of OrganisationWorkgroup
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
|
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
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 |
User who is the owner of a specific request. |
Returns
- Body
- RequestModel
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
|
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
|
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
|
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'.