link
Developer Pages

# Sign API v1

Page contents

# Introduction

The Sign API is a RESTful web service that allows businesses to obtain electronic signatures from their customers. Documents signed using the Sign API are legally binding and can be delivered to the involved parties quickly and efficiently, ensuring greater levels of transparency and traceability as well as lower abandonment rates.

The Sign API serves as Signicat's single integration point for electronic signatures and all underlying methods, both in a browser and in the context of a native app. It also allows service providers to archive documents after they have been signed.

Key concepts

Document: A resource of the Sign API. A document is any file which is uploaded to the Sign API for signing.

End-user: Also referred to as signer or subject. The person who is asked to sign the document(s).

Service provider: Also referred to as merchant. The entity that integrates with the Sign API.

Signing order: A resource of the Sign API. A signing order is an action that is initiated by a service provider to obtain the signature of one or more end-users on one or more documents.

# Differences between the Sign API and the DocumentService API

The main technological difference is that the DocumentService API is a SOAP API and the Sign API is a REST API. Additionally, the Sign API is a one-stop shop compared to DocumentService, which requires the support of several subsystems.

The main functional differences between the two APIs are as follows:

  • The ProvidedDocument data type is deprecated in the Sign API.
  • The send-to-archive field is deprecated in the Sign API, as this feature was only intended to work with the now deprecated ProvidedDocument data type.
  • Specification of authentication methods (using the Signature and AuthenticationBasedSignature data types in DocumentService) has been restructured into enum fields in the Sign API.
  • The DocumentAction and Document data types in DocumentService are merged into the Document model type in the Sign API.
  • In the Sign API, the only country code format allowed for phone number validation is +CC (e.g. +47 for Norway).

# Getting started

To consume Signicat REST services, you will need to acquire an access token using the OpenID Connect (OIDC) protocol. For more information on how to do this, refer to our documentation on Accessing Signicat REST Services.

# API reference

In our Sign API reference, you can find information about the available endpoints and properties, as well as sample requests and responses.

Sign API
Our REST API for sending out documents for electronic signing
REST

# Test information

Visit our Java electronic signatures quick start guide for a guide that will take you through the process of connecting to our electronic signature service. You can either download a sample project or follow our step-by-step guide to get your own sample application up and running.

In both cases, you will then be able to test the entire signing process by creating a signing order, signing it and downloading the resulting file.

# Using the API

The Sign API is used to obtain electronic signatures on digital documents from end-users or businesses. A basic process can be summed up as follows:

  1. The service provider uploads the document in PDF format.
  2. The service provider creates a signing order.
  3. The end-user receives a notification stating that the signing order is ready to be signed. The URL attached to the notification redirects the end-user to the signature task.
  4. The end-user signs the document using one of the available identity methods.
  5. The signing result is created.

The following diagram illustrates the signing process.

click-to-zoom

The sub-sections below contain more detailed information about the actions that must be carried out by the service provider throughout the process.

# Step 1: Obtain an access token and upload a document

Obtain an access token as per our documentation on Accessing Signicat REST Services.

Use the access token to upload a document to the Sign API's built-in Session Data Storage (SDS) for temporary storage.

To upload a document, make a POST call to the documents endpoint. Documents uploaded to the Sign API's built-in Session Data Storage (SDS) must have a MIME type of application/pdf or text/plain.

Important

We recommend using the Sign API's built-in Session Data Storage, rather than the standalone Session Data Storage service that is typically used together with our older DocumentService and PackagingService SOAP APIs.

In the next step, you will need to use the documentId value from the response you receive when creating the signing order.

The document will remain on the server for 30 minutes, after which it will be deleted unless it has been used in a subsequent web service request.

# Step 2: Create and send the signing order

Create the signing order using the Create signing order endpoint.

The signing order can contain more than one task. Each task item should contain the information relevant for each of the tasks that must be carried out by the end-user.

A task may involve signing one or more documents (SIGN), opening a document (VIEW) or uploading a document (UPLOAD). A task may require the end-user to log in.

Important

You will need to replace the value for the documentRef field with the documentId value from the response to the POST call to the documents endpoint in Step 1 above.

The service provider can obtain three different types of signature depending on their use case:

Optionally, it is possible to archive the document electronically once it has been signed by the end-user. This is configured by setting sendResultToArchive to true.

# Notifications

There are three data types that can be used to configure notifications to be sent to the end-user or to a system:

  • TaskNotification
  • SigningOrderNotification
  • PackagingTaskNotification

For example, you can send a TaskNotification automatically after the signing order is created, to let the user know that the document is ready to be signed.

Notifications can be sent as an SMS, an email or a URL.

# URL notifications

In order for a URL notification to work, you must first let Signicat know that you intend to use it. Contact us at support@signicat.com if you would like us to enable URL notification functionality.

If you specify the URL notification type, the following will be returned as URL parameters:

  • requestId
  • taskId or packagingTaskId
  • message

Important

Your call must return an HTTP status code 200. If the server at the recipient's URL responds with any other status code, Signicat considers the notification delivery unsuccessful and and will retry at regular intervals for a period of 24 hours.

# Request example

{
  "tasks": [
    {
      "id": "1",
      "documents": [
        {
          "id": "doc-1",
          "description": "Document",
          "action": "SIGN",
          "source": "SESSION",
          "documentRef": "010420202p3wj0zf0lokur1g6kit8wi0i1eh7sp0xqjddou32vc4xa6453",
          "sendResultToArchive": true
        }
      ],
      "signatureMethods": [
        {
          "name": "nemid",
          "type": "AUTHENTICATION_BASED"
        },
        {
          "name": "nbid-sign",
          "type": "SIGNED_STATEMENT"
        },
        {
          "name": "sbid-sign",
          "type": "SIGNED_STATEMENT"
        }
      ],
      "language": "en",
      "notifications": [
        {
          "id": "not-1",
          "recipient": "ginny@signicat.com",
          "sender": "noreply@signicat.com",
          "header": "Documents ready to be signed ",
          "message": "Please sign this document: ${taskUrl}",
          "type": "EMAIL",
          "schedule": [
            {
              "triggerStatus": "CREATED"
            }
          ]
        }
      ]
    }
  ]
}

# Step 3: Get the result and download the signed document

In order to get updates about the status of the signing order, the service provider can use the Get packaging task status endpoint.

The response will contain information about the status of the task, which can be created, completed, rejected, expired or deleted. It also contains status information for each of the documents in the task. When the status is completed, it means that the end-user has signed the document and the process is finalised.

If the service provider specified that they wanted to send the signed document to permanent storage in step 2 (using the sendResultToArchive field), they will be able to download the signed document from the archive for later use and validation. This can be done through the Get archived document endpoint.

It is also possible to download the signed document if it has not been archived. In this case, the number of days before the signing order and all associated documents (both original and signed) will be deleted is configured as a combination of the following:

  • daysToLive in the Task data type specifies the number of days from when the task is created until the task times out.
  • daysUntilDeletion in the SigningOrder data type specifies the number of days before the signing order is deleted after the last task in the signing order has died, as per daysToLive.

# Other integration details

# Placeholders in notification messages

Placeholders can be used in notification messages to insert certain values such as a signing order ID. Packaging task notifications do not support placeholders. The available placeholders are listed below.

# Signing order-specific placeholders

  • ${orderId} - The signing order ID.
  • ${clientRef} - The clientRef defined in the signing order

# Task-specific placeholders

  • ${taskUrl} - Provides a link to the login page for the end-user to start the signing/ viewing process (e.g. https://preprod.signicat.com/std/docaction/demo?request_id=<order ID>&task_id=<task ID>)
  • ${signCode} - The task's sign code - The sign code can be used as a replacement for request_id and task_id in a URL.
  • ${signCodeUrl} - The sign code equivalent of taskUrl (e.g. https://preprod.signicat.com/std/docaction/demo?sign_code=<sign code>)

# 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.

The name of a custom signing interface configuration can be specified through the configuration field for a given task. This is a customer-specific configuration that needs to be done by Signicat. Contact us at support@signicat.com if you would like us to set up a custom signing interface configuration for you.

# Browser support

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

# Language support

The language for the interface can be defined in the language field when creating the signing order.

The following languages are available. The codes in brackets are the codes you will need to use in the signing order request:

  • Catalan (ca)
  • Danish (da)
  • Dutch (nl)
  • English (en)
  • Estonian (et)
  • Faroese (fo)
  • Finnish (fi)
  • French (fr)
  • German (de)
  • Greenlandic (kl)
  • Italian (it)
  • Norwegian Bokmål (nb)
  • Norwegian Nynorsk (nn)
  • Spanish (es)
  • Swedish (sv)

Important

The above language options only apply to Signicat's electronic signature solution.

The individual identity methods used to obtain the end-user's signature may support different languages, often a subset of the ones listed above.

Last updated: 21/03/2023 16:12 UTC