Signing
Start sign
The POST /v3/bankid-se/sign
endpoint is used to sign a text, document or other information using BankID (SE).
POST /v3/bankid-se/sign
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
{
"ssn": "YYYYMMDDXXXX",
"text": "abcdef",
"digest": "12345",
"ipAddress": "8.8.8.8",
"pinRequired": true,
"orgNumber": "559000-0948",
"callbackUrl": "https://...",
"refId": "12398698"
}
Parameter | Required | Description |
---|---|---|
ssn | No | A Swedish personal identification number to be used to complete the transaction. If a BankID with another personal number attempts to authenticate, it fails. |
text | Yes | The text to sign, will be displayed in the BankID app. |
digest | No | Hash digest for an associated file, if any. Gets sent to BankID as "userNonVisibleData". |
ipAddress | No | The IP-address of the end user, or as close to the end user as possible. |
pinRequired | No | Require users to sign using their PIN code, even if they have biometrics enabled. |
orgNumber | No | Organizational number, 11 digits. Used to perform checks for company signatory. To enable this feature, contact IDkollen. |
callbackUrl | No | Custom callback URL, must be whitelisted. See Callback. |
refId | No | Reference ID which will be included in a Collect and in the callback. |
IDkollen will respond with HTTP status 201 for successful request, or 4xx/5xx on errors. For more information about errors, please see the Errors section.
{
"id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
"refId": "12398698",
"status": "PENDING",
"autoStartToken": "6e8fdb9e-4cc7-42a7-9ce7-59947aeec6e6",
"qrStartToken": "8b9c387f-8948-4b53-b6a5-519eee985d44",
"qrStartSecret": "f47d75e0-6662-4bb9-9b09-ca37849ef1e0",
"hintCode": "started"
}
Property | Description |
---|---|
id | Authentication id, used to cancel or get the status of this sign request. |
refId | The refId given in the request, if any. |
autoStartToken | A token used to launch the BankID app on the same device. See https://www.bankid.com/utvecklare/guider/teknisk-integrationsguide/programstart |
qrStartToken | A token used, in combination with the qrStartSecret , to generate an animated QR code to sign using BankID on another device. See https://www.bankid.com/utvecklare/guider/teknisk-integrationsguide/qrkoder |
qrStartSecret | Used to animate the QR code. |
hintCode | A string (potentially null) that can be used to provide the user with instructions. See 'hintCode for pending orders' at https://www.bankid.com/utvecklare/guider/teknisk-integrationsguide/graenssnittsbeskrivning/collect |
Phone sign
The POST /v3/bankid-se/phone/sign
endpoint can be used to sign a document or other information using BankID when the user is talking to the user over the phone.
This method will trigger the users BankID app to start the sign using an SSN alone.
POST /v3/bankid-se/phone/sign
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
{
"ssn": "YYYYMMDDXXXX",
"callInitiator": "USER",
"text": "abcdef",
"digest": "12345",
"pinRequired": true,
"orgNumber": "559000-0948",
"callbackUrl": "https://...",
"refId": "12398698"
}
Parameter | Required | Description |
---|---|---|
ssn | Yes | The Swedish personal identification number of the user to sign. |
callInitiator | Yes | Can be one of: 'USER' or 'RP'. Indicates whether the user or the RP initiated the phone call. |
text | Yes | The text to sign, will be displayed in the BankID app. |
digest | No | Hash digest for an associated file, if any. Gets sent to BankID as "userNonVisibleData". |
pinRequired | No | Require users to sign using their PIN code, even if they have biometrics enabled. |
orgNumber | No | Organizational number, 11 digits. Used to perform checks for company signatory. To enable this feature, contact IDkollen. |
callbackUrl | No | See Callback. |
refId | No | Reference ID which will be returned with the status and included in the callback. |
IDkollen will respond with HTTP status 201 for successful request, or 4xx/5xx on errors. For more information about errors, please see the Errors section.
{
"id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
"refId": "12398698",
"status": "PENDING",
"hintCode": "started"
}
Property | Description |
---|---|
id | Authentication id, used to cancel or get the status of this sign request. |
refId | The refId given in the request, if any. |
hintCode | A string (potentially null) that can be used to provide the user with instructions. See 'hintCode for pending orders' at https://www.bankid.com/utvecklare/guider/teknisk-integrationsguide/graenssnittsbeskrivning/collect |
Fetch result
As an alternative to receiving a callback from IDkollen on successful or failed requests, you can use the
GET /v3/bankid-se/sign/{{id}}
endpoint to check the status of a sign request.
NOTE: This endpoint is rate limited to one request per second.
GET /v3/bankid-se/sign/{{id}}
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
This endpoint will respond with a HTTP status of 404
if the sign session has expired.
The status of a sign can be either one of: PENDING
, COMPLETED
or FAILED
.
Pending
{
"id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
"refId": "12398698",
"status": "PENDING",
"hintCode": "started"
}
Parameter | Description |
---|---|
refId | The refId given in the request, if any. |
hintCode | See the section hintCode for pending orders at https://www.bankid.com/utvecklare/guider/teknisk-integrationsguide/graenssnittsbeskrivning/collect. |
Completed
{
"id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
"refId": "12398698",
"status": "COMPLETED",
"ssn": "YYYYMMDDXXXX",
"name": "Firstname Lastname",
"givenName": "Firstname",
"surname": "Lastname",
"certStartDate": "2020-01-01",
"companySignatoryText": "X är företrädare för Y..."
}
Parameter | Description |
---|---|
refId | The refId given in the request, if any. |
ssn | A Swedish personal identification number to be used to complete the transaction. |
name | The full name of the authenticated user. |
givenName | The given name of the authenticated user. |
surname | The surname of the authenticated user. |
certStartDate | The date the BankID was issued to the user. |
companySignatoryText | A text describing whether the authenticated user is a signatory for the given organisation number. |
Failed
{
"id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
"refId": "12398698",
"status": "FAILED",
"error": "INVALID_ID"
}
Parameter | Description |
---|---|
refId | The refId given in the request, if any. |
error | An error code describing the reason for why the authentication failed. |
The error may be one of the following values:
Code | Description |
---|---|
AUTH_FAILED | A generic code for any kind of failure. |
CANCELLED | The authentication was cancelled either by the user or the partner. |
INVALID_ID | The ID has expired or is otherwise invalid. |
INTERNAL_ERROR | An internal error occurred causing the authentication to fail. |
SESSION_TIMEOUT | The authentication expired or timed out. |
UNSUPPORTED_CLIENT | The client used for the authentication is not supported. |
New error codes may be added in the future without prior notice. The partner should therefore handle unknown error codes in their implementations.
Cancel signing
The DELETE /v3/bankid-se/sign/{{id}}
endpoint is used to cancel an ongoing BankID signing.
DELETE /v3/bankid-se/sign/{{id}}
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
IDkollen will respond with HTTP status 204 for successful request, or 4xx/5xx on errors. For more information about errors, please see the Errors section.