This is a brief description of the API calls most commonly used by banks. For full details about the request and response payloads, se the swagger documentation.

The process

API

Swagger documentation for finding a settlement

For more detailed information about the api se redoc or swagger ui

• Redoc ui or Swagger UI for beta

• Redoc ui or Swagger UI for production

API documentation links below is using redoc ui for beta

Find settlement

There are multiple ways of querying the Settlement API for an existing settlement.

Bankintention(API)

Deciding whether to generate a digital or paper pantedokument (mortgage document)

A bank can send a notification of the desired registration method(PAPER or DIGITAL) to a broker to uncover the broker's desired registration method. The notification must contain the buyer's birth and social security number and the real estate object to be financed. The bank includes its own intention about the registration method in the report.

The broker will respond with intention with structured data about the property and the parties, the desired intention registration method(PAPER or DIGITAL), contact information and the broker reference.

Creating a bank intention

A bank intention is created by posting on the /eps/v1/bankintentions resource.

The response will contain a reference to a settlement, either from the broker (if immediate match is found) or a created proxy settlement. Immediate match happens if the broker settlement exists in EPS.

A positive broker response is always recognised by the event INTENTION_RESPONSE_RECEIVED with EventCode EPS_EV0001. See information about events and event codes (Code register). In addition, If the brokers settlement resides i EPS, the http return code is 201 (created), which mean the broker response is immediately ready. The http return code is 202 (accepted) means that the broker response is asynchronous and you will have to wait for the INTENTION_RESPONSE_RECEIVED event.

A negative broker response is recognised by the event INTENTION_RESPONSE_RECEIVED with EventCode EPS_EV0002. The the reasons for negative response is available in the event description.

After a positive response from the broker, it is transparent whether it is a proxy settlement or a broker settlement. The broker's intention and data is available through the settlement's unique reference. (The settlement unique reference is always a part of the response payload of a POST bankintention)
If the broker sends a change-of-intention, an INTENTION_CHANGED event is created. The new broker intention and maybe new data is available through the settlements unique reference.

If the bank changes its intention from PAPER to DIGITAL or from DIGITAL to PAPER, a new post on the /eps/v1/bankintentions resource will generate and send an change-of-intention message to the broker. The broker will not answer an change-of-intention message. A second post-invocation of the bankintentions will generate an change-of-intention message.

Rules:

The rules for bank intention, assuming positive response, are:

1. The first POST shall generate a bank intention of type IntentionFromBank.

2. If the bank reference is unchanged, in subsequent POST, the flow(DIGITAL/PAPER) must be changed compared to the previous. One exception, if no answer from broker is received.

3. If the bank reference has been changed in a subsequent POST, it will generate a bank intention of type IntentionFromBank.

4. If neither flow nor bank reference is changed compared to the previous, a bad request is sent.

If a bank intention did get a negative response or none at all, a bank intention POST will always generate a bank intention of type IntentionFromBank.

State diagram for bankintention

Intention from Bank on an existing broker settlement

I the settlement resides in EPS is is possible to POST a simple bank intention directly on the broker settlement. It is a more easy approach, but it is limited to settlements created in EPS.

The bank will search for a settlement, and provide an intention directly. The intention contains information whether the bank supports a digital flow or not.

Provide mortgage document(API) DEPRECATED

The document resource is used by the bank to upload mortgage documents. If a settlement was found in step two, the settlementuid should be given as a query parameter. The mortgage document will then be included in that settlement. For settlements not known to EPS, it is possible to give the broker’s organization number in the request body, and if EPS is not able to identify a settlement, the mortgage document will be uploaded to Afpant. This enable banks to collaborate with brokers even if the broker is not using Ambita’s services for electronic registration and settlement services.

For customers integrating etinglysing.no, this step is handled by “send to broker”.

Add attachment DEPRECATED

Attachments are documents that relate to a document resource. The resource has its own endpoint, but must be linked to the document.