# DocumentService v3
Important
Our DocumentService API will be deprecated by the end of 2023. We will continue to support existing integrations. If you are working on a new integration or are planning to upgrade from an older DocumentService version, we strongly recommend that you use our RESTful Sign API instead.
# 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.
# 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. |
NOT IN USE. 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. |
| 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. |
# 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 forEMAIL(and on some occasionsSMS), as this is a link to the login page for the end-user to start the signing/ viewing process. - The
${signCode}is most useful forURL, 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:
|
| 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:
|
| 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.