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 accounts

List 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 parameters

format if set to tree to get the account structure in tree format. Optional.

Response

A 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	type Product id of the account description Product name of the account availableTransactionsMonths Max age for transactions that can be fetched from this account, in months.
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".

Examples Request

curl 'https://premiumapi.handelsbanken.com/premium/premium-accounts/v1/ /accounts'
--key
--cert
-H ' Authorization: Bearer '
-H ' X-IBM-Client-Id: '

Response

{ "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"
  }
]}

Request

curl 'https://premiumapi.handelsbanken.com/premium/premium-accounts/v1/ /accounts?format=tree'
--key
--cert
-H ' Authorization: Bearer '
-H ' X-IBM-Client-Id: '

Response

{ "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.

Response

A JSON object that includes the same fields as in the account list Also includes:

balances	a list of balances. Each entry includes:
	balanceType type of balance. Is one of BOOKED, CLEARED, VALUE_DATE amount content the amount as a number currency An ISO4217 currency code of the balance

Examples Request

curl 'https://premiumapi.handelsbanken.com/premium/premium-accounts/v1/ /accounts/ ' \
--key \
--cert \
-H ' Authorization: Bearer ' \
-H ' X-IBM-Client-Id: '

Response

{
    "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.

Query parameters

dateFrom Start date of the transactions in ISO 8601 format. Mandatory.
dateTo End date of the transactions in ISO 8601 format. Mandatory.

Response

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

amount content The amount as a number currency An ISO4217 currency code of the balance balanceType One of BOOKED, PENDING bookingDate The booking date is the date when the transaction is booked on the account. The date is in ISO 8601 format remittanceInformation Text shows the reference given for the transaction. status One of BOOKED, PENDING valueDate The value date is the start date for interest calculation. The date is in ISO 8601 format

Examples Request

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: Currency One day More than one day SEK 2900 1000 Max 24 months of transactions are available. Other currency 2900 600 Max 13 months of transactions are available.