# Quick start guide

Follow these steps to get started with our Signature solution in minutes! This guide will show you step by step how to sign a simple text saying "This text can safely be signed".

If you don't have an account already, you need to create a free Signicat account first:

Create a free account

# Full example for Postman

We have collected all the requests you need in a Postman collection allowing you to immediately test and see how the solution works, no setup required.

Run in Postman (opens new window)

# 1. Create and send document

Under the collection tab in Postman, you should now have a collection called Signicat Express Signature. When you expand the collection, the first item on the list is called Create and send a text document. Open it and click Send.

In the response, inside "signers" there is a URL which points to the signing process. Copy and paste this URL in your browser. Choose Norwegian BankID and sign with a test user, like the following:

National identity number One time password Password
29124815345 otp qwer1234

# 2. Get signing information and the signed document

After you have signed the document you can use the requests "Get information from signing process" and "Get the signed document" in the Postman collection. You will now be able to see the Signed Document Object and information about who signed the document.

# Do you want to set up and use your own test credentials?

The postman collection above works out-of-the-box and is set up with demo client credentials. If you want to add your own credentials after you have created an account (opens new window), open the collection in Postman, click Edit on the collection and go to the Authorization tab. For more information about what to fill in, see step 2 in the guide below.

# Step by step walkthrough guide

# Before you start

# 1. Open Postman (or similar tool)

Our developers like to use Postman, which allows you to easily send requests. It can be downloaded for free from https://www.getpostman.com (opens new window).

You can also download the OpenAPI document for our APIs from our API Reference (click the Download button at the top of the page).

# 2. Get access token

  1. Create a new empty request.
  2. Open the Authorization tab and set the authorisation type to OAuth 2.0.
  3. Click Get New Access Token.
  4. Fill in the fields as shown in the image below. Bear in mind that you can only get an access token for scopes that you have access to. Your Client ID and Client Secret can be found by logging into your Dashboard account under the tab API Clients > Oauth clients.
  5. Click Request Token and then Use Token.

Postman screenshot click-to-zoom

# 3. Create document

To create a document, use the Create document endpoint (opens new window). In Postman, in the Body tab, select the Raw option and select JSON in the dropdown list that appears on the right. Paste the JSON request below into the request body. The text that is going to be signed saying "This text can safely be signed" is Base64 encoded and is what you see in the JSON object as base64Content under dataToSign.

POST /documents

Request sample

{
  "title": "As simple as that",
  "description": "This is an important document",
  "externalId": "ae7b9ca7-3839-4e0d-a070-9f14bffbbf55",
  "dataToSign": {
    "base64Content": "VGhpcyB0ZXh0IGNhbiBzYWZlbHkgYmUgc2lnbmVk",
    "fileName": "sample.txt"
  }, "contactDetails": {
    "email": "test@test.com"
  },
  "signers": [ {
      "externalSignerId": "uoiahsd321982983jhrmnec2wsadm32",
      "redirectSettings": {
        "redirectMode": "donot_redirect"
      },
      "signatureType": {
        "mechanism": "pkisignature"
      }
    }
  ]
}

# 4. Sign the document

In the signer object of the response, you will receive the URL meant for the signer. Copy it, paste it on your browser (clicking it in Postman will not work), and sign the document. You must sign the document with a test user. For more information about test users and how to create them, refer to the email you received during your onboarding to Signicat.

# 5. Get information about the signing process

Create a new request as shown below. Replace {documentId} with the ID from the response body in step 4.

GET /documents/{documentId}

In the response, there will be a property named documentSignature (under signers). Here you will find key information about the signature. The document also contains a status object, which includes the document status and a list of completed packages. The completed packages tell you which file packages you can download using one of the Files endpoints. You can download the signed document as soon as the documentStatus is signed.

# 6. Get the signed document

Create a new request similar to the one below. Replace {documentId} with the ID of the document you want to download.

GET /documents/{documentId}/files?fileFormat=standard_packaging

This will give you the signed document as a Long Term Validation Signed Document Object (LTVSDO). You can also get more information and see the signed document by logging into your dashboard account and going to the Documents (opens new window) tab and clicking Search.

The parameter fileFormat can be set to either native (SDO) or standard_packaging (LTsVSDO). If the signed document is a PDF you can also download the signed document as a PAdES, which is a PDF viewable by the end-user that contains electronic signing data.

Last updated: 20/10/2023 14:34 UTC