# Sign API v1

# 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 merchants to archive the 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 to be signed.

End-user: The person who is asked to sign the document(s).

Service provider: Also called "merchant". The entity that will integrate with the Sign API.

Signing order: A resource of the Sign API. A signing order is an action that is initiated by a merchant to obtain the signature of one or more subjects on one or more documents.

# Main differences between the DocumentService API and the Sign 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 the DocumentService SOAP services, which require 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 has also been deprecated, since this feature was only intended to work with the ProvidedDocument data type.
  • Specification of signature type (Signature and AuthenticationBasedSignature data types) has been restructured into enum fields in the Sign API.
  • The DocumentAction and Document data types from the DocumentService API 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

Please refer to the documentation on Accessing Signicat REST Services.

# API reference

For detailed reference documentation and testable examples please refer to the OpenAPI documentation (Swagger).

# 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 signer receives a notification stating that the signing order is ready. The URL attached to the notification redirects the end-user to the task.
  4. The end-user signs the document using one of the available identity methods.
  5. The signing result is created.


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

# Step 1: Initial setup

Obtain an access token and use it to upload a document to Session Data Storage (SDS) for temporary storage. To do so, make a POST call to the /documents endpoint. You will need to use the documentId value from the response you receive when creating the signing order in the next step.

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). They will sometimes require the end-user to log in.


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 merchant can obtain three different types of signature depending on their use case: an authentication-based signature, a signed statement, or a third-party signature. 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.

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, and 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. Bear in mind that, in order for a URL notification to work, you must first let Signicat know that you intend to use it.

# 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 merchant can use the Get 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 finalized.

If the merchant specified that they wanted to send the signed document to permanent storage in step 2 (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.

# Integration details

# Placeholders in notification messages

Placeholders can be used in notification messages to insert certain values such as signing order ID. Note that 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>)

# Language options

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)
  • Finnish (fi)
  • French (fr)
  • German (de)
  • Greenlandic (kl)
  • Norwegian Bokmål (nb)
  • Norwegian Nynorsk (nn)
  • Spanish (es)
  • Swedish (sv)


The above language options only apply to the Sign solution. The identity methods used to obtain the end-user's signature may support different languages, often a subset of the ones listed above.

Last updated: 3/17/2021, 8:19:29 AM