Sign API v2 for Swedish BankID Phone
This section details how to integrate with the Swedish BankID Signing implementation using the Sign API v2.
Signing is currently only available for the BankID Phone feature.
Prerequisites
- Follow the steps on the Initial preparations page to establish a connection with Swedish BankID.
-
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.
To learn more about the Signicat Sign API v2, see:
- Sign API v2 for conceptual documentation.
- API Reference for endpoint descriptions.
Using the API
A basic signature process with Swedish BankID consist of the following steps:
- Upload a document.
- Create a document collection.
- Create a signing session.
- Redirect the end-user to the signature application.
- Get the result from the signing session.
- Download the signed document.
1. Upload a 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 can either be a plain text document or a PDF.
The BankID Phone feature only supports signing plain text documents (not PDFs).
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). Valid values are:
text/plaintext/markdown
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 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.
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 uploadDocument response.
This will create a document collection with the document you uploaded (in the Upload a document step).
Response
The response contains an id representing the document collection:
{
"id": "0197e4b8-ac22-7a2e-ba32-2515e67b05fa",
"documents": [
{
"documentId": "0197e4b8-6a73-75e1-9661-30bf53af8752"
}
],
"output": {
"packages": []
}
}
3. Create a signing session
In this step, you initiate a process where a signer can electronically sign one or more documents through the BankID app. 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.
Request
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.
Here is a request example for the BankID Phone feature:
[
{
"title": "Test signing with SBID",
"signText": "Please sign this document",
"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",
"additionalParameters": {
"sbid_sign_type": "PHONE",
}
}
],
"signer": {
"nationalIdentificationNumber": "199002171234",
"validations": [
"NATIONAL_IDENTIFICATION_NUMBER"
]
},
},
"ui": {
"language": "en"
},
"redirectSettings": {
"error": "http://example.com/error",
"cancel": "http://example.com/cancel",
"success": "http://example.com/complete"
}
}
]
- Language settings: Valid language values are
enandsv. - Validations: If you do not want to enforce that a specific user signs the document, you can omit the
validationsfield. You can still keep thenationalIdentificationNumberfield, so that the support agent does not have to enter the identification number manually in the UI.
For more details about the BankID specific fields, see signingSetup, additionalParameters and prefilledInput in the following sub-sections.
For details about other fields, see the general Sign API v2 integration guide.
signingSetup
To set up a signing session with BankID, use the following signingSetup fields:
additionalParameters
You use additionalParameters to specify available BankID flows and features, for example BankID Phone.
prefilledInput
For the BankID Phone feature, you can use the prefilledInput parameter to prefill the national identity number of the end-user, for example:
"signer": {
"nationalIdentificationNumber": "199002171234"
}
If you prefill the users national identity number and pass in a value in the sbid_phone_initiator additional parameter, it will automatically start the transaction.
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.
Here is a response example, including the link to the signing interface in the signatureUrl:
[
{
"id": "0197e4d7-7857-7246-9e6a-091606fada2f",
"signatureUrl": "https://test-domain.sandbox.signicat.dev/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": "0197e4d7-56ce-7fa0-bee4-18d1847f915a",
"action": "SIGN",
"documentId": "0197e4d7-39a4-745d-9d02-a6f87d778264"
}
],
"lifecycle": {
"state": "READY",
"stateIsFinal": false
},
"senderDisplayName": "Example Company Ltd",
"output": {
"signatures": [],
"packages": []
},
"externalReference": "someTestExternalReference",
"signingSetup": [
{
"vendor": "SBID",
"signingFlow": "PKISIGNING",
"additionalParameters": {
"sbid_sign_type": "PHONE",
}
}
],
"subsequentTo": [],
"signer": {
"nationalIdentificationNumber": "199002171234",
"validations": [
"NATIONAL_IDENTIFICATION_NUMBER"
]
},
"ui": {
"language": "en"
},
"redirectSettings": {
"error": "http://example.com/error",
"cancel": "http://example.com/cancel",
"success": "http://example.com/complete"
}
}
]
READY means the end-user has not completed the signing, hence the signatures field is empty.
4. Redirect the end-user to the signature application
Once you have created the signing session and received the response, you can redirect the end-user to the signatureUrl provided in the response. This URL will take them to the signing interface (BankID app) where they can complete (or cancel) the signing process.
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 nin is prefilled).
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).
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. Get 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.
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 createSigningSession 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": "01989d42-bf3f-71eb-b66f-7580d7809235",
"signatureUrl": "https://test-domain.sandbox.signicat.dev/sign?sessionId=01989d42-bf3f-71eb-b66f-7580d7809235",
"title": "Test signing with SBID",
"signText": "Please sign this document",
"dueDate": "2025-09-11T07:50:53.59749Z",
"documents": [
{
"documentCollectionId": "01989d41-61bf-7ba1-b569-6e245a1ae23e",
"action": "SIGN",
"documentId": "01989d41-3180-7b7d-bc38-ada25e827281"
}
],
"lifecycle": {
"state": "SIGNED",
"stateIsFinal": true
},
"senderDisplayName": "Example Company Ltd",
"output": {
"signatures": [
{
"resultDocumentId": "0198ebc7-9c6b-7701-9be6-6bfa1bf39915",
"originalDocumentId": "01989d41-3180-7b7d-bc38-ada25e827281",
"signatureType": "XADES"
}
],
},
"externalReference": "someTestExternalReference",
"signingSetup": [
{
"vendor": "SBID",
"signingFlow": "PKISIGNING",
"additionalParameters": {
"sbid_sign_type": "PHONE",
}
}
],
"subsequentTo": [],
},
"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.