Premium Account API
Available APIs
This service is for corporate customers wishing to obtain account information via Handelsbanken's Premium APIs. Communication is via a technical communications party (service provider) acting as the customer's representative with respect to Handelsbanken. In the agreement with Handelsbanken, the corporate customer specifies which service provider(s) are to gain access to the API service. By means of the service for Premium API account information, the service provider will have access to the corporate customer's accounts with Handelsbanken, including any related account information.
List accountsList accounts, including to get information about account structure
Get account information
Provide detailed account information
List account transactions
Get account transactions
API Description
Overall information
This section provides information that are common for all endpoints
Authorization
For use of API, a token must be fetched according to the instructions Here
Each request must contain these headers:
Authorization which should contain a bearer token with the BASE64-encoded JWT
X-IBM-Client-Id
this header contains the unique identifier of your application, that you get when you are onboarded to a Premium API.
List accounts
GET /premium/premium-accounts/v1/{orgNr}/accounts[?format=tree]
Path parameters
orgNr The organization number of the company.
Query parametersformat if set to tree to get the account structure in tree format. Optional.
ResponseA JSON object with the field "accounts", which is an array of objects with the following fields:
| Name | Description | ||||||
|---|---|---|---|---|---|---|---|
| accountId | Internal technical account identifier. Currently the same as BBAN. | ||||||
| iban | The IBAN (International Bank Account Number) | ||||||
| bban | The BBAN (Basic Bank Account Number). Same as accountId. | ||||||
| currency | Currency code of the account, according to ISO4217 | ||||||
| accountType |
|
||||||
| bic | The BIC associated to the account. A Handelsbanken BIC (Bank Identifier Code) is comprised of 8 characters.HANDSESS | ||||||
| clearingNumber | Handelsbanken branch identifier | ||||||
| name | Customer chosen name of the account, otherwise blank. | ||||||
| ownerName | Company name of the company that owns the account. Can be a subsidiary. | ||||||
| organisationNumber | Organization number of the company that owns the account. Can be a subsidiary. | ||||||
| accounts | Array of subaccount objects. Only used when the query parameter "format" is "tree". |
curl 'https://api3.handelsbanken.com/premium/v2/premium-accounts/5561286559/accounts'
--key
--cert
-H '
Authorization:
Bearer
-H '
X-IBM-Client-Id:
{
"accounts": [
{
"accountId": "961311234",
"accountType": {
"availableTransactionMonths": 24,
"description": "Underkonto 365 ind",
"type": 81
},
"bban": "961311234",
"bic": "HANDSESS",
"clearingNumber": "6765",
"currency": "SEK",
"iban": "SE4060000000000961311234",
"organisationNumber": "5560143041",
"ownerName": "Braxen Nickel Snövit TEST"
}
]}
curl 'https://api3.handelsbanken.com/premium/v2/premium-accounts/5561286559/accounts'
--key
--cert
-H '
Authorization:
Bearer
-H '
X-IBM-Client-Id:
{
"accounts": [{
"accountId": "962617911",
"accountType": {
"availableTransactionMonths": 24,
"description": "Huvudkonto PM",
"type": 62
},
"accounts": [
{
"accountId": "962624861",
"accountType": {
"availableTransactionMonths": 24,
"description": "Underkonto PM",
"type": 82
},
"bban": "962624861",
"bic": "HANDSESS",
"clearingNumber": "6293",
"currency": "SEK",
"iban": "SE3260000000000962624861",
"organisationNumber": "5560143041",
"ownerName": "APIS Huvudkonto UC3"
},
{
"accountId": "962625051",
"accountType": {
"availableTransactionMonths": 24,
"description": "Nivåkonto PM",
"type": 72
},
"accounts": [{
"accountId": "962625191",
"accountType": {
"availableTransactionMonths": 24,
"description": "Underkonto PM",
"type": 82
},
"bban": "962625191",
"bic": "HANDSESS",
"clearingNumber": "6293",
"currency": "SEK",
"iban": "SE4660000000000962625191",
"organisationNumber": "5560143041",
"ownerName": "APIS Huvudkonto UC3"
}]
"bban": "962625051",
"bic": "HANDSESS",
"clearingNumber": "6293",
"currency": "SEK",
"iban": "SE4360000000000962625051",
"organisationNumber": "5560143041",
"ownerName": "APIS Huvudkonto UC3"
}
],
"bban": "962617911",
"bic": "HANDSESS",
"clearingNumber": "62930",
"currency": "SEK",
"iban": "SE8460000000000962617911",
"organisationNumber": "5560143041",
"ownerName": "APIS Huvudkonto UC3"
}
]}
Get specific account
GET /premium/premium-accounts/{orgNr}/accounts/{accountId}
Path parameters
orgNr The organization number of the company.
accountId Currently the BBAN of the account.
Only accounts that are returned form the account list are available.
A JSON object that includes the same fields as in the account list Also includes:
| balances | a list of balances. Each entry includes: | ||||||||
|
curl 'https://api3.handelsbanken.com/premium/v2/premium-accounts/5561286559/accounts'
\
--key
--cert
-H '
Authorization:
Bearer
-H '
X-IBM-Client-Id:
{
"accountId": "98091234",
"accountType": {
"availableTransactionMonths": 13,
"description": "Huvudkonto valuta utan ränta",
"type": 9006
},
"bban": "98091234",
"bic": "HANDSESS",
"clearingNumber": "6103",
"currency": "CNY",
"iban": "SE6360000000000098091234",
"organisationNumber": "5560143041",
"ownerName": "Hedgehog Calcium Fuchsia TEST",
"balances": [{
"amount": {
"content": 2220007.93,
"currency": "CNY"
},
"balanceType": "AVAILABLE_AMOUNT"
},{
"amount": {
"content": 2220007.93,
"currency": "CNY"
},
"balanceType": "VALUE_DATE"
},{
"amount": {
"content": 2220007.93,
"currency": "CNY"
},
"balanceType": "CURRENT"
}
]
}
List transactions
GET /premium/premium-accounts/{orgNr}/accounts/{accountId}/transactions?dateFrom=&dateTo=
Path parameters
orgNr The organization number of the company.
accountId Currently the BBAN of the account.
Only accounts that are returned form the account list are available.
dateFrom Start date of the transactions in ISO 8601 format. Mandatory.
dateTo End date of the transactions in ISO 8601 format.
Mandatory.
200Sent complete transaction list.
206 Sent incomplete transaction list. Limitation applies to maximum number of transactions
The response consists of an object with the following fields:
| partialContent | true if we did not get all transactions because of transaction limits | ||||||||||||||||
| transactions |
|
Error codes
400 Invalid or missing organisation number Invalid account Invalid date format (dateFrom) Invalid date format (dateTo) Invalid date (future dateFrom) Invalid date (future dateTo) Invalid date (dateTo before dateFrom)
401 No access to organisation or it does not exist No customer agreement No access to account or it does not exist
403 KYC has expired
500 Internal server error Service is unavailable
Update times
Account list Up to 30 minutes delay.
Account balances Immediate
Transactions Immediate
Limits
Maximum number of transactions are: for accounts in SEK currency is 24 months back from today or at most 2 900 transactions. If no period is given then we will deliver the current month and 3 months back, but no more than 1000 transactions. If the date specified is one day, we will deliver a maximum of 2 900 transactions. If more than one day is specified, we will deliver a maximum of 1000 transactions.