High-level description

This document describes the services that the financial institutions should implement to provide the public agencies with account information. The services should be realised based on the REST architectural style and HTTP as a transport mechanism.

For a more detailed description of the eOppslag services, see “DSOP Kontrollinformasjon Arkitekturdokument”. Descriptions of other services are given in separate documents.

The services are defined so that they together or separately can support different use scenarios, such as:

  • Looking up account information with balance per person, both as account owner and third-party mandate.
  • Retrieving transaction history for a specific period.

The functional specification describes this in more detail.

Name Account
Functionality This API shall support 5 different operations:

- List of accounts for party
- Retrieve account details with balances
- Transaction history for account
- Cards linked to account
- Role holder on account
  Characteristics
Interface type REST API
Protocol HTTP
Transport HTTPS
State Stateless
Formats JSON (default)

Note: The API endpoints with examples are now in the Open API specification file.

General characteristics

API methods

The services should support lookup of information and, for that reason, only the HTTP method GET can be supported. The error message must be given if the request contains other HTTP operations, see “Error handling” below.

HTTP status code 200 should be given on successful calls.

Search by period

For information that changes over time, the general guideline is that the value at the end-time is given in the response. For searches where no period is specified, it means that the value at the time of the request should be given (e.g. balance).

Some values, such as address, account owner’s name, etc. may have changed over time without the bank having a log of the information. In those cases, the current value should be given in the response or, alternatively, the value at the end date if the customer no longer has an active customer relationship.

Data formats

All successful calls (200) should be given in JSON format and then encrypted according to JWE. Compact Serialization should be used (see other safety specification). Error messages should not be encrypted. Content type must be set for all responses, respectively, application/jose and application/json for successful and failed calls. In Test, it should be possible to get results unencrypted, by the client setting the Accept header (application/json). This function should not be available in production. Missing/empty values should be represented as is usual for the format, i.e. enter “null” for JSON.

Error handling

All errors that occur in relation to the service call, will follow the standard for HTTP status codes, but an error response should also be given. The error response should include an error code for machine handling, as well as a readable description of the error that has occurred. See list of HTTP status codes.

As a general rule, the 400 series is reserved for client errors that must be corrected before retrying, while the 500 series should be used for various technical errors at the service provider (e.g. database downtime, etc.). To handle technical errors that occur at the provider, the client may choose to have automatic retry mechanisms.

Error code overview

See the Open API specification for an overview of error codes for the different endpoints.

Logging

CorrelationID

In order to simplify troubleshooting for error situations, the service should support the logging of a common “correlation ID”. The users of the APIs have the responsibility of creating a unique identifier (GUID or similar) that follows the request end-to-end and is logged along the way. This is done by defining an Http header used for this purpose – CorrelationID.

Example correlationID

CorrelationID: 14fbc062-aacb-4449-93c1-85c352d387a4

AccountInfoRequestID

To make it possible to retrieve a (logical) request on a part, the service has to support logging of “AccountInfoRequestID”.

The purpose of the reference is that financial institutions should be able to prove that there was a valid legal basis to provide information to a specific public agency if, for example, there is a claim for compensation from someone who believes that the financial institution should not have provided the information.

One example of using “AccountInfoRequestID” is a scenario where a bank gets sued for providing confidencial information to the police. In this case, the bank would provide one (or more) “AccountInfoRequestID” to the police who received the account information of the customer who sued the bank. Based on this key, the police can retrieve from their archive, the grounds or evidence they had when they sent the request for the account information (for example a signature from a police lawyer).

“AccountInfoRequestID” will be created by the consumers according to the same pattern as used for “CorrelationID” (explained in the chapter above).

  • “AccountInfoRequestID” has to be the same for all API calls related to a request. Please note that it may also apply to several parts.
  • The same “AccountInfoRequestID” will be reused across several banks if the customer has a customer relationship with more than one bank during the requested period.
  • It should be possible for the consumer and the provider to locate an old case (or another reason for the request) based on this “AccountInfoRequestID”
  • The “AccountInfoRequestID” must be logged and stored for 13 years, in accordance to “Juridiske rammebetingelser”.

Example AccountInfoRequestID

AccountInfoRequestID: 14fbc062-aacb-4449-93c1-85c352d387a4

Versioning

The service should follow the principles of semantic versioning. The users of the APIs have responsibility for their clients’ continued functioning if changes are introduced, which are “non-breaking”, e.g. changing of the order or adding new fields (see also the Tolerant reader principles). Only MAJOR versions are included in the API URLs (i.e. v2, v3, etc.) and are introduced when the need arises. If several versions of the APIs occur and there also eventually is a need for the phasing out of older versions, their users must be given a reasonable amount of time to switch to the new version (e.g. 4 months). This will be specified further in the service agreements.

Mapping

All accounts that are or have been registered with the bank must be mapped into following 7 values:

  • loanAccount
  • salaryAccount
  • currencyAccount
  • savingsAccount
  • clientAccount
  • taxDeductionAccount
  • businessAccount

This applies to all accounts. The bank needs to map their accounts at their best ability and choose the value that is the most representative for each account.

Large result sets

The service must support the division of the response (pagination) if the request results in large result sets. This should be done through linking. The table below shows the code values to be used. Relative URLs should always be used. The goal should be that the number of items on each page is high enough to make the retrieval as efficient as possible. For transactions, a minimum of 1000 is desirable.

Code value  
next Next page in the result set. The absence of ‘next’ will be interpreted as this being the last page of the result set, and it should therefore be removed if this is the case.
self (Optional) Current page in the result set
prev (Optional) Previous page in the result set
last (Optional) Last page in the result set

Example linking

	"links": [{
		"rel": "self",
		"href": "/accounts/58758848484/transactions?fromDate=2018-01-01&toDate=2018-01-18"
	},
	{
		"rel": "next",
		"href": "/accounts/58758848484/transactions?fromDate=2018-01-01&toDate=2018-01-18"
	},
	{
		"rel": "last",
		"href": "/accounts/58758848484/transactions?fromDate=2018-01-01&toDate=2018-01-18"
	}]

Incomplete response

If the service provider cannot give a complete response because the information for the specified period is not available online*, the client must be made aware that more data exist. This is done through a separate element “responseStatus” in each response.

*Note: If the reason that a complete response cannot be provided is a service failure (eg, interruptions in one of the underlying systems), an error message should be provided as described in Error Handling (responseStatus = partial should therefore not be used in such situations).

Change log

Date Change Link in document
02.03.20 Added clarification about mapping of accounts Mapping
02.02.20 Updated AccountInfoRequestID AccountInfoRequestID
02.01.20 Added AccountInfoRequestID AccountInfoRequestID