link

# The electronic signature life cycle

# Using DocumentService and the SOAP APIs

# 1. Uploading the documents

The first step is to upload the documents that you want the end-user to sign to Signicat's standalone Session Data Storage (SDS).

# 2. Create a signing request

The signing request is a SOAP request sent to DocumentService API. This is where you specify which signing methods should be available to sign with, the documents that should be signed and other options for the signing flow.

Requests are made up of five main components:

  • Task(s)
  • DocumentAction(s)
  • Document(s)
  • Subject(s)
  • Notification(s)

# 3. Redirect the user to Signicat for the signing request

After the signing request has been created and you want the user to sign the document, you need to construct a URL that takes the user to Signicat's electronic signature solution.

# URL format

The URL will have the following format: https://env.signicat.com/std/docaction/service?request_id=request_id&task_id=task_id&artifact=artifact

Parameter Description Example value Required
env env is the environment. When you're first starting out, this will typically be preprod — in production it will be id. In production, if you have acquired a Signicat Subdomain, this must be be used instead.
  • preprod (in pre-production)
  • id (in production)
Yes
service service is the name of your service as registered with Signicat. There is a pre-production service called demo which you may use while developing, but eventually you use your own service.
  • demo (in pre-production environment)
  • yourdomainname.com (in production)
Yes
request_id request_id is the unique identifier for a created request. Yes
task_id task_id is the unique identifier for a specific task in the request. Yes
artifact artifact is optional and should only be included if the return value from DocumentService request includes an artifact or if you specify an artifact later using createArtifact in DocumentService. This is a short-lived single sign-on artifact, valid for only 30 seconds and can be used to secure the signing order if you prefer not to require the end-user to log in with a stronger ID (such as BankId) to be able to view the documents before signing. See Use artifacts to secure signing orders for a complete code example, as well as the section Features and customisation for a more thorough description of artifacts and their usage. No

Important

All URL parameters must be properly URL-encoded using UTF-8, as per RFC 3986.

Example of a valid signing URL: https://preprod.signicat.com/std/docaction/demo?request_id=10112015xwufkg8j94nfikhn0t26mvmme13mqzd37ok0tn5pv9am9y4hl&task_id=task0

For a code example of a simple request using C# or Java, see our code examples for creating a signing order with one signer.

# Request workflow and task order

The order in which the tasks of signature request are completed can be arranged by using depends-on-task within the Task datatype, allowing for complex workflows. For example: Two customers and a sales person need to sign a contract, but the sales person may only sign when both of the customers have completed their signatures.

In this scenario the request would consist of three tasks (one for each signer), so lets call these tasks A, B and C.

  • The first option is to let the two customers sign in parallel. This would be achieved by letting task C depend on task A and B.
  • Alternatively, all signatures could be sequential. This could be achieved by letting task B depend on A and task C depend on B.

# Changing an existing request

There could be various reasons why you would want to change an existing request — the email address or mobile number of one of the signers could have changed, the relevant signers could change or the request could simply become obsolete.

# 4. Receive status of the request

When the signing order was created, you most likely defined a documentactionrequest in order for notifications and callbacks to notify your server (or other recipient) about actions being taken by the signer — whether it's a request being created, cancelled or completed.

We provide three complementary mechanisms for this:

  1. Notification by redirect
  2. Notification by server-to-server callback
  3. Notification by messaging

All are optional and may be used independently.

# Notification by redirect

When you're creating a signing order, the documentactionrequest allows you to specify three different URLs where Signicat can redirect the end-user when they have signed (or declined to sign) a document. These cover the following scenarios:

URL URL is used when
on-task-cancel The URL where the end-user should be returned if the task is cancelled.
on-task-postpone The URL where the end-user should be returned if they choose to postpone the task.
on-task-complete The URL where the end-user should be returned when the task is completed.

The URLs are specified for each signing order and may contain HTTP parameters with session-specific or transaction-specific values. The end-user will not be redirected at all if on-task-complete is missing in the request when a document has been signed.

HTTP redirection cannot be guaranteed, however, the end-user may close their browser before the redirect has completed or network problems may prevent the HTTP request to reach your server.

# Notification by server-to-server callback

The documentactionrequest allows you to specify a URL on your server that Signicat should call when a signing order is created or completed.

Signicat's server will make an HTTPS call to this URL directly (or HTTP, but insecure HTTP calls are only supported in pre-production). This is a server-to-server call, not involving the end-user's browser at all.

You may specify a static URL that should be used for all signing orders or you may specify a different URL for each order. The URL may contain any number of parameters, such as session-specific parameters or user-specific information. You may also add parameters for added security, such as a static or dynamic password. Signicat will always add the requestId in an extra HTTP parameter.

Important

The HTTP call will be made by Signicat's server and will come from a fixed IP address. In order for these to work, Signicat must be informed about the destination address on your end, as our firewall blocks notifications to unknown URLs by default.

The notification is specified in the request with these values:

Attribute Value
type The string "URL"
recipient The URL that Signicat should call (with any HTTP parameters).

You may specify more than one notification if you want Signicat to make more than one callback. Delivery of the notification is guaranteed as long as your server is able to receive HTTP calls.

When doing server-to-server notification, you may choose to add additional security features to make the notification reliable. An example would be to:

  1. Create a one time token (a random number or string) for each request.
  2. Add the token to the callback URL in an HTTP parameter called secure.
  3. Validate that the value of the parameter is correct when Signicat makes the callback.

The steps above will protect against fake HTTP callbacks, since senders of fake callbacks would not be able to guess the correct parameter value.

# Notification by messaging

The documentactionrequest allows you to specify a mobile phone number or an email address where Signicat should send a message when a signing order is created or completed — you may specify one or more notifications like this.

Typical use cases for this would be to send a message to a back office address, send a message to the end-user or even send a message to a local workflow system.

Each message is specified in each request and the text can be personalised or contain user-specific information like customer number, transaction details and so forth. Delivery of the notification depends on the SMS and email infrastructure and cannot be guaranteed.

The notification is specified in the documentactionrequest with these values:

Attribute Value
sender The sender address.
header Subject in email. Not used for SMS.
message The text message in the email or SMS.
type The string "SMS" or "EMAIL".
recipient Phone number (with country code prefix) or email address.

An example can be found here: Notify and get notified when a signing order status changes.

# Notes about security

You should not depend on the correctness of the information you receive in the notifications. The notifications should be regarded as a "hint" about a possible status change in the signing order. You must always call getStatus on Signicat's web service after you have received a notification to get reliable, updated status information.

The "Notification by server-to-server" callback can be extended to include security mechanisms that would make the notification reliable. However, Signicat still recommends that you always call getStatus to get reliable information. The information you receive in return from the getStatus web service call will always be correct and reliable.

# Other web service calls

It is possible to get information about existing requests by using getStatus and getRequestHistory, which in combination yield a precise picture of any given requests as well as related status events.

An example of this can be found here: Check the status and result of a signing order.

Important

getStatus can be used for checking status on selected request, but in general, polling should be avoided. Instead, notifications and callbacks should be used.

# 5. Signing result

Go to the next step, The signing result to learn more about what the signed document looks like and which formats you can choose.

Last updated: 8/12/2021, 12:26:54 PM