# DocumentService v3

# Introduction

DocumentService is a SOAP web service used for creating and manipulating signing orders.

The service may be used from any platform capable of making a SOAP web service call. Signicat provides several connector kits with wrapper classes for accessing the web service. A connector kit may or may not be used when calling the service.

The service relies on Signicat's standalone Session Data Storage (SDS) service for uploading and downloading binary document data.

Note

We now support our existing Enterprise Electronic Signing solutions on our new platform.

If you are an existing customer using DocumentService v3 and PackagingService v4 and have recently migrated to our new platform, the document is uploaded to our Sign API's built-in Session Data Storage (SDS) by using the documents endpoint (opens new window).

For more information, see our guide on setting up an API integration (opens new window).

# Location

The WSDL for the service is available at:

Infrastructure Location
Pre-production https://preprod.signicat.com/ws/documentservice-v3?wsdl
Production https://id.signicat.com/ws/documentservice-v3?wsdl

Note

The only difference between the WSDL in pre-production and production is the SOAP address location attribute.

# List of methods

Method Description
createRequest Used for registering a document action request
getRequest Used for retrieving the details of a document action request
deleteRequest Used for deleting a previously created document action request
createArtifact Used for creating a new single sign-on artifact
addNotification Used to add a new notification to an existing document action request
disableNotification Used to disable an existing notification
getTask Used for retrieving the details of a specific task in a document action request
findTasks Used to search for a set of tasks that matches a specific search filter
getTaskCount Used to get a count of tasks that matches a specific search filter
addTask Used to add a new task to an existing request
disableTask Used to disable an existing task
getStatus Used for checking the status of the tasks in a set of document action requests
setClientStatus Used to update the client status field on a task
getRequestHistory Used to get a list of events that has occurred on a task
createUserSession Used to create a single session containing multiple requests.
getPackagingTaskStatus Used for checking the status of the packaging tasks in a set of document action requests.

# Mandatory parameters in all requests

All requests requires these mandatory parameters for authentication.

Name Data type Description
service String The name of the customer service (the customer account).
password String The password for the service. This is different in pre-production and production.

# Methods

# createRequest

This method is used for registering one or several document action requests.

# Parameters

Name Data type Description
request List of Request See the data type specification for Request

# Return value

Name Data type Description
request-id List of String Unique identifiers for the requests that was created. This identifier should be used when creating end-user URLs and when calling the getStatus method.
artifact String Unique single sign-on token for a task in this request. The artifact will be created if one of the tasks has an authentication element where the attribute artifact is true. The artifact token can be used when creating URLs for end-users. Use the createArtifact method if you need to create an artifact for more than one task.

# getRequest

# Purpose

This method is used for retrieving a previously created request. This will retrieve a copy of the same data that was registered by the createRequest, addTask and addNotification method. Use the getStatus method to get the current status for the request.

# Parameters

Name Data type Description
request-id String The unique id for the request

# Return value

Name Data type Description
request Request The request data

# deleteRequest

# Purpose

This method is used for deleting a previously created request.

# Parameters

Name Data type Description
request-id List of String A list of unique id's for the requests to be deleted

# Return value

Name Data type Description
deleted Integer The number of requests that was deleted

# createArtifact

# Purpose

This method is used for creating single sign-on artifacts. Call this method to create a new single sign-on artifact for a task in an already pre-defined order. The single sign-on artifact will have a lifetime of 30 seconds from the moment is it created. You should create the artifact just in time before you redirect the end-user to Signicat.

# Parameters

Name Data type Description
request-id String The unique id of the request
task-id String The unique id of the task in the request

# Return value

>Name Data type Description
artifact String A single sign-on token with a lifetime of 30 seconds.

# addNotification

# Purpose

This method is used for adding a new notification to an existing request and task. The notification will be distributed immediately unless it is scheduled to be distributed later.

Adding a notification can be useful if you want detailed control of exactly when and how notifications and reminders should be distributed.

You may also change the values in an existing notification by disabling the old notification and creating a new notification with the correct values.

# Parameters

Name Data type Description
request-id String The unique id of the request
task-id String The unique id of the task in the request
notification Notification The new notification

# Return value

No return value

# disableNotification

# Purpose

This method is used for disabling an existing notification on an existing request. It is not possible to delete or change notifications. The recommended strategy if you need to delete or change an existing notification is to disable it and create a new one.

It is not possible to activate a disabled notification. The recommended strategy for reactivating a disabled notification is to create a new, identical notification.

# Parameters

Name Data type Description
request-id String The unique id of the request
task-id String The unique id of the task in the request
notification-id List of String List of notifications to be disabled

# Return value

No return value

# getTask

# Purpose

This method is used for retrieving the details of a specific task. This is a subset of the data that is returned by the getRequest method.

# Parameters

Name Data type Description
request-id String The unique id of the request
task-id String The unique id of the task in the request

# Return value

Name Data type Description
task Task The task data

# findTasks

# Purpose

This method is used to search for a set of requests and tasks. The search filter accepts a wide range of criteria both from the request, the task, the subject and the document. The search will return all requests and tasks that match all of the criteria.

The from-index and to-index parameters can be used to only retrieve a subset of the tasks. This can be useful when creating user interfaces with paging.

Note

The to-index parameter has a default value of 100. The search will return only the first 100 matches unless you raise this value. Raising the value will have a detrimental effect on response time.

# Parameters

Name Data type Description
filter TaskFilter The filter to use when searching for requests and tasks
from-index Integer Optional. Skip all tasks before this index. Default value: 0
to-index Integer Optional. Skip all tasks after this index. Default value 100
sort-column TaskFilterField Optional. The field that should be used to sort the result set
ascending Boolean Optional. If the sort order should be ascending or descending. Default value: ascending

# Return value

Name Data type Description
task List of TaskInfo A list of TaskInfo objects, one for each task in each request

# getTaskCount

# Purpose

This method provides a count if tasks match a specific filter. The method can be used to find the number of tasks that would be returned by a findTasks method call with an identical filter argument.

# Parameters

Name Data type Description
request-id String The unique id of the request
task-id String The unique id of the task in the request
filter Filter The filter to use when searching for requests and tasks

# Return value

Name Data type Description
count Integer The number of tasks that matches the filter

# addTask

# Purpose

This method is used for adding a new task to an existing request, for example to include a new signatory in the business process represented by the signing order. The task will be activated immediately unless it is specified as dependent on another task that is not completed yet. This method has some limitations, namely:

  • It is not possible to specify a new subject for the new task
  • It is not possible to specify new documents in the new task

In order to work around these limitations, you could include the information in the original signing order. This workaround is not applicable in cases where the information is not known at the time of creating the signing order.

# Parameters

Name Data type Description
request-id String The unique id of the request
task Task The new task

# Return value

No return value

# disableTask

# Purpose

This method is used for disabling an existing task. It is not possible to delete or change tasks. The recommended strategy if you need to delete or change an existing task is to disable it and create a new one. It is not possible to activate a disabled task. The recommended strategy for reactivating a disabled task is to create a new, identical task.

# Parameters

Name Data type Description
request-id String The unique id of the request
task-id String The unique id of the task in the request

# Return value

No return value

# getStatus

# Purpose

This method is used for checking the status of a document action request.

# Parameters

Name Data type Description
request-id String The unique id of the request

# Return value

Name Data type Description
task-status-info List of TaskStatusInfo A list of task-status-info objects, one for each task in the request.

# setClientStatus

# Purpose

This method is used for setting the value of the client status field on a task. The client status field is not used by the service. The field is provided so that the client can record and maintain a client-specified status for each task.

The field can be used to store a string, a JSON structure, Base64-encoded binary data, etc. The field must not exceed 256 characters. The client status is returned by the getStatus and findTask methods.

# Parameters

Name Data type Description
request-id String The unique id of the request
task-id String The unique id of the task in the request
client-status String Any value

# Return value

No return value

# getRequestHistory

# Purpose

This method provides a list of events that have occurred on the request. This can be used to e.g. display a history for customer support or an administrator or to create statistics on how the service is used.

# Parameters

Name Data type Description
request-id String The unique id of the request

# Return value

Name Data type Description
event List of Event An ordered list of events Possible values: request-created, notification-sent, task-started, task-rejected, task-completed, error, document-uploaded, document-signed, document- viewed, document-sign-cancelled, document-deleted, user-authenticated, user-authentication-cancelled.

# createUserSession

# Purpose

This method is used to bind multiple document action requests together to one user-centric session.

# Parameters

Name Data type Description
userSession userSession Data type containing session data

# getPackagingTaskStatus

# Purpose

This method is used for checking the status of the packaging tasks in a document action request.

# Parameters

Name Data type Description
request-id String The unique id of the request

# Return value

Name Data type Description
packaging-task-status-info List of PackagingTaskStatusInfo A list of packaging-task-status-info objects, one for each packaging task in the request

# Data types

# Data type: Request

# Description

The Request data type describes a request for an action on one or more documents by one or more subjects. The main data in a request is:

  • The documents
  • The subjects (users)
  • The tasks where one user is asked to perform a specific action (typically to sign) one or more documents
  • The packaging tasks where one or more signed documents are packaged into another format, e.g. one or more XAdES documents packaged to a single PAdES document

# Fields

Name Data type Description
profile String Optional. The name of the graphical profile to use
language String Optional. A two-letter language code. E.g.: nb, sv, fi, en, da.
subject List of Subject Optional. One or more users that can be referenced from a task element. The subject can also be specified directly inside the task element.
document List of Document Optional. One or more documents that can be referenced from a task element. A document can also be specified directly inside the task element.
task List of Task One or more tasks. See the documentation of the Task data type.
client-reference String Optional. A client-specific reference. This value will not be used by the service, but will be returned by the methods getStatus, getRequest and findTasks.
sender Sender Optional. The sender of the request. See the documentation of the Sender data type.
notification Notification Optional. One or more notifications that should be sent immediately or later as specified by the notification.
days-until-deletion Integer Optional. The number of days before the request is automatically deleted from Signicat's storage after the last task in the request has died (see days-to-live on the Task element). Documents in the archive will not be deleted even if the request that created the documents is deleted. A document that is not in the archive will be deleted.
sdo-format String NOT IN USE. Optional. The requested format on the SDO that is returned. Valid values are NATIVE and PADES. Default value: NATIVE.
account String Optional. Required if the request should be registered on a specific Documents account. This is only relevant if this service is used in combination with Signicat Documents.
packaging-task List of PackagingTask Optional. One or more packaging tasks. See the documentation of the PackagingTask data type.
lookup-task List of LookupTask Optional. One or more lookup tasks. See the documentation of the LookupTask data type.

# Data type: Task

# Description

The Task data type describes a specific document task for an end-user. A task could be to sign one or more documents or to open and view a document. A task will sometimes require the end-user to log in. A task can always be completed in one web session, but the end-user may also perform only parts of a task in one web session and come back and complete the task later. A task will always only have one end-user (subject).

# Notes about the ontask*-fields

The ontaskcomplete, ontaskpostpone and ontaskcancel fields can be used to get an indication of status of a signing order. The URLs passed can contain some server-interpreted variables to help identify the signing order.

Note

The redirect URLs will be passed to the web browser on the client, which means that the data potentially may be tampered with by the client. Available variables are ${taskId} and ${requestId}.

ontaskcomplete = "https://foo.com/verifyreq.bar?requestId=${requestId}&taskId=${taskId}&status=taskcomplete"
ontaskpostpone = "https://foo.com/verifyreq.bar?requestId=${requestId}&taskId=${taskId}&status=taskpostponed"
ontaskcancel = "https://foo.com/verifyreq.bar?requestId=${requestId}&taskId=${taskId}&status=taskcanceled"

Other means of identifying which request and taskId has been completed is using URL type Notifications or saving the requestid returned by DocumentService .createRequest() in a database or similar.

# Fields

Name Data type Description
id String  A unique identifier for this task. The id must be specified by the client that creates the task. The id must be unique in the scope of the request. An id may be e.g. A, 1, Agreement, Task123456, etc. The task id will be used in URLs and must not contain sensitive information.
subject Subject The end-user that should perform the actions required by this task. A task may only specify either the subject field or the subject-ref field. A task can never have more than one subject.
subject-ref String A reference to a subject that should perform the actions required by this task. A task may only specify either the subject field or the subject- ref field. A task can never have more than one subject.
days-to-live Integer Optional. The number of days from when the task is created until the task times out. The end-user will not be allowed to access or perform any operation on the task after this deadline.
dialog Dialog Optional. A message text that is displayed to the end-user when they are about to complete the task.
document-action DocumentAction One or more document actions. This is the specification of the particular actions that the end-user is asked to perform. See the documentation for the DocumentAction data type.
notification Notification Zero or more notifications that should be sent out either when this task is created or later (as specified in the notification)
authentication Authentication Optional. Specifies that the end-user must log in before they can perform the actions required to complete this task. See the Authentication data type.
signature Signature Optional. Specifies the signing methods that the end-user may use to sign documents.
authentication-based-signature AuthenticationBasedSignature Optional. Can be used instead of a signature element in order to define authentication methods to use for signing.
profile String Optional. The name of the graphical profile to use. This will override the profile set in the request.
language String Optional. A two-letter language code. E.g.: nb, sv, fi, en, da. This setting will override the language set in the request.
configuration String Optional. The name of a signature configuration. This setting will override the configuration set in the request.
on-task-postpone String Optional. The URL the end-user should be returned to if they choose to postpone the task. The URL can contain some server-side variables, see notes above.
on-task-complete String Optional. The URL the end-user should be returned to when the task is completed. The URL can contain some server-side variables, see notes above.
on-task-cancel String Optional. The URL the end-user should be returned to if the task is cancelled. The URL can contain some server-side variables, see notes above.
depends-on-task String Optional. The id of another task in the request that this task depends on. The current task will not be started before the other task is completed. If the current task depends on several other tasks, multiple "depends-on-task" elements may be defined.
bundle Boolean Optional. If multiple documents within a task should be treated as a bundle. This attribute should be true in order to use Signed Statement signatures. Default value: false
sign-text String Optional. The contents of this field will be displayed to the end-user as part of the signing process and is intended to describe the documents, the context and other relevant information about the documents. If this field is configured, it will override the default sign text (the sign-text-entry field of the Document type will be ignored). The maximum length of this field is 2048 characters.

# Data type: Subject

# Description

The Subject data type describes an end-user that should perform the actions specified in a Task. All fields except the id are optional. However, different use cases will require some fields to exist, e.g. the mobile number is required if the user is asked to log in with an SMS one-time code.

# Fields

Name Data type Description
id String A unique identifier for this subject in this request. The id must be specified by the client and must be unique in this request.
national-id String Optional. The end-user's national identification number (e.g. social security number, personnummer, fødselsnummer, CPR, personbeteckning, hetu). The end-user's id is matched against this attribute if the end-user authenticates or signs using an eID that returns a national id.
first-name String Optional. The end-user's first name.
last-name String Optional. The end-user's last name.
mobile String Optional. The end-user's mobile phone. The end-user's id is matched against this attribute if the end-user authenticates or signs using an eID that uses mobile (e.g. SMS-based) authentication mechanisms.
email String Optional. The end-user's email address. The end-user's id is matched against this attribute if the end-user authenticates or signs using an eID based on email.
username String Optional. The end-user's username. The end-user's id is matched against this attribute if the end-user authenticates or signs using an eID that returns a username (i.e. an eID based on username/password).
attribute Attribute Optional. A list of other attributes that describe the subject. This list of attributes is only necessary when using an eID that cannot use any of the other strongly typed attributes on the subject.

# Data type: Attribute

# Description

The Attribute data type describes zero or more attributes that describe a subject. This list of attributes is only necessary when using an eID that cannot use any of the other strongly typed attributes on the subject.

# Fields

Name Data type Description
name String The attribute name
value String The attribute value

# Data type: Sender

# Description

The Sender data type describes the person that is sending out this request or a notification.

# Fields

Name Data type Description
unique-id String The sender's unique identity. This can be a username. The unique-id is used to identify the sender in reports and administrative tools.
first-name String Optional. The sender's first name.
last-name String Optional. The sender's last name.

# Data type: Document

# Description

The Document data type describes a document. The Document data type is a superclass with five subclasses. The five data types extend the general Document data type.

# Extensions

Extention Description
ProvidedDocument A document where the document data is provided as a field in the web service XML element.
ArchiveDocument A document in the archive.
SdsDocument A document located in Signicat's standalone Session Data Storage. This is temporary storage that is accessible via a REST interface.
UploadDocument A specification of a document that is meant to be uploaded by the end-user.
ResultDocument A document that is the result of a previous task.

# Data type: ProvidedDocument

# Description

A document where the document data is provided as a field in the XML.

# Fields

Name Data type Description
id String A unique identifier for the document in the request.
description String A human-readable description of the document. This description is used in the user interface and is also part of the signed data object for some eIDs.
mime-type String The MIME type of the document. Must be application/pdf or text/plain.
data Base64 The data bytes of the document. Plain text should be UTF-8 encoded.
send-to-archive Boolean If the provided document is to be sent to the archive for permanent storage after it is signed. If you want to archive the signed document, use the send-result-to-archive attribute on the DocumentAction element.
form Form Optional. The form data that should be used. Only relevant if you are using Signicat Secure Forms.
external-reference String Optional. Optional information about the document that will be stored in the signed data object as an external reference. Only some SDO formats support this.
sign-text-entry String Optional. Optional sign-text-information that will be displayed to the customer in the final parts of the signing ceremony. May not be supported by all ID methods and document formats. Meant to be used for relatively short texts. Currently, the max length is 1024 chars.

# Data type: ArchiveDocument

# Description

A document that is located in the archive.

# Fields

Name Data type Description
id String A unique identifier for this document in the request.
ref-archive-id String The unique archive ID that identifies the document.
form Form Optional. The form data that should be used. Only relevant if you are using Signicat Secure Forms.
external-reference String Optional. Information about the document that will be stored in the signed data object as an external reference. Only some SDO formats support this.
sign-text-entry String Optional. Optional sign-text information that will be displayed to the customer in the final parts of the signing ceremony. May not be supported by all ID methods and document formats. Meant to be used for relatively short texts. Currently, the max length is 1024 chars.

Important

You must manage each archive-id in your own system and map it to the relevant document.

If you do not know your archive-id and would like to retrieve an archived document, or if you would like to get a list of all your archive IDs, contact us at support@signicat.com. This service will entail additional costs. With the archive-id, you can then retrieve the corresponding archived document yourself.

# Data type: SdsDocument

# Description

A document that is located in Signicat's standalone Session Data Storage. This is temporary storage that is accessible via a REST interface.

# Fields

Name Data type Description
id String A unique identifier for this document in the request.
ref-sds-id String The unique SDS id that identifies the document.
description String A human-readable description of the document. This description is used in the user interface and is also part of the signed data object for some eIDs.
send-to-archive Boolean If the SDS document is to be sent to the archive for permanent storage after it is signed. If you want to archive the signed document, use the send-result-to-archive attribute on the DocumentAction element.
form Form Optional. The form data that should be used. Only relevant if you are using Signicat Secure Forms.
external-reference String Optional. Information about the document that will be stored in the signed data object as an external reference. Only some SDO formats support this.
sign-text-entry String Optional. Sign-text-information that will be displayed to the customer in the final parts of the signing ceremony. May not be supported by all ID methods and document formats. Meant to be used for relatively short texts. Currently, the max length is 1024 chars.

# Data type: UploadDocument

# Description

A specification of a document that is meant to be uploaded by the end-user.

# Fields

Name Data type Description
id String A unique identifier for this document in the request.
description String A human readable description of the document. This description is used in the user interface and is also part of the signed data object for some eIDs.
send-to-archive Boolean If the upload document is to be sent to the archive for permanent storage after it is signed. If you want to archive the signed document, use the send-result-to-archive attribute on the DocumentAction element.
form Form Optional. The form data that should be used. Only relevant if you are using Signicat Secure Forms.
external-reference String Optional. Information about the document that will be stored in the signed data object as an external reference. Only some SDO formats support this.
sign-text-entry String Optional. Sign-text-information that will be displayed to the customer in the final parts of the signing ceremony. May not be supported by all ID methods and document formats. Meant to be used for relatively short texts. Currently, the max length is 1024 chars.

# Data type: ResultDocument

# Description

A specification of a document that is the result of a previous task in the request. This document type is used if one task should reference the result of a previous task.

# Fields

Name Data type Description
id String A unique identifier for the document in the request.
ref-task-id String The unique id of the task where the document will be created.
ref-document-id String The unique id of the document in the task.
form Form Optional. The form data that should be used. Only relevant if you are using Signicat Secure Forms.
external-reference String Optional. Information about the document that will be stored in the signed data object as an external reference. Only some SDO formats support this.
sign-text-entry String Optional. Sign-text-information that will be displayed to the customer in the final parts of the signing ceremony. May not be supported by all ID methods and document formats. Meant to be used for relatively short texts. Currently, the max length is 1024 chars.

# Data type: Notification

# Description

The Notification data type describes a notification to an end-user or a system about an event in the system. A notification may be sent as an email, an SMS or as a callback to a URL. Bear in mind that, in order for a URL notification to work, you must notify Signicat beforehand.

Task-level notifications behave differently than request-level notifications. Specifically, request-level notifications are only triggered after all the tasks in the request have reached a final state (completed or rejected), while task-level notifications can have a schedule for when they should be triggered.

If no schedule is set, task-level notifications are triggered when the task status is created. See the table below for further information. If the notification type is set to URL, then the notification will be made as an HTTP GET (not POST) call to the URL specified in the recipient field. This call must return the HTTP status code 200. The call will be SSL-encoded if the URL starts with https. The URL may contain parameters.

The request-id, task-id and message will be added to the URL as additional parameters named requestId, taskId and Message.

The HTTP request sent from Signicat's servers will ignore any contents returned from your callback site; only the HTTP status code matters. A notification like this one:

    <notification type="URL" notification-id="notification1">
        <recipient> https://foo.org/callback?hubId=ABC123&loanId=foo&environmentId=47</recipient>
        <message>Ping pong</message>
    </notification>

Would send the following callback:

https://foo.org/callback?hubId=ABC123&loanId=foo&environmentId=47&requestId=bar&taskId=baz&message=Ping+pong

The message texts in the notification may contain some placeholders in addition to plain text:

Request-specific placeholders:

Message field: ${requestId} and ${clientRef}

Task-specific placeholders:

Message field: ${taskUrl}, ${signCode} and ${signCodeUrl}

Note

  • The ${taskUrl} is useful for EMAIL (and on some occasions SMS), as this is a link to the login page for the end-user to start the signing/ viewing process.
  • The ${signCode} is most useful for URL, where you will be generating the URL for the end-user on your side. It can be used as follows:
https://preprod.signicat.com/std/docaction/demo?sign_code=${signCode}

Alternatively, you can use ${signCodeUrl} to insert the entire URL into an SMS, like this:

Click on this link to sign: ${signCodeUrl}</code>

# Fields

Name Data type Description
type NotificationType The notification type. Valid values: EMAIL, SMS, URL.
notification-id String A unique id for this notification in the scope of the task. The id must be created by the client when the notification is created.
recipient String The address of the recipient of this notification.
sender String Optional. The address or name of the sender of this notification. Only relevant if the notification type is EMAIL.
header String Optional. The header or subject text of the message. Only relevant if the notification type is EMAIL.
message String The message text in the notification. Formatting is not supported in notification messages.
schedule Schedule Optional. A schedule that specifies when this notification should be sent (only for task-level notifications). See the data type for Schedule.

# Data type: Schedule

# Description

The Schedule data type specifies when a notification should be distributed.

The notification will be distributed as soon as ALL of the criteria are met. For example, if both state-is and days-of-week is specified, then the notification will not be distributed before both the state is exactly as specified and the time is one of the specified week days at the same time.

Default values may be configured on a customer service level.

# Fields

Name Data type Description
state-is TaskStatus The notification should be not be distributed before the task reaches this status.
wait-until DateTime Optional. The notification should be distributed at or after this time.
wait Wait Optional. The notification should not be distributed before this number of days and hours has passed since the notification was created, completed, rejected or expired. The wait time is calculated based on the provided state-is property. Therefore, if you specify the wait-property, a state-is value must also exist.
days-of-week String Optional. The notification should only be distributed on these weekdays. Weekdays are specified by comma-separated numbers (1 to 7) or as a range. Monday is day number 1. Example values:
  • 1,3,5,7
  • 1-5,7
time-of-day String Optional. The notification should only be distributed on these times of day. Hours are specified by comma-separated numbers or as a range. Example values:
  • 7-23
  • 8-11,12-16
timezone String Optional. The timezone for time specifications.

# Data type: DocumentAction

# Description

The DocumentAction data type describes a required action an end-user must perform. This could be signing a document, uploading a document or opening and viewing a document.

# Fields

Name Data type Description
dialog Dialog Optional. A message text connected to the specified document. Currently not in use.
document Document The document to be viewed, signed or uploaded. A document action may specify either the document field or the document-ref field. A document action can only contain one document.
document-ref String A reference to a document specified in the request scope. A document action may specify either the document field or the document-ref field. A document action can only contain one document.
order-index Integer The index of this action in the task scope.
type DocumentActionType The action type. Valid values: sign, view, upload.
optional Boolean Gives the end-user the option to skip this action.
send-result-to-archive Boolean Optional. The signed or uploaded document is sent to archive. Default value: false.

# Data type: Dialog

# Description

The Dialog data type describes a text message that is connected to a task or a specific document. The dialogue message is presented on the web to the end-user.

# Fields

Name Data type Description
title String The title or header of the dialogue message.
message String The message text

# Data type: Authentication

# Description

The Authentication data type describes how an end-user may authenticate themselves before they are entitled to see the document.

The artifact field triggers a mechanism for single sign-on to Signicat's service. If artifact is true then the web service will return an artifact token. The artifact token is a randomised string with high entropy. This token should be added as an extra parameter when creating the HTTP URL for the end-user.

HTTP requests with a valid artifact will not be asked to log in. The returned artifact is valid for 30 seconds.

# Fields

Name Data type Description
method Method One or more methods. The method names should match the method definitions on the service.
artifact Boolean See the description for the Authentication data type above.
dialog Dialog Optional. A dialogue message that may be presented on the web page when the user is asked to log on. Currently not in use.

# Data type: Signature

# Description

The Signature data type describes how an end-user may sign documents that require digital signing.

The if-authentication attribute makes it possible to automatically select a signing method based on how the user was authenticated. This is best illustrated by an example:

A task specifies two methods for authentication: nbid and nbid-mobil.

The task also specifies two methods for signing: nbid-sign and nbid-mobil-sign. The signature element for nbid-sign also specifies that if-authentication should be nbid, while the signature element for nbid-mobil-sign specifies that if-authentication should be nbid-mobil.

With this configuration, if an end-user logs in with nbid, then the nbid-sign method is automatically chosen. The API allows you to choose which signing interface to use with the Boolean responsive.

# Fields

Name Data type Description
method Method One or more methods. The method names should match the method definitions on the service.
responsive boolean Optional. Defines which signing interface to use (our current Responsive Signflow solution or our older Multisign UI).
if-authentication String Optional. One of the methods specified in the authentication element.
dialog Dialog Optional. A dialogue message that may be presented on the web page when the user is asked to sign the document. Currently not in use.

# Data type: AuthenticationBasedSignature

# Description

This element is used for specifying authentication methods to use for signing. This element will always invoke the Responsive Signflow interface and cannot be used simultaneously with the signature element.

# Fields

Name Data type Description
method Method One or more methods. The method names should match the method definitions on the service.
if-authentication String Optional. One of the methods specified in the authentication element.
dialog Dialog Optional. A dialogue message that may be presented on the web page when the user is asked to sign the document. Currently not in use.

# Data type: Method

# Description

The Method data type allows you to choose if a handwritten signature should be applied after signing. You can also specify a method that can be used to sign the document. See our InkSign (handwritten signatures) documentation for an example request.

# Fields

Name Data type Description
handwritten boolean Can be true or false. If set to true with no method given, only a handwritten signature will be requested.

# Data type: TaskStatusInfo

# Description

The TaskStatusInfo data type describes the status for a specific task.

# Fields

Name Data type Description
request-id String The unique request id
task-id String The unique task id (is omitted if task status is deleted)
task-status TaskStatus The status for this task. Valid values: created, completed, rejected, deleted, expired
client-reference String The client-reference that was registered with this task, if any.
client-status String The last client-status that was registered on this task, if any.
document-status List of DocumentStatus Status information for each document in the task.

# Data type: TaskStatus

# Description

The status of the task.

# Values

Name Description
created The task has been created
forwarded The end-user has forwarded the task to another signer.

Note that Signature Forwarding needs to be configured at Signicat's end. To start using Signature Forwarding, send a request to Signicat at support@signicat.com.
completed The task has successfully been completed by the end-user
rejected The end-user has actively rejected the task. The end-user may still access the task and complete it if they change their mind.
expired The task has expired
deleted The task has been deleted and is no longer available.

# Data type: DocumentStatus

# Description

Description of a document that was created by this task. E.g. the signed SDO.

# Fields

Name Data type Description
id String The unique id of the original document in the request
original-uri String URL to the original document
result-uri String URL to the result document.
form-output-param FormParam Parameters that was filled in by the end-user. Only relevant if you are using Signicat Secure Forms.

# Data type: Wait

Name Data type Description
days String Number of days to wait before sending a notification
hours String Number of hours to wait before sending a notification
minutes String umber of minutes to wait before sending a notification

# Data type: TaskFilter

# Description

The TaskFilter data type specifies a set of criteria that is used to create a set of tasks. The filter will only return tasks where all of the criteria are meet.

# Fields

Name Data type Description
criteria List of TaskFilterCriteria A list of criteria that restricts a set of tasks
from-date DateTime Optional. Only include tasks created on or after this date
to-date DateTime Optional. Only include tasks created on or before this date

# Data type: TaskFilterCriteria

# Description

The TaskFilterCriteria data type specifies a criterion that a request or task must meet to be included in a search. The use of this data type is best described by examples:

field value operator case-sensitive
language nb equals
document-description 123456 contains false
subject-last-name Hansen equals false

# Fields

Name Data type Description
field TaskFilterField One of a list of fields that can be used to restrict the set of tasks.
value AnyType The value that should be compared
operator TaskFilterCondition Optional. The operator that should be used when comparing the value. Valid values: equals, not-equals, contains, less- than, bigger-than. Default value: equals
case-sensitive Boolean Optional. Set to true if a comparison of the text field should be case-sensitive.

# Data type: Form

# Description

The Form data type is used when requesting an input form. This is only relevant if you are using Signicat Secure Forms.

# Fields

Name Data type Description
id String The id of one of the registered form templates.
input-param FormParam List of parameters to be used with the form. The list may be empty if you have no parameters.
case-sensitive Boolean Optional. Set to true if a comparison of the text field should be case-sensitive.

# Data type: FormParam

# Description

The FormParam data type describes a specific parameter in a form. This is only relevant if you are using Signicat Secure Forms.

# Fields

Name Data type Description
name String The name of the parameter. This must match the name of the parameter in the form template.
value String The parameter value.

# Data type: UserSession

# Description

The UserSession contains multiple tasks from different requests that shall be presented together.

# Notes about the onsession fields

The onSessionPostpone, onSessionComplete and onSessionCancel fields can be used to get an indication of status of a signing order. The URLs passed can contain a server-interpreted variable to help identify the signing order.

Note

The redirect URLs will be passed to web browser on the client, which means that the data potentially may be tampered with by the client. Available variables are ${userSessionId}.

# Fields

Name Data type Description
language String Optional. A two-letter language code. E.g.: nb, sv, fi, en, da. Will override the language setting in the DARs.
onSessionPostpone String Optional. The URL where the end-user should be returned if they choose to postpone the session. The URL can contain some server-side variables, see notes above.
onSessionComplete String Optional. The URL where the end-user should be returned when the session is completed. The URL can contain some server-side variables, see notes above.
onSessionCancel String Optional. The URL where the end-user should be returned if the session is cancelled. The URL can contain some server-side variables, see notes above.
sessionTask List of SessionTaskInfo Optional. The URL where the end-user should be returned if the session is cancelled. The URL can contain some server-side variables, see notes above.

# Data type: SessionTaskInfo

# Description

An existing request with a task. Usually a set of documents created by one business process.

# Fields

Name Data type Description
requestId String The unique id of the request.
taskId String The ID of the task in the request. The taskIDs do not need to be unique within the UserSession.
order BigInteger The order in which this request/task should show up.
description String Optional. Description of the documents in this request/task.

# Data type: PackagingTask

# Description

The PackagingTask data type describes a packaging operation to be performed on one or more signed documents, e.g. packaging one or more XAdES documents into a single PAdES document.

The input to the operation is a set of signed documents resulting from the regular tasks in the current request. For packaging across document action requests, the PackagingService must be used.

# Fields

Name Data type Description
packaging-task-id String Required. A unique identifier for this packaging task. The id must be specified by the client that creates the packaging task. The id must be unique in the scope of the request.
method String Required. The name of the packaging method to be used in the packaging task. The method name should match the method definition on the service.
send-to-archive Boolean Optional. If the result of the packaging task is to be sent to the archive for permanent storage after it is packaged. Default value: false
packaging-task-document List of PackagingTaskDocument One or more packaging task documents. This is the specification of the documents to be used as input to this packaging task. See the documentation of the PackagingTaskDocument data type.
packaging-notification Notification Zero or more notifications that should be sent out either when this packaging task is created or later (as specified in the notification).
packaging-task-lookup-document List of PackagingTaskLookupDocument Optional. Refers to the lookups that have to be included in a given packaging task.

# Data type: PackagingTaskDocument

# Description

The PackagingTaskDocument data type describes the result of a document action from a task within the same document action request.

# Fields

Name Data type Description
task-id String The unique identifier of the task wherein the document action resides.
document-id String The unique identifier of the document that the document action refers to.

# Data type: PackagingTaskStatusInfo

# Description

The PackagingTaskStatusInfo data type describes the status of a specific packaging task.

# Fields

Name Data type Description
request-id String The unique request id
packaging-task-id String The unique packaging task id
packaging-task-status PackagingTaskStatus The status for this packaging task. Valid values: "created, completed, failed"
packaging-document-status List of PackagingDocumentStatus Status information for each packaging document in the packaging task.

# Data type: PackagingTaskStatus

# Description

The status of the packaging task.

# Fields

Name Description
created The packaging task that has been created
completed The packaging task has successfully been completed
failed The packaging task has failed

# Data type: PackagingDocumentStatus

# Description

Description of the result of the packaging operation performed by this packaging task.

# Fields

Name Data type Description
id String The unique id of the original document in the request
result-uri String URL to the result of the packaging operation

# Data type: PackagingTaskLookupDocument

# Description

The packaging task lookup document data type refers to the lookups that have to be included in a given packaging task.

# Fields

Name Data type Description
lookup-task-id String The unique identifier of the lookup task as specified in the lookup-task-id field of the lookup task.

# Data type: LookupTask

# Description

This data type describes a lookup operation to be performed on a business. Each lookup task can only be performed on one business, but you can concatenate several lookup tasks within the same request. For further details about Business Lookups, see our Business Lookups documentation.

# Fields

Name Data type Description
lookup-task-id String The unique identifier for the lookup task. Used to reference lookup tasks in packaging tasks.
provider String The name of the lookup provider to be used. See our Business Lookups documentation for the list of available providers.
orgnr String The identifier of the business the user wants information about. Varies depending on the provider (see our Business Lookups documentation for details.

# Integration details

# Signing interface configuration options

The documents to be signed, viewed or uploaded are presented to the end-user in Signicat's document viewer.

Signicat can customise a number of functional options, such as signing process behaviour and document packaging choices, as well as the graphical end-user experience through styling, different rendering and method flow options, buttons and dialogues as well as feature toggles. See our document presenter documentation for details on graphical customisation options.

# Browser support

For a complete list of supported browsers, see our Electronic signatures browser support page.

Last updated: 07/03/2024 14:17 UTC