For the complete documentation index, see llms.txt. You can also append .md to any page URL to get its markdown version.
Skip to main content
For the complete documentation index, see llms.txt.

For the complete documentation index, see llms.txt

Sign API v2 for Swedish BankID

This section details how to integrate with Swedish BankID Signing using the Sign API v2 PKISIGNING flow.

With this integration, one or more users can sign single or multiple documents with Swedish BankID.

Prerequisites​

  1. Enable signing with Swedish BankID in the Dashboard:
    1. Navigate to Configuration > Sign methods in the left-hand menu.
    2. Click the Add method button. You can find this button in the middle of the page or in the top-right corner.
    3. In the list of available sign methods, locate Swedish BankID and click the plus (+) icon on the right-hand side of the row.
    4. A side panel will appear with a description of the Swedish BankID method. Click the Add button at the bottom of this panel.
    5. Swedish BankID will now be added to your list of configured sign methods for PKI signing. In the Sign API v2, this is referred to as the vendor. This is different from the IdP (Identity Provider) used for authentication-based signing.
    To disable or remove the method later
    1. Click on the row for Swedish BankID in your list of configured sign methods.
    2. From the new UI that appears, you can either disable or remove the method.

  2. For the complete documentation index, see llms.txt

    Before you can start making requests to this API, you need to learn how to connect to it. To do this, follow steps 1-3 in the Connect to Signicat APIs Quick start guide.
Want to learn more?

To learn more about the Signicat Sign API v2, see:

Step overview​

A basic signature process with Swedish BankID consist of the following steps:

  1. Upload a new document.
  2. Create a document collection.
  3. Create a signing session.
  4. Redirect the end-user to the signature application.
  5. Get the result from the signing session.
  6. Download the signed document.

1. Upload a new document​

The initial step in the electronic signing process is to upload one or more documents to be signed by one or more end-users.

The uploaded document(s) can be in the following formats:

  • text/plain
  • text/markdown
  • application/pdf

For more details about supported document formats, see the About page.

Request​

To upload a document, make an HTTP POST request to the /documents endpoint.

You can specify the format of the document in the Content-Type header when uploading the document (POST to /documents).

When specifying text/plain or text/markdown as the mimeType, the document will be displayed in the BankID app only. Specifying application/pdf, the document will be displayed in Signicat's signing UI. See also the overview of the supported documentation formats on the About page.

Read more about BankID text formatting

BankID supports simple markdown format (simpleMarkdownV1). For more information, see BankID's documentation about formatting, Syntax, special characters and rendering and Test your text.

Response​

The "Upload a new document" response shows the document type, here a plain text document, and a documentId for the uploaded document:

{
    "mimeType": "text/plain",
    "documentId": "0197e4b8-6a73-75e1-9661-30bf53af8752",
    "createdAt": "2025-07-07T10:31:26.355228387Z",
    "documentHash": {
        "hash": "zjFmFoXWpL0F6K8Vl4qXGZBXEsIywg8MVowxRj3RYxE=",
        "hashAlgorithm": "SHA256"
    }
}

2. Create a document collection​

The uploaded documents must always be inside a collection, even if you only have one document to sign.

What is a document collection?

See the general Sign API v2 integration guide.

Request​

To create a document collection, make an HTTP POST request to the /document-collections endpoint.

Ensure you use the documentId that you received in the Upload a document response.

This will create a document collection with the document you uploaded in the previous section.

Response​

The response contains an id representing the document collection:

{
    "id": "0197e4b8-ac22-7a2e-ba32-2515e67b05fa",
    "documents": [
        {
            "documentId": "0197e4b8-6a73-75e1-9661-30bf53af8752"
        }
    ],
    "packageTo": [],
    "output": {
        "packages": []
    }
}

3. Create a signing session​

In this step, you initiate a process where a signer can electronically sign one or more documents. This involves creating a signing session that defines which documents are to be signed, who the signer is, and the settings for the signing process.

To create a signing session, make an HTTP POST request to the /signing-sessions endpoint.

Ensure you use the documentId for the uploaded document and the document collection id from the response in the previous section.

Request​

Here is a full request example of signing with BankID (see the next sections for more details). The signingSetup object is highlighted as it specifies the vendor as SBID and includes BankID-specific configurations in additionalParameters.

[
    {
        "title": "Test signing with SBID",
        "signText": "Please sign this document",
        "dueDate": "2025-08-06T12:23:35.455010295Z",
        "sealTo": [
            "XADES_CONTAINER"
        ],
        "documents": [
            {
                "documentCollectionId": "0197e4b8-ac22-7a2e-ba32-2515e67b05fa",
                "action": "SIGN",
                "documentId": "0197e4b8-6a73-75e1-9661-30bf53af8752"
            }
        ],
        "senderDisplayName": "Example Company Ltd",
        "externalReference": "someTestExternalReference",
        "signingSetup": [
            {
                "vendor": "SBID",
                "signingFlow": "PKISIGNING",
                "requestedAttributes": ["sbidSubjectDn", "risk"],
                "additionalParameters": {
                    "sbid_sign_type": "NORMAL"
                }
            }
        ],
        "packageTo": [],
        "signer": {
            "nationalIdentificationNumber": "199002171234",
            "validations": [
                "NATIONAL_IDENTIFICATION_NUMBER"
            ]
        },
        "preAuthentication": {
            "enabled": false
        },
        "ui": {
            "language": "en"
        },
        "redirectSettings": {
            "error": "http://example.com/error",
            "cancel": "http://example.com/cancel",
            "success": "http://example.com/success"
        }
    }
]

signingSetup​

To set up a signing session with Swedish BankID, use the following signingSetup fields:

additionalParameters​

You use additionalParameters to specify available BankID flows and features, for example BankID Phone.

language​

Valid language values are:

  • sv (Swedish)
  • en (English)

validations​

If you want a specific user to sign the document, you can add information about the signer. This ensures that the correct person signs the document.

You then set validations to NATIONAL_IDENTIFICATION_NUMBER.

If you do not want to enforce that a specific user signs the document, you can omit the validations field.

Response​

Once the signing session is created, the signer receives a link to access the signing interface, review the documents, and provide their electronic signature.

The response for this call contains the signatureUrl, which is the link you must redirect the signer to (see the next section for more details about the redirect). The example below is condensed to show this key field and the state of the session:

[
    {
        "signatureUrl": "https://example.sandbox.signicat.com/sign?sessionId=0197e4d7-7857-7246-9e6a-091606fada2f",
        "lifecycle": {
            "state": "READY"
        },
        "senderDisplayName": "Example Company Ltd"
    }
]
Click to expand full JSON response
[
    {
        "id": "0197e4d7-7857-7246-9e6a-091606fada2f",
        "signatureUrl": "https://example.sandbox.signicat.com/sign?sessionId=0197e4d7-7857-7246-9e6a-091606fada2f",
        "title": "Test signing with SBID",
        "signText": "Please sign this document",
        "dueDate": "2025-08-06T12:23:35.455010295Z",
        "documents": [
            {
                "documentCollectionId": "0197e4b8-ac22-7a2e-ba32-2515e67b05fa",
                "action": "SIGN",
                "documentId": "0197e4b8-6a73-75e1-9661-30bf53af8752"
            }
        ],
        "preAuthentication": {
            "enabled": false
        },
        "lifecycle": {
            "state": "READY",
            "stateIsFinal": false
        },
        "senderDisplayName": "Example Company Ltd",
        "output": {
            "signatures": [],
            "packages": [],
            "userInfo": {
                "extra": {}
            }
        },
        "externalReference": "someTestExternalReference",
        "signingSetup": [
            {
                "vendor": "SBID",
                "identityProviders": [],
                "signingFlow": "PKISIGNING",
                "additionalParameters": {
                    "sbid_sign_type": "NORMAL"
                },
                "requestedAttributes": [
                    "sbidSubjectDn",
                    "risk"
                ]
            }
        ],
        "subsequentTo": [],
        "packageTo": [],
        "sealTo": [
            "XADES_CONTAINER"
        ],
        "signer": {
            "nationalIdentificationNumber": "199002171234",
            "prefill": [],
            "validations": [
                "NATIONAL_IDENTIFICATION_NUMBER"
            ],
            "restrictUse": []
        },
        "archive": {
            "sendSignatureResultsToArchive": false,
            "sendPackagingResultToArchive": false,
            "archiveTags": []
        },
        "preAuthentication": {
            "enabled": false
        },
        "ui": {
            "language": "en",
            "hideWelcomeScreen": false,
            "minimalTextMode": false
        },
        "redirectSettings": {
            "error": "http://example.com/error",
            "cancel": "http://example.com/cancel",
            "success": "http://example.com/complete"
        }
    }
]
READY state

READY means the end-user has not completed the signing, hence the signatures field is empty.

For more field descriptions, see the Sign API Reference.

4. Redirect the end-user to the signature application​

Once you have created the signing session and received the response, you redirect the end-user to the signatureUrl provided in the response. This URL will take them to the signing interface where they can complete (or cancel) the signing process.

You then wait for the user to complete the signing and return to your application. After completion, you can retrieve the signed documents (see the next sections).

Phone specifics
  • Additional screen: When using the Phone feature, an additional screen is shown before the signing interface. In this screen (see example on the About page), the support agent must enter the personal identification number of the customer (unless it has been prefilled using the nationalIdentificationNumber).
  • Cancellation behaviour: Currently, when an end-user cancels the signing session in the BankID Phone flow, the session state does not change in the API. Cancellation currently behaves more like a postpone action. This means that the session remains in the READY state and can be resumed later.

5. Retrieve the result from the signing session​

When the signing session is finalised, meaning the state is either SIGNED, or REJECTED, you can retrieve the result from the signing session.

This process happens synchronously, so the result is available as soon as the signing process has been completed.

Request​

To get the result from the signing session, make an HTTP GET request to the /signing sessions/{sessionId} endpoint, using the session ID you received in the "Create a new signing session" response.

Response​

The response will contain the information requested in the "Create a signing session" call that was done earlier. It will contain updated information regarding the status of the process, as well as the relevant document identifiers.

Below you can see an example response for a successfully completed session:

{
    "id": "0197e4d7-7857-7246-9e6a-091606fada2f",
    "signatureUrl": "https://example.sandbox.signicat.com/sign?sessionId=0197e4d7-7857-7246-9e6a-091606fada2f",
    "title": "Test signing with SBID",
    "signText": "Please sign this document",
    "dueDate": "2025-08-06T12:23:35.455010295Z",
    "documents": [
        {
            "documentCollectionId": "0197e4b8-ac22-7a2e-ba32-2515e67b05fa",
            "action": "SIGN",
            "documentId": "0197e4b8-6a73-75e1-9661-30bf53af8752"
        }
    ],
    "lifecycle": {
        "state": "SIGNED",
        "stateIsFinal": true
    },
    "senderDisplayName": "Example Company Ltd",
    "output": {
        "signatures": [
            {
                "resultDocumentId": "0198f4a2-1b3c-7a8d-8e9f-1a2b3c4d5e6f",
                "originalDocumentId": "0197e4b8-6a73-75e1-9661-30bf53af8752",
                "signatureType": "XADES"
            }
        ],
        "packages": [],
        "seals": [
            {
                "sealId": "019eb55d-9068-7ab2-a034-4343c785bdcc",
                "resultDocumentId": "0198f4a2-1b3c-7a8d-8e9f-1a2b3c4d5e6f",
                "originalDocumentId": "0197e4b8-6a73-75e1-9661-30bf53af8752",
                "packageType": "XADES_CONTAINER"
            }
        ]
    },
    "externalReference": "someTestExternalReference",
    "signingSetup": [
        {
            "vendor": "SBID",
            "signingFlow": "PKISIGNING",
            "additionalParameters": {
                "sbid_sign_type": "NORMAL"
            }
        }
    ],
    "subsequentTo": [],
    "packageTo": [],
    "sealTo": [
            "XADES_CONTAINER"
        ],
    "ui": {
        "language": "en"
    },
    "redirectSettings": {
        "error": "http://example.com/error",
        "cancel": "http://example.com/cancel",
        "success": "http://example.com/success"
    }
}

6. Download the signed document​

To download the signed document, make an HTTP GET request to the /documents/{documentId} endpoint of the API using the result document ID you obtained in the previous step.

Response​

The response contains the content of the signed document. For BankID, the signature document type will be a signed XML document (XADES).

API reference​

Explore our Sign API v2 reference documentation to look up all API endpoints and properties as well as view sample requests and responses.

Sign API v2 API reference
Regulatory compliant electronic signatures
On this page