Asset Requirement API (1.0)

Download OpenAPI specification:Download

Introduction

Asset Requirement API allows an agent to manage asset requirements. A buyer can specify requirements to buy an asset.

Based on these asset requirements, the agent can find matching realties for the buyer to purchase.

Contact

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

Error codes

Below is the summary of most common error codes included in the response's errorCode field.

HTTP status code	Error code	Meaning
400	`BAD_REQUEST_PARAMETERS`	Invalid request with e.g. missing mandatory parameters.
400	`BAD_REQUEST_BODY`	Invalid request body with e.g. missing mandatory fields.
400	`VALUE_REQUIRED`	Mandatory value missing for the request.
400	`INVALID_TYPE`	Invalid data type provided for the value in the request.
400	`INVALID_STATUS`	Unable to perform the request operation due to invalid state.
401	`UNAUTHORIZED`	Unauthorized request.
404	`INVALID_ID`	Missing or invalid identifier.
404	`INVALID_API_KEY`	Missing or invalid API key.
415	`UNSUPPORTED_MEDIA_TYPE`	Unsupported media type.
500	`TECHNICAL_ERROR`	A technical error has occurred.

Asset Requirements

Asset Requirements API allows you to create, update and fetch asset requirements. They can be associated with a purchase assignment.

Create an asset requirements entity

Create a new asset requirements entity.

Authorizations:

bearerAuth

header Parameters

Request-ID

required

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

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

Contains the details for the asset-requirements entity.

agencyOfficeId required	string <uuid> (AgencyOfficeId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Unique identifier for the agency office in the UUID format.
	Array of objects (AgentForAssetRequirement) non-empty Specifies the agents who are associated with this asset requirement.
note	string (Note) A note written by the agent.
required	object (AssetRequirements) Includes requirements about the asset to be purchased.
	object (ConsentToChange) Contains the consent provided by the principal (buyer or seller) to change details for this entity.
creationTime	string <date-time> (CreationTime) Creation time of the asset requirement entity in the ISO 8601 format. If the value is not provided, the time will be automatically generated upon creating the asset requirement entity.

Responses

Request samples

Payload

Content type

application/json

{"agencyOfficeId": "212114ec-819e-483c-a8e0-f82289ac6e19",
"agents": [{"agentId": "da3a543e-4220-4c1f-8cda-2ae0b2e596e0",
"roleCode": "RESPONSIBLE_AGENT"
},
{"agentId": "386654b2-882f-442e-9ffe-7d6b6e367715",
"roleCode": "MARKETING_AGENT"
}
],
"note": "Asiakas haluaa myöhemmin toimeksiannon, aloitetaan vahdilla ensin",
"assetRequirements": {"title": [{"languageCode": "en",
"text": "3R+K+S"
},
{"languageCode": "fi",
"text": "3H+K+S"
},
{"languageCode": "sv",
"text": "3R+K+S"
}
],
"realty": {"availability": {"availabilityCodes": ["AVAILABLE"
],
"description": [{"languageCode": "fi",
"text": "Saatavissa kahden kuukauden sisällä."
},
{"languageCode": "sv",
"text": "Tillgänglig inom två månader."
}
]
},
"ownershipTypeCodes": ["OWN"
],
"propertyTypeCodes": ["RESIDENTIAL",
"LEISURE"
],
"residentialTypeCodes": ["APARTMENT_HOUSE"
],
"plotPropertyTypeCodes": ["HOUSE_PLOT"
],
"estatePropertyTypeCodes": ["FOREST"
],
"otherPropertyTypeCodes": ["PARKING_SLOT"
],
"condition": {"conditionCodes": ["GOOD",
"NEW"
],
"description": [{"languageCode": "fi",
"text": "Keittiö voidaan uusia."
},
{"languageCode": "sv",
"text": "Köket kan förnyas."
}
]
},
"earliestConstructionYear": 2000,
"latestConstructionYear": 2022
},
"addresses": [{"district": "Tammela",
"region": "Pirkanmaa",
"regionCode": "FI_PIRKANMAA",
"postcode": "33500",
"postalArea": "Tampere",
"locality": "Tampere",
"localityCode": "FI_PIRKANMAA_TAMPERE",
"countryCode": "FI"
},
{"district": "Nekala",
"region": "Pirkanmaa",
"regionCode": "FI_PIRKANMAA",
"postcode": "33800",
"postalArea": "Tampere",
"locality": "Tampere",
"localityCode": "FI_PIRKANMAA_TAMPERE",
"countryCode": "FI"
}
],
"apartment": {"roomCountCodes": ["2H",
"3H"
],
"area": {"minimumLivingAreaInSquareMeters": 100,
"maximumLivingAreaInSquareMeters": 200,
"totalAreaDescription": [{"languageCode": "en",
"text": "About 200 square meters."
},
{"languageCode": "fi",
"text": "Noin 200 neliömetriä."
},
{"languageCode": "sv",
"text": "Circa 200 kvadratmeter."
}
]
}
},
"plot": {"holdingTypeCodes": ["OWN"
],
"minimumAreaInSquareMeters": 500,
"maximumAreaInSquareMeters": 1000,
"totalAreaDescription": [{"languageCode": "en",
"text": "Perferably not over 1000 square meters."
},
{"languageCode": "fi",
"text": "Ei mielellään yli 1000 neliömetriä."
},
{"languageCode": "sv",
"text": "Högst 1000 kvadratmeter."
}
]
},
"features": {"hasElevator": true,
"hasBalcony": true,
"hasSauna": true,
"housingCompanyHasSauna": false,
"specialWishes": [{"languageCode": "fi",
"text": "Merinäköala."
},
{"languageCode": "sv",
"text": "Havutsikt."
}
]
},
"financialTerms": {"debtFreePriceRange": {"minimumPrice": 100000,
"maximumPrice": 150000,
"currencyCode": "EUR"
},
"paymentTerms": [{"languageCode": "fi",
"text": "14 pv netto."
},
{"languageCode": "sv",
"text": "14 dagar netto."
}
]
}
}
}

Response samples

Content type

application/json

{"assetRequirementId": "45221bb8-2deb-47c4-b5e4-155a8f1770dd"
}

Fetch asset requirements

Fetch asset requirements by using different search criteria. You can combine the search criteria, for example to search for asset requirements for a specified agency office.

Authorizations:

bearerAuth

query Parameters

agentId	string <uuid> (AgentId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: agentId=5d2a6d47-da73-4b11-8940-27cffabb6de5 Search by the agent identifier to get a list of asset requirements the agent is responsible for.
agencyOfficeId	Array of strings <uuid> (AgencyOfficeId) Example: agencyOfficeId=212114ec-819e-483c-a8e0-f82289ac6e19 Search by the agency office identifiers to get a list of asset requirement entities that belong to certain agency offices.
friendlyId	string (FriendlyId) Example: friendlyId=40246121 Search by the friendly identifier to get asset requirements matching the identifier.
statusCode	Array of strings (StatusCode) Items Enum: "DRAFT" "ACTIVE" "FINISHED" "REJECTED" "PURCHASED" Example: statusCode=DRAFT Search by the asset requirements status to get asset requirements matching the status.
marketingActionStatusCode	Array of strings (MarketingActionStatusCode) Items Enum: "IN_PROGRESS" "WAITING" "PUBLISHED" "FINISHED" "FAILED" Example: marketingActionStatusCode=PUBLISHED Search by the publishing status to get asset requirements matching the status.
freeTextSearch	string Example: freeTextSearch=Hämeenkatu Tampere Search by a free text to match asset requirements with the given search text.
startIndex	integer <int32> >= 0 Default: 0 Example: startIndex=20 Paginate returned asset requirements starting from this index. Index starts from 0.
endIndex	integer <int32> >= 0 Example: endIndex=40 Paginate returned asset requirements ending to this index.
sort	string Example: sort=creationTime\|desc,friendlyId\|asc Sort the asset requirements based on the specified fields. Fields also includes sort order as follows: `{field_name}\|{asc\|desc},{field_name}\|{asc\|desc}`

header Parameters

Request-ID

required

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

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,
"assetRequirements": [{"assetRequirementId": "45221bb8-2deb-47c4-b5e4-155a8f1770dd",
"statusCode": "DRAFT",
"friendlyId": "40142361",
"agencyOfficeId": "212114ec-819e-483c-a8e0-f82289ac6e19",
"responsibleAgent": {"agentId": "da3a543e-4220-4c1f-8cda-2ae0b2e596e0",
"roleCode": "RESPONSIBLE_AGENT",
"firstName": "Veikko",
"lastName": "Viljanen"
},
"note": "Asiakas haluaa myöhemmin toimeksiannon, aloitetaan vahdilla ensin",
"marketingActionStatusCode": "PUBLISHED",
"assetRequirements": {"title": [{"languageCode": "en",
"text": "3R+K+S"
},
{"languageCode": "fi",
"text": "3H+K+S"
},
{"languageCode": "sv",
"text": "3R+K+S"
}
],
"realty": {"availability": {"availabilityCodes": ["AVAILABLE"
],
"description": [{"languageCode": "fi",
"text": "Saatavissa kahden kuukauden sisällä."
},
{"languageCode": "sv",
"text": "Tillgänglig inom två månader."
}
]
},
"ownershipTypeCodes": ["OWN"
],
"propertyTypeCodes": ["RESIDENTIAL",
"LEISURE"
],
"residentialTypeCodes": ["APARTMENT_HOUSE"
],
"plotPropertyTypeCodes": ["HOUSE_PLOT"
],
"estatePropertyTypeCodes": ["FOREST"
],
"otherPropertyTypeCodes": ["PARKING_SLOT"
],
"condition": {"conditionCodes": ["GOOD",
"NEW"
],
"description": [{"languageCode": "fi",
"text": "Keittiö voidaan uusia."
},
{"languageCode": "sv",
"text": "Köket kan förnyas."
}
]
},
"earliestConstructionYear": 2000,
"latestConstructionYear": 2022
},
"addresses": [{"district": "Tammela",
"region": "Pirkanmaa",
"regionCode": "FI_PIRKANMAA",
"postcode": "33500",
"postalArea": "Tampere",
"locality": "Tampere",
"localityCode": "FI_PIRKANMAA_TAMPERE",
"countryCode": "FI"
},
{"district": "Nekala",
"region": "Pirkanmaa",
"regionCode": "FI_PIRKANMAA",
"postcode": "33800",
"postalArea": "Tampere",
"locality": "Tampere",
"localityCode": "FI_PIRKANMAA_TAMPERE",
"countryCode": "FI"
}
],
"apartment": {"roomCountCodes": ["2H",
"3H"
],
"area": {"minimumLivingAreaInSquareMeters": 100,
"maximumLivingAreaInSquareMeters": 200,
"totalAreaDescription": [{"languageCode": "en",
"text": "About 200 square meters."
},
{"languageCode": "fi",
"text": "Noin 200 neliömetriä."
},
{"languageCode": "sv",
"text": "Circa 200 kvadratmeter."
}
]
}
},
"plot": {"holdingTypeCodes": ["OWN"
],
"minimumAreaInSquareMeters": 500,
"maximumAreaInSquareMeters": 1000,
"totalAreaDescription": [{"languageCode": "en",
"text": "Perferably not over 1000 square meters."
},
{"languageCode": "fi",
"text": "Ei mielellään yli 1000 neliömetriä."
},
{"languageCode": "sv",
"text": "Högst 1000 kvadratmeter."
}
]
},
"features": {"hasElevator": true,
"hasBalcony": true,
"hasSauna": true,
"housingCompanyHasSauna": false,
"specialWishes": [{"languageCode": "fi",
"text": "Merinäköala."
},
{"languageCode": "sv",
"text": "Havutsikt."
}
]
},
"financialTerms": {"debtFreePriceRange": {"minimumPrice": 100000,
"maximumPrice": 150000,
"currencyCode": "EUR"
},
"paymentTerms": [{"languageCode": "fi",
"text": "14 pv netto."
},
{"languageCode": "sv",
"text": "14 dagar netto."
}
]
}
},
"creationTime": "2021-03-13T12:07:23+00:00"
}
]
}

Fetch an asset requirements entity

Fetch details for a specified asset requirements entity.

Authorizations:

bearerAuth

path Parameters

assetRequirementId

required

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

Example: b0cd92da-0810-4f9c-a81c-08e4da4e2f21

Unique asset requirement identifier in UUID format.

header Parameters

Request-ID

required

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

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

{"assetRequirementId": "45221bb8-2deb-47c4-b5e4-155a8f1770dd",
"statusCode": "DRAFT",
"friendlyId": "40142361",
"agencyOfficeId": "212114ec-819e-483c-a8e0-f82289ac6e19",
"agents": [{"agentId": "da3a543e-4220-4c1f-8cda-2ae0b2e596e0",
"roleCode": "RESPONSIBLE_AGENT"
},
{"agentId": "386654b2-882f-442e-9ffe-7d6b6e367715",
"roleCode": "MARKETING_AGENT"
}
],
"note": "Asiakas haluaa myöhemmin toimeksiannon, aloitetaan vahdilla ensin",
"assetRequirements": {"title": [{"languageCode": "en",
"text": "3R+K+S"
},
{"languageCode": "fi",
"text": "3H+K+S"
},
{"languageCode": "sv",
"text": "3R+K+S"
}
],
"realty": {"availability": {"availabilityCodes": ["AVAILABLE"
],
"description": [{"languageCode": "fi",
"text": "Saatavissa kahden kuukauden sisällä."
},
{"languageCode": "sv",
"text": "Tillgänglig inom två månader."
}
]
},
"ownershipTypeCodes": ["OWN"
],
"propertyTypeCodes": ["RESIDENTIAL",
"LEISURE"
],
"residentialTypeCodes": ["APARTMENT_HOUSE"
],
"plotPropertyTypeCodes": ["HOUSE_PLOT"
],
"estatePropertyTypeCodes": ["FOREST"
],
"otherPropertyTypeCodes": ["PARKING_SLOT"
],
"condition": {"conditionCodes": ["GOOD",
"NEW"
],
"description": [{"languageCode": "fi",
"text": "Keittiö voidaan uusia."
},
{"languageCode": "sv",
"text": "Köket kan förnyas."
}
]
},
"earliestConstructionYear": 2000,
"latestConstructionYear": 2022
},
"addresses": [{"district": "Tammela",
"region": "Pirkanmaa",
"regionCode": "FI_PIRKANMAA",
"postcode": "33500",
"postalArea": "Tampere",
"locality": "Tampere",
"localityCode": "FI_PIRKANMAA_TAMPERE",
"countryCode": "FI"
},
{"district": "Nekala",
"region": "Pirkanmaa",
"regionCode": "FI_PIRKANMAA",
"postcode": "33800",
"postalArea": "Tampere",
"locality": "Tampere",
"localityCode": "FI_PIRKANMAA_TAMPERE",
"countryCode": "FI"
}
],
"apartment": {"roomCountCodes": ["2H",
"3H"
],
"area": {"minimumLivingAreaInSquareMeters": 100,
"maximumLivingAreaInSquareMeters": 200,
"totalAreaDescription": [{"languageCode": "en",
"text": "About 200 square meters."
},
{"languageCode": "fi",
"text": "Noin 200 neliömetriä."
},
{"languageCode": "sv",
"text": "Circa 200 kvadratmeter."
}
]
}
},
"plot": {"holdingTypeCodes": ["OWN"
],
"minimumAreaInSquareMeters": 500,
"maximumAreaInSquareMeters": 1000,
"totalAreaDescription": [{"languageCode": "en",
"text": "Perferably not over 1000 square meters."
},
{"languageCode": "fi",
"text": "Ei mielellään yli 1000 neliömetriä."
},
{"languageCode": "sv",
"text": "Högst 1000 kvadratmeter."
}
]
},
"features": {"hasElevator": true,
"hasBalcony": true,
"hasSauna": true,
"housingCompanyHasSauna": false,
"specialWishes": [{"languageCode": "fi",
"text": "Merinäköala."
},
{"languageCode": "sv",
"text": "Havutsikt."
}
]
},
"financialTerms": {"debtFreePriceRange": {"minimumPrice": 100000,
"maximumPrice": 150000,
"currencyCode": "EUR"
},
"paymentTerms": [{"languageCode": "fi",
"text": "14 pv netto."
},
{"languageCode": "sv",
"text": "14 dagar netto."
}
]
}
},
"consentToChange": {"date": "2021-09-10",
"consentProvided": true,
"consentDeliveryMethodCode": "DELIVERED_BY_EMAIL"
},
"creationTime": "2021-03-13T12:07:23+00:00",
"modificationTime": "2021-08-15T08:04:44+00:00"
}

Update an asset requirements entity

Update the details of the asset requirements entity whose id is given as a path variable.

Authorizations:

bearerAuth

path Parameters

assetRequirementId

required

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

Example: b0cd92da-0810-4f9c-a81c-08e4da4e2f21

Unique asset requirement identifier in UUID format.

header Parameters

Request-ID

required

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

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

Contains the updated asset requirements entity.

assetRequirementId required	string <uuid> (AssetRequirementId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Unique identifier for the asset requirement in the UUID format.
statusCode required	string (StatusCode) Enum: "DRAFT" "ACTIVE" "FINISHED" "REJECTED" "PURCHASED" Asset requirement status. The status defines what actions can be performed for the asset requirement entity.
agencyOfficeId required	string <uuid> (AgencyOfficeId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Unique identifier for the agency office in the UUID format.
	Array of objects (AgentForAssetRequirement) non-empty Specifies the agents who are associated with this asset requirement.
note	string (Note) A note written by the agent.
required	object (AssetRequirements) Includes requirements about the asset to be purchased.
	object (ConsentToChange) Contains the consent provided by the principal (buyer or seller) to change details for this entity.

Responses

Request samples

Payload

Content type

application/json

{"assetRequirementId": "45221bb8-2deb-47c4-b5e4-155a8f1770dd",
"statusCode": "DRAFT",
"agencyOfficeId": "212114ec-819e-483c-a8e0-f82289ac6e19",
"agents": [{"agentId": "da3a543e-4220-4c1f-8cda-2ae0b2e596e0",
"roleCode": "RESPONSIBLE_AGENT"
},
{"agentId": "386654b2-882f-442e-9ffe-7d6b6e367715",
"roleCode": "MARKETING_AGENT"
}
],
"note": "Asiakas haluaa myöhemmin toimeksiannon, aloitetaan vahdilla ensin",
"assetRequirements": {"title": [{"languageCode": "en",
"text": "3R+K+S"
},
{"languageCode": "fi",
"text": "3H+K+S"
},
{"languageCode": "sv",
"text": "3R+K+S"
}
],
"realty": {"availability": {"availabilityCodes": ["AVAILABLE"
],
"description": [{"languageCode": "fi",
"text": "Saatavissa kahden kuukauden sisällä."
},
{"languageCode": "sv",
"text": "Tillgänglig inom två månader."
}
]
},
"ownershipTypeCodes": ["OWN"
],
"propertyTypeCodes": ["RESIDENTIAL",
"LEISURE"
],
"residentialTypeCodes": ["APARTMENT_HOUSE"
],
"plotPropertyTypeCodes": ["HOUSE_PLOT"
],
"estatePropertyTypeCodes": ["FOREST"
],
"otherPropertyTypeCodes": ["PARKING_SLOT"
],
"condition": {"conditionCodes": ["GOOD",
"NEW"
],
"description": [{"languageCode": "fi",
"text": "Keittiö voidaan uusia."
},
{"languageCode": "sv",
"text": "Köket kan förnyas."
}
]
},
"earliestConstructionYear": 2000,
"latestConstructionYear": 2022
},
"addresses": [{"district": "Tammela",
"region": "Pirkanmaa",
"regionCode": "FI_PIRKANMAA",
"postcode": "33500",
"postalArea": "Tampere",
"locality": "Tampere",
"localityCode": "FI_PIRKANMAA_TAMPERE",
"countryCode": "FI"
},
{"district": "Nekala",
"region": "Pirkanmaa",
"regionCode": "FI_PIRKANMAA",
"postcode": "33800",
"postalArea": "Tampere",
"locality": "Tampere",
"localityCode": "FI_PIRKANMAA_TAMPERE",
"countryCode": "FI"
}
],
"apartment": {"roomCountCodes": ["2H",
"3H"
],
"area": {"minimumLivingAreaInSquareMeters": 100,
"maximumLivingAreaInSquareMeters": 200,
"totalAreaDescription": [{"languageCode": "en",
"text": "About 200 square meters."
},
{"languageCode": "fi",
"text": "Noin 200 neliömetriä."
},
{"languageCode": "sv",
"text": "Circa 200 kvadratmeter."
}
]
}
},
"plot": {"holdingTypeCodes": ["OWN"
],
"minimumAreaInSquareMeters": 500,
"maximumAreaInSquareMeters": 1000,
"totalAreaDescription": [{"languageCode": "en",
"text": "Perferably not over 1000 square meters."
},
{"languageCode": "fi",
"text": "Ei mielellään yli 1000 neliömetriä."
},
{"languageCode": "sv",
"text": "Högst 1000 kvadratmeter."
}
]
},
"features": {"hasElevator": true,
"hasBalcony": true,
"hasSauna": true,
"housingCompanyHasSauna": false,
"specialWishes": [{"languageCode": "fi",
"text": "Merinäköala."
},
{"languageCode": "sv",
"text": "Havutsikt."
}
]
},
"financialTerms": {"debtFreePriceRange": {"minimumPrice": 100000,
"maximumPrice": 150000,
"currencyCode": "EUR"
},
"paymentTerms": [{"languageCode": "fi",
"text": "14 pv netto."
},
{"languageCode": "sv",
"text": "14 dagar netto."
}
]
}
},
"consentToChange": {"date": "2021-09-10",
"consentProvided": true,
"consentDeliveryMethodCode": "DELIVERED_BY_EMAIL"
}
}

Response samples

Content type

application/json

{"errorCode": "BAD_REQUEST_PARAMETERS",
"message": "Invalid request parameters",
"description": "Request parameters are missing or have invalid type.",
"errors": [{"target": "assignmentId",
"errorCode": "VALUE_REQUIRED",
"message": "Mandatory request parameter assignmentId is missing"
},
{"target": "authorId",
"errorCode": "INVALID_TYPE",
"message": "Request parameter authorId must be a string"
}
]
}

Delete an asset requirements entity

Deletes the specified asset requirements entity whose id is given as a path variable.

An asset requirement entity can be deleted only if its status is DRAFT.

Authorizations:

bearerAuth

path Parameters

assetRequirementId

required

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

Example: b0cd92da-0810-4f9c-a81c-08e4da4e2f21

Unique asset requirement identifier in UUID format.

header Parameters

Request-ID

required

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

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": [{"target": "assignmentId",
"errorCode": "VALUE_REQUIRED",
"message": "Mandatory request parameter assignmentId is missing"
},
{"target": "authorId",
"errorCode": "INVALID_TYPE",
"message": "Request parameter authorId must be a string"
}
]
}

Watches

Asset Requirements Watch API allows an agent to manage watches. Watches generate automatic notifications to parties about prospective realties.

The agent adds an asset requirement to act like search criteria for a party to match against newly added prospective realties for sale. The watch is associated with the asset requirement.

Fetch watches

Fetch watches by multiple search criteria.

Authorizations:

bearerAuth

query Parameters

watchId	Array of strings <uuid> (WatchId) Example: watchId=1803ca58-50ea-422b-a1f8-330289b67fe2 Search by one or multiple watch identifiers.
agentId	Array of strings <uuid> (AgentId) Example: agentId=5d2a6d47-da73-4b11-8940-27cffabb6de5 Search by the agent identifiers to get a list of watches the agents are responsible for.
agencyOfficeId	Array of strings <uuid> (AgencyOfficeId) Example: agencyOfficeId=212114ec-819e-483c-a8e0-f82289ac6e19 Search by the agency office identifiers to get a list of watches that belong to certain agency offices.
assetRequirementId	Array of strings <uuid> (AssetRequirementId) Example: assetRequirementId=1803ca58-50ea-422b-a1f8-330289b67fe2 Search by one or multiple watch identifiers.
partyId	Array of strings <uuid> (PartyId) Example: partyId=1803ca58-50ea-422b-a1f8-330289b67fe2 Search by one or multiple watch identifiers.
statusCode	Array of strings (WatchStatusCode) Items Enum: "ACTIVE" "ENDED" Example: statusCode=ACTIVE Search by watch validity status.
realtyPropertyTypeCode	Array of strings (RealtyPropertyTypeCode) Items Enum: "ESTATE" "LEISURE" "PLOT" "RESIDENTIAL" "OTHER" "SUBLEASE" "SHARED_APARTMENT" "COMMERCIAL_PROPERTY" Example: realtyPropertyTypeCode=RESIDENTIAL Search with property type codes to get a list of watches with specified property type criteria.
startIndex	integer <int32> >= 0 Example: startIndex=20 Paginate returned watches starting from this index. Index starts from 0.
size	integer <int32> [ 1 .. 100 ] Default: 50 Example: size=40 Number of results.
sort	Array of strings Example: sort=modificationTime\|asc Sort watches based on the specified fields. Supported fields: modificationTime. 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> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

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,
"watches": [{"watchId": "123e4567-e89b-12d3-a456-426614174000",
"assetRequirement": {"assetRequirementId": "45221bb8-2deb-47c4-b5e4-155a8f1770dd",
"responsibleAgent": {"agentId": "da3a543e-4220-4c1f-8cda-2ae0b2e596e0",
"firstName": "Veikko",
"lastName": "Viljanen"
},
"agencyOffice": {"agencyOfficeId": "212114ec-819e-483c-a8e0-f82289ac6e19",
"name": "Agency Office name"
}
},
"watchStatusCode": "ENDED",
"validityStartTime": "2023-01-01T00:00:00Z",
"validityEndTime": "2024-01-01T00:00:00Z",
"agentNotificationTypeCodes": ["EMAIL"
],
"parties": [{"partyId": "123e4567-e89b-12d3-a456-426614174000",
"partyTypeCode": "PERSON_PARTY",
"partyNotificationTypeCodes": ["EMAIL"
]
}
],
"creationTime": "2022-01-01T00:00:00Z",
"modificationTime": "2022-01-01T00:00:00Z"
}
]
}

Create a watch

Create a new watch

Authorizations:

bearerAuth

header Parameters

Request-ID

required

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

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

Watch details

agentNotificationTypeCodes required	Array of strings (NotificationTypeCode) Items Value: "EMAIL" An array of enabled notifications to the responsible agent.
validityEndTime required	string <date-time> (Timestamp) Timestamp as defined by ISO 8601 with time offset.
required	Array of objects (WatchParty) [ 1 .. 100 ] items An array of watch parties.
assetRequirementId required	string <uuid> (Uuid) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Unique identifier in the UUID format.

Responses

Request samples

Payload

Content type

application/json

{"assetRequirementId": "123e4567-e89b-12d3-a456-426614174000",
"validityEndTime": "2023-01-01T00:00:00Z",
"agentNotificationTypeCodes": ["EMAIL"
],
"parties": [{"partyId": "123e4567-e89b-12d3-a456-426614174000",
"partyTypeCode": "PERSON_PARTY",
"partyNotificationTypeCodes": ["EMAIL"
]
}
]
}

Response samples

Content type

application/json

{"watchId": "123e4567-e89b-12d3-a456-426614174000"
}

Fetch a watch

Fetch a watch by watch identifier.

Authorizations:

bearerAuth

path Parameters

watchId

required

string <uuid>

Example: ddc25849-7bc7-43c0-9c3b-602cb03f7806

Unique watch identifier in UUID format.

header Parameters

Request-ID

required

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

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

{"watchId": "123e4567-e89b-12d3-a456-426614174000",
"assetRequirement": {"assetRequirementId": "123e4567-e89b-12d3-a456-426614174000"
},
"watchStatusCode": "ENDED",
"validityStartTime": "2023-01-01T00:00:00Z",
"validityEndTime": "2024-01-01T00:00:00Z",
"agentNotificationTypeCodes": ["EMAIL"
],
"parties": [{"partyId": "123e4567-e89b-12d3-a456-426614174000",
"partyTypeCode": "PERSON_PARTY",
"partyNotificationTypeCodes": ["EMAIL"
]
}
],
"creationTime": "2022-01-01T00:00:00Z",
"modificationTime": "2022-01-01T00:00:00Z"
}

Update a watch

Update a watch by watch identifier.

Authorizations:

bearerAuth

path Parameters

watchId

required

string <uuid>

Example: ddc25849-7bc7-43c0-9c3b-602cb03f7806

Unique watch identifier in UUID format.

header Parameters

Request-ID

required

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

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

Contains the watch to be updated.

watchId required	string <uuid> (WatchId) Unique identifier for the watch in the UUID format. If referenced in the URL, should match the request body content.
agentNotificationTypeCodes required	Array of strings (NotificationTypeCode) Items Value: "EMAIL" An array of enabled notifications to the responsible agent.
validityEndTime required	string <date-time> (Timestamp) Timestamp as defined by ISO 8601 with time offset.
required	Array of objects (WatchParty) [ 1 .. 100 ] items An array of watch parties. The party IDs are immutable.
assetRequirementId required	string <uuid> (Uuid) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Unique identifier in the UUID format.

Responses

Request samples

Payload

Content type

application/json

{"watchId": "123e4567-e89b-12d3-a456-426614174000",
"assetRequirementId": "123e4567-e89b-12d3-a456-426614174000",
"validityEndTime": "2023-01-01T00:00:00Z",
"agentNotificationTypeCodes": ["EMAIL"
],
"parties": [{"partyId": "123e4567-e89b-12d3-a456-426614174000",
"partyTypeCode": "PERSON_PARTY",
"partyNotificationTypeCodes": ["EMAIL"
]
}
]
}

Response samples

Content type

application/json

{"errorCode": "BAD_REQUEST_PARAMETERS",
"message": "Invalid request parameters",
"description": "Request parameters are missing or have invalid type.",
"errors": [{"target": "assignmentId",
"errorCode": "VALUE_REQUIRED",
"message": "Mandatory request parameter assignmentId is missing"
},
{"target": "authorId",
"errorCode": "INVALID_TYPE",
"message": "Request parameter authorId must be a string"
}
]
}

Notes

Notes API allows you to create, fetch, update and delete notes.

Create a new note

Create a new note. One asset requirement can have maximum 20 notes. Return status code 400 if the limit is exceeded.

Authorizations:

bearerAuth

header Parameters

Request-ID

required

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

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

Request body contains details of the note to be created.

note required	string The content of the note
assetRequirementId required	string <uuid> The asset requirement id related to the note.

Responses

Request samples

Payload

Content type

application/json

{"note": "This is a note.",
"assetRequirementId": "123e4567-e89b-12d3-a456-426655440000"
}

Response samples

Content type

application/json

{"noteId": "c6d2288d-2ecb-448a-aef3-fd5144920e0b"
}

Search notes

Search notes with specified parameters.

Authorizations:

bearerAuth

query Parameters

assetRequirementId

required

string <uuid>

Identifier of the assetRequirement for which notes are searched.

header Parameters

Request-ID

required

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

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,
"notes": [{"noteId": "c6d2288d-2ecb-448a-aef3-fd5144920e0b",
"note": "This is a note.",
"assetRequirementId": "123e4567-e89b-12d3-a456-426655440000",
"creationTime": "2021-01-01T00:00:00Z",
"modificationTime": "2021-01-01T00:00:00Z",
"createdBy": "123e4567-e89b-12d3-a456-426655440000",
"modifiedBy": "123e4567-e89b-12d3-a456-426655440000"
}
]
}

Update a note

Update a note.

Authorizations:

bearerAuth

path Parameters

noteId

required

string <uuid>

Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

Identifier of the note

header Parameters

Request-ID

required

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

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

Request body contains details of the note to be updated.

note

required

string

The content of the note

Responses

Request samples

Payload

Content type

application/json

{"note": "This is a note."
}

Response samples

Content type

application/json

{"errorCode": "BAD_REQUEST_PARAMETERS",
"message": "Invalid request parameters",
"description": "Request parameters are missing or have invalid type.",
"errors": [{"target": "assignmentId",
"errorCode": "VALUE_REQUIRED",
"message": "Mandatory request parameter assignmentId is missing"
},
{"target": "authorId",
"errorCode": "INVALID_TYPE",
"message": "Request parameter authorId must be a string"
}
]
}

Delete a note

Delete a note.

Authorizations:

bearerAuth

path Parameters

noteId

required

string <uuid>

Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

Identifier of the note

header Parameters

Request-ID

required

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

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": [{"target": "assignmentId",
"errorCode": "VALUE_REQUIRED",
"message": "Mandatory request parameter assignmentId is missing"
},
{"target": "authorId",
"errorCode": "INVALID_TYPE",
"message": "Request parameter authorId must be a string"
}
]
}