Introduction

DocumentService is a service with a SOAP web service interface. It is used for creating and manipulating document orders for document centric services at Signicat.

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.

Difference between DocumentService-v2 and DocumentService-v3

User Centric Session

Tasks from multiple requests can be signed in one operation by creating a UserSession.

Task improvements

Authentication based signature

A new element to explicitly say that the signature will be authentication based. The existing signature element can now only have 3rd party signature methods.

Configuration

A service can now have multiple signature configurations (for example changing the visuals of Responsive Signflow). The task can then choose which configuration to use with this element.

Profile and language

Each task can select which profile and language that can be used. If set, they will overrule the setting on the request.

Task status

New task status deleted.

Notification

Notification on task staus expired (previously not in use).

Packaging task

A new task type in request. The packaging task is triggered when the last task has completed. This can be used to i.e. automatically create a PAdES document when the documents are signed by the end user.

This feature may reduce the need of packagingservice/createPackage calls when multitask sign orders within a request, as well the need to for inline packaging (this feature is not implemented for production use yet).

Handwritten Signature

Authentication based signature methods can now include an attribute for handwritten signature. With this attribute set, the user will be asked to draw a signature after the sign method has been completed. The sign method can also be omitted, so only the handwritten signature is required.

Signed Statement

This new functionality allows use of text-based signature methods to sign documents. The statement will express the end-user’s consent of the contents of the documents to be signed, and will be constructed in such a way as to include the description/title of the documents to be signed. For ID solutions that support non-visible properties as part of the signature data, a data structure containing cryptographic digests of the documents can also be included.

DocumentService v2 – API

If you are looking for DocumentService v2 – API, you could find it here: DocumentService v2 – API

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

The only difference between the wsdl in preprod 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 this service. This is different in preprod and production.

createRequest

Purpose

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 url’s 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 Descriptio
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 add change the values in an existing notification by disabling the old notification and create 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.

It is not possible to activate a disabled notification. The recommended strategy for re- activating 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.

NB! Note that 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 this value will however 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 task info objects, one for each task in each request

getTaskCount

Purpose

This method provides a count if tasks that matches 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. The task will be activated immediately unless it is specified as dependent on another task that is not completed yet.

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.

It is not possible to activate a disabled task. The recommended strategy for re-activating 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 has occurred on the request. This can be used i.e. to 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 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:

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.

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 and only 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 URL’s passed can contain some server-interpreted variables to help identify the signing order. Please note that the redirect URL’s 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 ${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 i.e. “A”, “1”, “Agreement”, “Task123456” etc.
The task id will be used in url’s 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 the task is created until this 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 he is 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 he can perform the actions required to complete this task. See the Authentication data type.
signature Signature Optional. Specifies the eID signature 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 responsive signflow configuration. This setting will override the configuration set in the request.
on-task-postpone String Optional. The url where the end user should be returned if he chooses to postpone the task. The URL can contain some serverside variables, see notes above.
on-task-complete String Optional. The url where the end user should be returned when the task is completed. The URL can contain some serverside variables, see notes above.
on-task-cancel String Optional. The url where the end user should be returned if the task is cancelled. The URL can contain some serverside variables, see notes above.
depends-on-task String
Optional. The id of another task in this 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. I.e. 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 id (i.e. social security number, personnummer, fødselsnummer, cpr, personbeteckning, hetu).
The end users 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 use mobile (i.e. sms based) authentication mechanisms.
email String Optional. The end users email address.
The end users 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 describes 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 describes 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 senders first name
last-name String Optional. The senders 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 extends the general Document data type.
See Specify the document in DocumentService for examples.

Extentions

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 the Session Data Storage. This is a temporary storage that is accessible via a REST interface.
UploadDocument A specification of a document that is supposed 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 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.
mime-type String The mime-type of this document. E.g.: “text/plain”, “application/pdf”.
data Base64 The data bytes of this document. Plain text should be UTF-8 encoded.
send-to-archive Boolean
If this 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 supports 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. Optional information about the document that will be stored in the signed data object as an external reference. Only some sdo formats supports 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: SdsDocument

Description

A document that is located in the Session Data Storage. This is a 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 this 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. Optional information about the document that will be stored in the signed data object as an external reference. Only some sdo formats supports 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: UploadDocument

Description

A specification of a document that is supposed 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 this 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. Optional information about the document that will be stored in the signed data object as an external reference. Only some sdo formats supports 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: ResultDocument

Description

A specification of a document that is the result of a previous task in this 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 this document in the request.
ref-task-id String The unique id of the task where this 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. Optional information about the document that will be stored in the signed data object as an external reference. Only some sdo formats supports 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: 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. Otherwise, it will not work.

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 HTTP status code 200. The call will be ssl encoded if the url starts with “https”. The url may contain parameters. The request- id and task-id will be added to the url as additional parameters named “requestId” and “taskId”. Please note that the HTTP request sent from Signicat’s servers will ignore any contents returned from your callback site, only the HTTP status code matters.

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} and ${signCode}

The ${taskUrl} is useful for EMAIL (and in some occations, 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 and can be used like this: https://preprod.signicat.com/std/docaction/demo?sign_code=${signCode}.

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.
schedule Schedule Optional. A schedule that specifies when this notification should be sent. 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. I.e. 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 is 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 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 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 dialog message is presented on the web to the end user.

Fields

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

Data type: Authentication

Description

The Authentication data type describes how an end user may authenticate himself before he is 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 randomized 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 dialog 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 signature method based on how the user was authenticated. This is best illustrated by an example:

A task specifies two methods for authentication: “telia” and “nordea”. The task also specifies two methods for signing: “telia-sign” and “nordea-sign”. The signature element for “telia-sign” also specifies that if-authentication should be “telia”, while the signature element for “nordea- sign” specifies that if-authentication should be “nordea”.

With this configuration, if an end user logs in with “telia” then “telia-sign” method is automatically chosen when he should sign a document.

v3 of this API allows for choosing which signflow 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 signature flow to use (Responsive Signflow or Multisign UI).
if-authentication String Optional. One of the methods specified in the authentication element.
dialog Dialog
Optional. A dialog 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 was introduced in v3 of this API, and is used for specifying authentication methods to use for signing. This element will always invoke the Responsive Signflow, 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 dialog 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 is new to v3 of this API, and allows for choosing whether or not a handwritten signature should be applied after signing.

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 info for each document in the task.

Data type: TaskStatus

Description

The status of the task.

Values

Name
Description
created
The task has been created
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 he changes his mind.
expired The task has expired (“expired” is currently not supported in notification schedules)
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 URL’s passed can contain a server-interpreted variable to help identify the signing order. Please note that the redirect URL’s 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 he chooses to postpone the session. The URL can contain some serverside 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 serverside 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 serverside 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 serverside 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
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
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
If the result of the packaging task is to be sent to the archive for permanent storage after it is packaged.
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).

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 info 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