Alma logo
API docs by Redocly

Offer API (1.0)

Download OpenAPI specification:Download

Introduction

Offer API allows an agent to manage purchase offers and counter offers for realties. Offers are divided into different types:

  • Purchase offer - An offer to purchase a realty. Offer is provided by the prospective buyer.
  • Counter offer - A counter offer to a previous offer. The counter offer can be provided by the seller or the prospective buyer.

Counter offer is a sub-resource to purchase offer. Together they form an offer chain.

Offers and counter offers

A purchase offer can be a starting point for a number of counter offers. The following diagram shows an example of a purchase offer chain with two counter offers and possible replies to the offers.

Contact

If you have any questions, comments or feedback regarding our APIs, please contact developer@ovipro.fi.

Purchase Offer

Purchase Offer API allows you to create, update and fetch purchase offers.

Create a purchase offer

Create a new purchase offer.

Authorizations:
bearerAuth
header Parameters
Request-ID
required
string <uuid>
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

A unique id which identifies the HTTP request. The value of this header must be created by the client. This identifier is used for troubleshooting purposes.

Request Body schema: application/json
required

Contains the details for the purchase offer.

assignmentId
string <uuid> (AssignmentId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

Unique identifier for the assignment in the UUID format.

required
object (PurchaseOffer)

Contains the buyer-specific conditions for the offer.

required
object (OfferValidity)

Contains details about offer validity. Note that the end date also includes the time.

required
Array of objects (BuyerPartyForOffer) non-empty

Specifies the buyer customers which are associated with this offer.

required
Array of objects (SellerPartyForOffer) non-empty

Specifies the seller customers which are associated with this offer. If the offer has a sales assignment, the seller parties must be picked from the assignment.

required
Array of objects (Assets) non-empty

Assets to be included in this offer. An offer typically includes one asset. However, there are situations when an offer may include several assets:

  • Apartments in new buildings can be sold through one offer.
  • A residential share and one or more parking slots can be included in the same offer.
required
Array of objects (Attachments)

Specifies the documents which the offerer has examined.

If the document was delivered directly from Ovi PRO, the documentId field identifies the document in Ovi PRO.

Responses

Request samples

Content type
application/json
{
  • "assignmentId": "d265a413-a83e-40f1-b185-a3b1fb74c905",
  • "purchaseOffer": {
    },
  • "offerValidity": {
    },
  • "buyerCustomerParties": [
    ],
  • "sellerCustomerParties": [
    ],
  • "assets": [
    ],
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "offerId": "7266e36e-5e9b-40f3-9965-297f7ed10218"
}

Fetch purchase offers

Fetch purchase offers by using different search criteria. You can combine the search criteria, for example to search for active purchase offers for a specified agency office.

Authorizations:
bearerAuth
query Parameters
offerStatusCode
Array of strings (OfferStatusCode)
Items Enum: "DRAFT" "READY_FOR_SIGNING" "ACTIVE" "ACCEPTED" "REJECTED" "EXPIRED" "COUNTER_OFFERED"
Example: offerStatusCode=ACTIVE

Search by the offer status code to fetch offers having specific statuses.

offerChainStatusCode
Array of strings (OfferChainStatusCode)
Items Enum: "DRAFT" "ACTIVE" "ACCEPTED" "REJECTED" "EXPIRED"
Example: offerChainStatusCode=ACTIVE

Search by the offer chain status code to fetch offers having specific offer chain statuses.

realtyId
string <uuid> (RealtyId)
Example: realtyId=9fd9124c-e6c1-4368-9f17-6938f0e2f524

Search by the realty identifier to get a list of offers that belong to certain realty.

assignmentId
string <uuid> (AssignmentId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: assignmentId=9238cf7b-b86a-49a5-b54f-cbdfcd03e9c9

Search by the assignment identifier to fetch the continuation agreements for this assignment.

modifiedAfter
string <date-time> (Timestamp)
Example: modifiedAfter=2021-09-21T17:32:28Z

Search by the modification time to get a list of offers that were modified after given timestamp.

startIndex
integer <int32> >= 0
Default: 0
Example: startIndex=20

Paginate returned offers starting from this index. Index starts from 0.

size
integer <int32> [ 1 .. 50 ]
Default: 25
Example: size=25

Offers returned per page.

sort
Array of strings
Example: sort=validAfter|desc

Sort offers based on the specified fields. Each fields must also include a sort order as follows:

sort={fieldName}|{asc|desc}&sort={anotherFieldName}|{asc|desc}

header Parameters
Request-ID
required
string <uuid>
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

A unique id which identifies the HTTP request. The value of this header must be created by the client. This identifier is used for troubleshooting purposes.

Responses

Response samples

Content type
application/json
{
  • "totalCount": 1,
  • "purchaseOffers": [
    ]
}

Fetch a purchase offer

Fetch details for the specified purchase offer.

Authorizations:
bearerAuth
path Parameters
offerId
required
string <uuid>
Example: ddc25849-7bc7-43c0-9c3b-602cb03f7806

Unique offer identifier in UUID format.

header Parameters
Request-ID
required
string <uuid>
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

A unique id which identifies the HTTP request. The value of this header must be created by the client. This identifier is used for troubleshooting purposes.

Responses

Response samples

Content type
application/json
{
  • "offerId": "d1b0fc64-e6ab-4889-bfd7-861edc8d4356",
  • "assignmentId": "e1050cdc-34a7-435b-b940-1d3442a34f2f",
  • "offerStatusCode": "COUNTER_OFFERED",
  • "offerChainStatusCode": "ACTIVE",
  • "offerTypeCode": "PURCHASE_OFFER",
  • "purchaseOffer": {
    },
  • "offerValidity": {
    },
  • "buyerCustomerParties": [
    ],
  • "sellerCustomerParties": [
    ],
  • "assets": [
    ],
  • "documents": {
    },
  • "counterOffers": [
    ],
  • "attachments": [
    ],
  • "replyTime": "2021-08-13T13:07:23Z",
  • "creationTime": "2023-05-08T12:35:45.793Z",
  • "modificationTime": "2023-05-08T12:35:45.793Z"
}

Update a purchase offer

Update a purchase offer.

Authorizations:
bearerAuth
path Parameters
offerId
required
string <uuid>
Example: ddc25849-7bc7-43c0-9c3b-602cb03f7806

Unique offer identifier in UUID format.

header Parameters
Request-ID
required
string <uuid>
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

A unique id which identifies the HTTP request. The value of this header must be created by the client. This identifier is used for troubleshooting purposes.

Request Body schema: application/json
required

Contains the details for the purchase offer.

offerId
required
string <uuid> (OfferId)

Unique identifier for the offer in the UUID format.

assignmentId
string <uuid> (AssignmentId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

Unique identifier for the assignment in the UUID format.

required
object (PurchaseOffer)

Contains the buyer-specific conditions for the offer.

required
object (OfferValidity)

Contains details about offer validity. Note that the end date also includes the time.

required
Array of objects (BuyerPartyForOffer) non-empty

Specifies the buyer customers which are associated with this offer.

required
Array of objects (SellerPartyForOffer) non-empty

Specifies the seller customers which are associated with this offer. If the offer has a sales assignment, the seller parties must be picked from the assignment.

required
Array of objects (Assets) non-empty

Assets to be included in this offer. An offer typically includes one asset. However, there are situations when an offer may include several assets:

  • Apartments in new buildings can be sold through one offer.
  • A residential share and one or more parking slots can be included in the same offer.
required
Array of objects (Attachments)

Specifies the documents which the offerer has examined.

If the document was delivered directly from Ovi PRO, the documentId field identifies the document in Ovi PRO.

Responses

Request samples

Content type
application/json
{
  • "offerId": "7266e36e-5e9b-40f3-9965-297f7ed10218",
  • "assignmentId": "d265a413-a83e-40f1-b185-a3b1fb74c905",
  • "purchaseOffer": {
    },
  • "offerValidity": {
    },
  • "buyerCustomerParties": [
    ],
  • "sellerCustomerParties": [
    ],
  • "assets": [
    ],
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "errorCode": "BAD_REQUEST_PARAMETERS",
  • "message": "Invalid request parameters",
  • "description": "Request parameters are missing or have invalid type.",
  • "errors": [
    ]
}

Delete a purchase offer

Deletes the specified purchase offer whose id is given as a path variable.

A purchase offer can be deleted only if its status is: DRAFT.

Authorizations:
bearerAuth
path Parameters
offerId
required
string <uuid>
Example: ddc25849-7bc7-43c0-9c3b-602cb03f7806

Unique offer identifier in UUID format.

header Parameters
Request-ID
required
string <uuid>
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

A unique id which identifies the HTTP request. The value of this header must be created by the client. This identifier is used for troubleshooting purposes.

Responses

Response samples

Content type
application/json
{
  • "errorCode": "BAD_REQUEST_PARAMETERS",
  • "message": "Invalid request parameters",
  • "description": "Request parameters are missing or have invalid type.",
  • "errors": [
    ]
}

Execute purchase offer action

Execute purchase offer action.

Authorizations:
bearerAuth
path Parameters
offerId
required
string <uuid>
Example: ddc25849-7bc7-43c0-9c3b-602cb03f7806

Unique offer identifier in UUID format.

header Parameters
Request-ID
required
string <uuid>
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

A unique id which identifies the HTTP request. The value of this header must be created by the client. This identifier is used for troubleshooting purposes.

Request Body schema: application/json
required

Contains the action to be executed for the purchase offer.

actionCode
required
string
Enum: "LOCK" "UNLOCK" "ACTIVATE" "OFFEROR_REJECT" "RECEIVER_REJECT" "ACCEPT"

'Action to be executed. The actions can be used to trigger the following status transitions:

  • LOCK = DRAFT -> READY_FOR_SIGNING

  • UNLOCK = READY_FOR_SIGNING -> DRAFT

  • ACTIVATE = READY_FOR_SIGNING -> ACTIVE

  • OFFEROR_REJECT = READY_FOR_SIGNING -> REJECTED

  • RECEIVER_REJECT = ACTIVE -> REJECTED

  • ACCEPT = ACTIVE -> ACCEPTED'

Responses

Request samples

Content type
application/json
{
  • "actionCode": "LOCK"
}

Response samples

Content type
application/json
{
  • "errorCode": "BAD_REQUEST_PARAMETERS",
  • "message": "Invalid request parameters",
  • "description": "Request parameters are missing or have invalid type.",
  • "errors": [
    ]
}

Update purchase offer to it's final status

Update purchase offer that is in DRAFT status to it's final status. This method can be used while migrating historical purchase offers from other systems.

Authorizations:
bearerAuth
path Parameters
offerId
required
string <uuid>
Example: ddc25849-7bc7-43c0-9c3b-602cb03f7806

Unique offer identifier in UUID format.

header Parameters
Request-ID
required
string <uuid>
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

A unique id which identifies the HTTP request. The value of this header must be created by the client. This identifier is used for troubleshooting purposes.

Request Body schema: application/json
required

Contains the final status for the purchase offer.

finalOfferStatusCode
required
string
Enum: "ACCEPTED" "REJECTED" "EXPIRED"

Final status for purchase offer.

decisionTime
string <date-time>

Date time when offer was either accepted or rejected.

Note: The value must be present if finalOfferStatusCode is ACCEPTED or REJECTED and ignored if finalOfferStatusCode is EXPIRED.

Responses

Request samples

Content type
application/json
{
  • "finalOfferStatusCode": "ACCEPTED",
  • "decisionTime": "2023-12-06T12:00:00Z"
}

Response samples

Content type
application/json
{
  • "errorCode": "BAD_REQUEST_PARAMETERS",
  • "message": "Invalid request parameters",
  • "description": "Request parameters are missing or have invalid type.",
  • "errors": [
    ]
}

Counter Offer

Counter Offer API allows you to create, update and fetch counter offers. Counter offers are modifications to the original offer.

Create a counter offer

Create a new counter offer.

The counter offer is related either to an purchase offer or another counter offer.

Authorizations:
bearerAuth
path Parameters
offerId
required
string <uuid>
Example: ddc25849-7bc7-43c0-9c3b-602cb03f7806

Unique offer identifier in UUID format.

header Parameters
Request-ID
required
string <uuid>
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

A unique id which identifies the HTTP request. The value of this header must be created by the client. This identifier is used for troubleshooting purposes.

Request Body schema: application/json
required

Contains the details for the counter offer.

required
object

Specifies details for the counter offer.

The respondent is either a buyer or a seller.

required
object (OfferValidity)

Contains details about offer validity. Note that the end date also includes the time.

required
Array of objects (CounterOfferAssetPrices) [ items non-empty ]

Includes realty-specific prices for the counter offer. The array must include price element for each asset specified in the initial purchase offer.

Responses

Request samples

Content type
application/json
{
  • "counterOffer": {
    },
  • "offerValidity": {
    },
  • "assetPrices": [
    ]
}

Response samples

Content type
application/json
{
  • "counterOfferId": "8a35693d-735a-4dbd-9a3a-8f624654f6df"
}

Update a counter offer

Update a counter offer.

The counter offer is related either to an purchase offer or another counter offer.

Authorizations:
bearerAuth
path Parameters
offerId
required
string <uuid>
Example: ddc25849-7bc7-43c0-9c3b-602cb03f7806

Unique offer identifier in UUID format.

counterOfferId
required
string <uuid>
Example: ddc25849-7bc7-43c0-9c3b-602cb03f7808

Unique counter offer identifier in UUID format.

header Parameters
Request-ID
required
string <uuid>
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

A unique id which identifies the HTTP request. The value of this header must be created by the client. This identifier is used for troubleshooting purposes.

Request Body schema: application/json
required

Contains the details for the counter offer.

required
object

Specifies details for the counter offer.

required
object (OfferValidity)

Contains details about offer validity. Note that the end date also includes the time.

required
Array of objects (CounterOfferAssetPrices) [ items non-empty ]

Includes realty-specific prices for the counter offer. The array must include price element for each asset specified in the initial purchase offer.

Responses

Request samples

Content type
application/json
{
  • "counterOffer": {
    },
  • "offerValidity": {
    },
  • "assetPrices": [
    ]
}

Response samples

Content type
application/json
{
  • "errorCode": "BAD_REQUEST_PARAMETERS",
  • "message": "Invalid request parameters",
  • "description": "Request parameters are missing or have invalid type.",
  • "errors": [
    ]
}

Delete a counter offer

Deletes the specified counter offer whose id is given as a path variable.

A counter offer can be deleted only if its status is: DRAFT.

Authorizations:
bearerAuth
path Parameters
offerId
required
string <uuid>
Example: ddc25849-7bc7-43c0-9c3b-602cb03f7806

Unique offer identifier in UUID format.

counterOfferId
required
string <uuid>
Example: ddc25849-7bc7-43c0-9c3b-602cb03f7808

Unique counter offer identifier in UUID format.

header Parameters
Request-ID
required
string <uuid>
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

A unique id which identifies the HTTP request. The value of this header must be created by the client. This identifier is used for troubleshooting purposes.

Responses

Response samples

Content type
application/json
{
  • "errorCode": "BAD_REQUEST_PARAMETERS",
  • "message": "Invalid request parameters",
  • "description": "Request parameters are missing or have invalid type.",
  • "errors": [
    ]
}

Execute counter offer action.

Execute counter offer action.

Authorizations:
bearerAuth
path Parameters
offerId
required
string <uuid>
Example: ddc25849-7bc7-43c0-9c3b-602cb03f7806

Unique offer identifier in UUID format.

counterOfferId
required
string <uuid>
Example: ddc25849-7bc7-43c0-9c3b-602cb03f7808

Unique counter offer identifier in UUID format.

header Parameters
Request-ID
required
string <uuid>
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

A unique id which identifies the HTTP request. The value of this header must be created by the client. This identifier is used for troubleshooting purposes.

Request Body schema: application/json
required

Contains the action to be executed for the counter offer.

actionCode
required
string
Enum: "LOCK" "UNLOCK" "ACTIVATE" "OFFEROR_REJECT" "RECEIVER_REJECT" "ACCEPT"

'Action to be executed. The actions can be used to trigger the following status transitions:

  • LOCK = DRAFT -> READY_FOR_SIGNING

  • UNLOCK = READY_FOR_SIGNING -> DRAFT

  • ACTIVATE = READY_FOR_SIGNING -> ACTIVE

  • OFFEROR_REJECT = READY_FOR_SIGNING -> REJECTED

  • RECEIVER_REJECT = ACTIVE -> REJECTED

  • ACCEPT = ACTIVE -> ACCEPTED'

Responses

Request samples

Content type
application/json
{
  • "actionCode": "LOCK"
}

Response samples

Content type
application/json
{
  • "errorCode": "BAD_REQUEST_PARAMETERS",
  • "message": "Invalid request parameters",
  • "description": "Request parameters are missing or have invalid type.",
  • "errors": [
    ]
}