Samleikin signing

Samleikin enables electronic signing for Faroese end-users through the Sign API v2 AUTHENTICATION_BASED flow. This guide details how to configure and invoke samleikin for signing.

Note

This guide focuses on electronic signing. For information about the identity provider and authentication, see our Samleikin documentation.

Supported capabilities

Capability	Support
Identity provider name	`samleikin`
Signing flow	`AUTHENTICATION_BASED`
Signature result	XAdES, digitally signed by Signicat.
PDF packaging	Set `packageTo` to `["PADES_CONTAINER"]` to produce a PAdES document.

The signer reviews and consents to the document, then authenticates with Samleikin. Signicat combines the proof of these actions with the original document. For more information on how authentication-based signing works, see our authentication-based signing overview.

Prerequisites

Set up an API client with the Signature API permission and obtain an access token, as described in our Sign API v2 integration prerequisites.
In the Signicat Dashboard, select your account and go to Products > eID and Wallet Hub > eIDs. Enable Samleikin as you would other authentication-based signing methods.
Upload a document and create a document collection. Keep the returned documentId and document collection id for the signing request. The example below uses an unsigned PDF.

Date of birth requirements

Confirm date of birth availability and mapping

If your integration requires the signer's date of birth (DOB), contact us by creating a support ticket in the Signicat Dashboard to confirm that DOB is available for your Samleikin integration and mapped to the signing result. Confirm any required account configuration before relying on DOB in your application or PAdES evidence.

Setting idpName to samleikin selects the signing method; it does not establish that DOB is available. Verify the returned DOB in a completed test session and its PAdES evidence before going live.

Signing setup

Set identityProviders[].idpName to samleikin and signingFlow to AUTHENTICATION_BASED in the signingSetup array:

[
  {
    "identityProviders": [
      {
        "idpName": "samleikin"
      }
    ],
    "signingFlow": "AUTHENTICATION_BASED"
  }
]

Create a signing session

Send an HTTP POST request to the Signing sessions endpoint:

POST https://api.signicat.com/sign/signing-sessions
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

The following is an example of a request body for a signing session with Samleikin as the only active method. Replace the document identifiers with the values from the upload and document collection responses and replace the redirect URLs with your application's URLs. The endpoint accepts an array of signing sessions.

[
  {
    "title": "Sign your agreement",
    "externalReference": "samleikin-agreement-001",
    "documents": [
      {
        "action": "SIGN",
        "documentCollectionId": "0197d5cb-dbbd-7e4d-b95c-9f2920882733",
        "documentId": "0197d5cb-d683-7451-9b21-1a2da906b353"
      }
    ],
    "signingSetup": [
      {
        "identityProviders": [
          {
            "idpName": "samleikin"
          }
        ],
        "signingFlow": "AUTHENTICATION_BASED"
      }
    ],
    "packageTo": ["PADES_CONTAINER"],
    "redirectSettings": {
      "success": "https://www.example.com/signing/success",
      "cancel": "https://www.example.com/signing/cancel",
      "error": "https://www.example.com/signing/error"
    }
  }
]

Session response

The following excerpt from an example response shows the session ID, signing URL and initial state:

[
  {
    "id": "0197d5fb-d3ce-70c0-a420-68972e1c4d57",
    "signatureUrl": "https://example.sandbox.signicat.com/sign?sessionId=0197d5fb-d3ce-70c0-a420-68972e1c4d57",
    "lifecycle": {
      "state": "READY",
      "stateIsFinal": false
    }
  }
]

Store the session id and redirect the signer to the returned signatureUrl. The signer completes the signing flow using Samleikin.

User attributes (optional)

You may explicitly request some user attributes through signingSetup[].requestedAttributes.

User attributes and account defaults

By default, Sign API v2 automatically requests nin (P-tal) and dateOfBirth, and the signer's name and identity provider's name are always included. This means that you normally do not need to include requestedAttributes.

However, if your Signicat account has "minimal attributes" enabled, nin and dateOfBirth are not queried automatically. In this case, you must explicitly specify them in requestedAttributes (see below example).

If you want to explicitly request user attributes, include them in requestedAttributes as follows:

...
"signingSetup": [
      {
        "identityProviders": [
          {
            "idpName": "samleikin"
          }
        ],
        "signingFlow": "AUTHENTICATION_BASED",
        "requestedAttributes": ["name","firstName","lastName","nin","dateOfBirth"]
      }
    ]

Here is an example response where you can see the signer's user attributes in the output.userInfo section:

{
  "userInfo": {
    "fullName": "Petur Pól",
    "firstName": "Petur",
    "lastName": "Pól",
    "dateOfBirth": "1980-01-30",
    "nin": "320000008",
    "uniqueId": "320000008",
    "idpName": "samleikin",
    "signingTime": "2026-10-07T06:54:39.576Z"
  }
}

Here is an overview of the user attributes:

Signing result

PAdES packaging is asynchronous. Configure a webhook subscription for Packaging completed and Packaging failed, as described in the Get the result from the signing session section of our Sign API v2 integration guide. A success redirect alone does not indicate that the PAdES is ready.

After receiving package.completed, retrieve the session using GET https://api.signicat.com/sign/signing-sessions/{sessionId} with your bearer token.

The following example response shows the relevant result fields after successful signing and packaging:

{
  "id": "0197d5fb-d3ce-70c0-a420-68972e1c4d57",
  "lifecycle": {
    "state": "SIGNED",
    "stateIsFinal": true
  },
  "output": {
    "signatures": [
      {
        "resultDocumentId": "0197d623-1dae-7ea6-88f9-8474d83dbf97",
        "originalDocumentId": "0197d5cb-d683-7451-9b21-1a2da906b353",
        "signatureType": "XADES"
      }
    ],
    "packages": [
      {
        "packageId": "0154e96f-4ff8-448b-bd22-6401cfa13180",
        "resultDocumentId": "0197d623-2b90-75e5-be3b-138fe89dfe38",
        "packageType": "PADES_CONTAINER"
      }
    ]
  }
}

Find the entry in output.packages whose packageType is PADES_CONTAINER. Use its resultDocumentId to download the signed PDF with GET https://api.signicat.com/sign/documents/{resultDocumentId} and your bearer token. The identifier under output.signatures refers to the XAdES result.

Verify signature details in the PAdES

Use a completed test session to check the packaged signing evidence:

Download the PAdES document as described above and open it in a PDF reader that supports signature validation and embedded attachments.
Validate the PDF signature using the reader's signature panel. Authentication-based signing uses a signature created by Signicat. The signer's identity is recorded in the signing evidence.
Open the embedded evidence package from the reader's attachments panel and inspect the authentication metadata in the JSON/XML evidence. Check that the recorded identity provider is Samleikin and that the signer's identity and signing time correspond to the completed test session.
If DOB is required for your integration, check that the evidence contains the expected date of birth. If it is missing or incorrect, contact us by creating a support ticket in the Signicat Dashboard to confirm the Samleikin attribute availability and mapping before using the integration in production.

Limitations

DOB availability and mapping must be confirmed for integrations that depend on it. See Date of birth requirements for more information.
P-tal (nin) is only returned when your Dashboard account's configuration for Samleikin is set to the NATURAL_PERSON_WITH_PERSON_NO attribute set.
If you request PAdES packaging, use an unsigned PDF. A document that already contains a digital signature cannot be included in a PAdES package.
PAdES packaging must complete before you can retrieve the signed PDF.

Supported capabilities​

Prerequisites​

Date of birth requirements​

Signing setup​

Create a signing session​

Session response​

User attributes (optional)​

Signing result​

Verify signature details in the PAdES​

Limitations​