Insights API (v1)
Download OpenAPI specification:
The Insights API provides endpoints to retrieve real estate and property-related documents using Alma Property Insights service. It enables users to configure agency settings, validate realty identifiers and place document orders.
If you have any questions, comments or feedback regarding our APIs, please contact developer@ovipro.fi.
Get Insights API configuration
Returns the current configuration for the agency office.
Authorizations:
query Parameters
| agencyOfficeId required | string Example: agencyOfficeId=161f90cc-90f7-4e43-b4ad-a09b4f02689c ID of the agency to get configuration for. |
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
- 200
- 400
- 401
- 500
{- "agencyOfficeId": "161f90cc-90f7-4e43-b4ad-a09b4f02689c",
- "isTokenConfigured": true,
- "configuration": {
- "tokenConfigurationLevel": "AGENCY_OFFICE",
- "costCenter": "CC-12345"
}
}Set Insights API configuration
Sets the configuration for accessing the Insights API. Configuration can be set at agency office, customer, or customer group level.
Authorizations:
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/jsonrequired
| token required | string Secret token to authenticate to Insights API. |
| agencyOfficeId required | string <uuid> ID of the agency to set configuration for. |
Responses
Request samples
- Payload
{- "token": "MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC4v4kkS68+Iin6\n",
- "agencyOfficeId": "161f90cc-90f7-4e43-b4ad-a09b4f02689c"
}Response samples
- 200
- 400
- 401
- 500
{ }Get housing companies
Returns a list of housing companies and their business identifiers matching the given name.
Authorizations:
query Parameters
| housingCompanyName required | string non-empty Example: housingCompanyName=Asunto Oy Esimerkki Partial or full name of the housing company to search for. |
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
- 200
- 400
- 401
- 500
- 502
{- "housingCompanies": [
- {
- "businessId": "1234567-8",
- "officialName": "Asunto Oy Esimerkkitalo"
}
]
}Get property identifier
Returns property identifier (kiinteistötunnus) for the given address. Street names and municipality names can be provided in either Finnish or Swedish.
Authorizations:
query Parameters
| streetName required | string non-empty Example: streetName=Esimerkkikatu Name of the street (can be in Finnish or Swedish). |
| streetNumber | string Example: streetNumber=1 Street number. |
| municipalityName required | string non-empty Example: municipalityName=Helsinki Name of the municipality (can be in Finnish or Swedish). |
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
- 200
- 400
- 401
- 500
{- "propertyIdentifiers": [
- {
- "propertyId": "123-456-7890-1234",
- "address": {
- "streetName": {
- "fi": "Esimerkkikatu",
- "sv": "Exempelgatan"
}, - "streetNumber": "1",
- "municipalityName": {
- "fi": "Helsinki",
- "sv": "Helsingfors"
}, - "postalCode": "00100"
}
}
]
}Used to create PDF orders for documents that are availaible in Alma Property Insights.
Get document orders
Returns a list of document orders.
Authorizations:
query Parameters
| ownerCode required | string Enum: "REALTY" "ASSIGNMENT" Example: ownerCode=REALTY Owner code of the entity for which the document orders are requested. |
| ownerEntityId required | string <uuid> Example: ownerEntityId=d6d8d138-4aea-4cd3-8b6e-1a9e45bb409f PublicId of the owner entity for which the document orders are requested. |
| startIndex | integer <int32> >= 0 Default: 0 Paginate returned documents starting from this index. Index starts from 0. example: 20 |
| size | integer <int32> [ 1 .. 200 ] Default: 100 |
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
- 200
- 400
- 401
- 500
{- "documentOrders": [
- {
- "documentOrderId": "550e8400-e29b-41d4-a716-446655440000",
- "ownerCode": "REALTY",
- "ownerEntityId": "b5c7a833-47d1-4d49-a8b4-79c6d6778899",
- "agencyOfficeId": "161f90cc-90f7-4e43-b4ad-a09b4f02689c",
- "orderedDocuments": [
- {
- "documentType": "TITLE_CERTIFICATE",
- "identification": {
- "propertyId": "91-123-4567-1"
}, - "orderStatus": "COMPLETED",
- "completionTime": "2024-03-01T10:20:30Z",
- "documentId": "7a8b9c10-d11e-4f12-a13b-14c15d16e17f"
}, - {
- "documentType": "EXTRACT_OF_LAND_REGISTRY",
- "identification": {
- "propertyId": "91-123-4567-1"
}, - "orderStatus": "FAILED",
- "failureCode": "CONFIGURATION_ERROR"
}
], - "orderedBy": "42befdc5-9a72-4a85-b324-c63d4a961022",
- "orderedFor": "8b4e5ca4-0c84-493f-afa6-9693a0e16165",
- "creationTime": "2024-03-01T10:15:30Z"
}, - {
- "documentOrderId": "660e8400-e29b-41d4-a716-446655440111",
- "ownerCode": "REALTY",
- "ownerEntityId": "c6d7e844-58e2-5e5a-b9c5-80d7e7889900",
- "agencyOfficeId": "161f90cc-90f7-4e43-b4ad-a09b4f02689c",
- "orderedDocuments": [
- {
- "documentType": "OWNER_APARTMENT_PRINTOUT",
- "identification": {
- "businessId": "1234567-8",
- "shareGroupIdentifier": "AB12345678901234"
}, - "orderStatus": "COMPLETED",
- "completionTime": "2024-03-01T11:35:15Z",
- "documentId": "7a8b9c10-d11e-4f12-a13b-14c15d16e17f"
}, - {
- "documentType": "SHARE_REGISTER_PRINTOUT",
- "identification": {
- "businessId": "1234567-8",
- "shareGroupIdentifier": "AB12345678901234"
}, - "orderStatus": "IN_PROGRESS"
}
], - "orderedBy": "42befdc5-9a72-4a85-b324-c63d4a961022",
- "orderedFor": "8b4e5ca4-0c84-493f-afa6-9693a0e16165",
- "creationTime": "2024-03-01T11:30:45Z"
}
], - "totalCount": 2
}Create a new document order
Creates a new document order for the specified realty from Alma Property Insights.
Authorizations:
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/jsonrequired
| orderedFor required | string <uuid> PublicId of the business user for whom the document is being ordered. |
required | object Identification of the entity for which the documents will be saved. |
required | Array of PropertyDocumentByPropertyId (object) or PropertyDocumentByFacilityId (object) or PropertyDocumentByParcelCode (object) or ShareDocumentForHousingCompany (object) or ShareDocumentForShareGroup (object) (Document) non-empty unique List of documents to order. |
Responses
Request samples
- Payload
{- "orderedFor": "cd1c227b-38b4-4f64-9e3a-c00f429a57ae",
- "ownerEntity": {
- "ownerCode": "REALTY",
- "ownerEntityId": "6da7bd98-1f0e-4b09-9a16-e8663f1e0b04",
- "agencyOfficeId": "a7643542-677e-46a7-8397-9443da8af2be"
}, - "documents": [
- {
- "propertyId": "123-456-7890-1234",
- "documentType": "ENCUMBRANCE_CERTIFICATE"
}
]
}Response samples
- 201
- 400
- 401
- 500
{- "documentOrderId": "d6d8d138-4aea-4cd3-8b6e-1a9e45bb409f"
}