This page is for banks that will start the collaboration with the broker by requesting the purchase contract data.

...

The http status code of the response will determine the flow:

• 201 : The intention data matches a settlement in Ambita and the response is readyrequest matches one or more settlements at Ambita and the result is included in the response body.

• 202 : The intention request is sent to the (non-Ambita) broker and an event (INTENTIONPURCHASE_RESPONSECONTRACT_RECEIVEDCHANGED) will be generated when the response is ready.

• 400 : Bad request. Either the data in the request is invalid or the intention data didn’t match any settlements. Se below for error description.

Both 201 and 202 status codes will have a property in the payload containing a field named uniqueIdentifier requestUid identifying your intentionrequest. The intention response of the request can be retrieved later by performing a GET /eps/v1/bankintentionspurchasecontractrequests/<uniqueIdentifier><requestUid>. The response will also have a field named settlementUniqueIdentifier. This is the unique identifier of a settlement that you must keep for later retrieval of data. Also all events will reference a settlement (NOTE: if requesting a purchase contract, some new events will not have this settlement identifier)an array of references to the settlements that has enough information to be converted to a purchase contract. This array can be empty. In addition the response will have the status and a boolean field existsSettlementsNotReady indicating if there exists any settlements that cannot yet be converted to a purchase contract.

Handling 201 status code

A status code of 201 is return when the intention data matches a request matches one or more settlement for an Ambita broker. Since we already have the settlement data, a synchronous response is given. The broker’s intended registration method can be found in the response body in the field flowCapability and the possible values are "PAPER" or "DIGITAL". In the future a third value for Not determined yet can be added.

Now the broker knows the bank’s intention and the bank knows the broker’s intention. Again. both parties must agree on DIGITAL for it to be a digital process.

Also keep in mind that the intention can be changed later on in the process. The bank does this by again sending a bankintention but with the new flowCapability. The bank is notified by reading events and receiving an INTENTION_CHANGED event referencing the settlement unique identifier.list of contracts can have zero or more elements, each having:

• a settlement unique identifier

• The broker’s reference

• A link to fetch the settlement/contract data

• A link to get a PDF rendering of the contract data

• A link to fetch the signed purchase contract as PDF

• Address of the real estate in question

See the online API documentation for detailed information: https://beta-api.ambita.com/eps/#tag/Purchase-Contract/operation/createRequest

Handling 202 status code

Receiving a 202 means that EPS has sent the intention request asynchronously to the broker. The bank receives an immediately response containing the settlement request’s unique identifier for later reference and data retrieval. Nothing is known about When the broker’s intention before a response is received later on and an event (INTENTIONPURCHASE_CONTRACT_RESPONSE_RECEIVED) is generated referencing this settlement. The data returned in the immediate response is the bank’s data from the intention until a successful match is done and the settlement is updated with some more data from the brokerrequest.

A status of ACCEPTED means that the request was accepted by the broker and matched one or more settlements. However, the contracts array may be empty. The property existsSettlementsNotReady will indicate if there are additional matching settlements which are not yet ready to be converted into a purchase contract.

Handling 400 status code (bad request)

A bad request signals a failed validation of the input data or, in case of an Ambita broker, the intention didn’t match any settlements. The error object returned in EPS all contains a field message that we work hard on being human understandable. In case of a bad request, this message should be presented to the person in the bank handling the case as either the input must be changed or the broker must be contacted to find out what went wrong.

States and codes

A bank intention purchase contract request can have the following states.

Note that for external brokers, the event INTENTION_RESPONSE_RECEIVED has a human understandable explanation in the event.description field that should be presented to the person in the bank handling the case. Only intentions that are accepted by a broker will receive updates if the flow changed. If an intention is rejected, the bank must send a new intention to the broker after agreeing with the broker what the correct data is.

Listening for events

A few more status codes will become available as the whole lifecycle of a request is implemented.

Listening for events

It is essential that the bank has a kind of scheduled batch job that fetches the latest list of events, processes them and takes action on relevant events like INTENTIONPURCHASE_CONTRACT_RESPONSE_RECEIVED and INTENTIONPURCHASE_CONTRACT_CHANGED. Unknown or uninteresting events can be ignored.

Note that the event PURCHASE_CONTRACT_RESPONSE_RECEIVED is the first event that does not have a reference to a settlement (settlementuid). Not having a settlement uid would be a braking change for the /events endpoint. In order for the bank to receive this event type, a new request parameter is required (then we know that the bank can handle null in this property). GET /eps/v1/events?contractevents=true.

Relevant event types are described here: Events for banks.

More information about how to listen to events can be found here: Monitoring settlements

Setting the intention the easy way

When the bank has requested a purchase contract and successfully received a contract in response, the settlement (unique identifier) is a handle to the broker’s data/settlement. Having this handle, setting the bank’s desired registration method i easy using the new endpoint /eps/v1/purchasecontractrequests/{requestuid}/{settlementuid}/intention/ and only add the desired flow (digital or paper). Se OAS documentation for details.

Requesting purchase contract data several times

DSVE has defined a set of properties that are required in order to create a purchase contract. It’s therefore possible to match the request with a settlement, but still not being able to create a purchase contract. The bank can then request the data again at a later point in time by just sending another POST request to the same endpoint. When requesting purchase contract data again, the following rules apply:

• All previous requests to the same broker using the same (bank) reference will change status to OUTDATED, no further events will be generated for that request and related data such as local (bank) settlements will be cleared.

• All previous requests to the same broker having a different (bank) reference will be kept alive and the bank will now receive events on both requests.

It is important that the bank’s refernce identifies a specific case in the bank’s system and is not a transaction/correlationId that will change for each request.

The broker doesn’t support purchase contract requests

As purchase contract data request is a rather new message type, it will take some time before all collaborating parties support this message. If the broker in question does not support purchase contract requests, the bank should skip this step and start collaboration by sending a bank intention, se Collaboration starting with bank intention .

See a PDF of the purchase contract data

As an alternative for the bank to fetch and present JSon in the bank system, we offer a PDF rendering of the data as PDF. The PDF is generated using the official XSLT as defined by the DSVE project. For a given settlement/contract related to a purchase contract request, you can get the PDF by using the endpoint https://beta-api.ambita.com/eps/#tag/Purchase-Contract/operation/getPurchaseContractPdf. This is a PDF rendering of the contract data, this is not a copy of the signed purchase contract.

Getting the signed purchase contract

If the signed purchase contract is available (as a PDF) you will find the link to it in the array of contracts as a property named signedPurchaseContractLink. If a signed purchase contract is added (for the first time) or updated (new version), the event PURCHASE_CONTRACT_CHANGED. will be generated and the property settlementChanges will contain the category SIGNED_PURCHASE_CONTRACT.

Generating pantedokument (digital registration process)

...