Alma logo
API docs by Redocly

Document API (1.0)

Download OpenAPI specification:Download

Introduction

Document API is used to manage documents in the document archive.

  • Documents can be uploaded to the document archive.
  • Documents can be downloaded from the document archive.
  • Documents can be searched using different search criteria.
  • Documents can be shared with parties or using email.

Contact

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

Document

API for managing and serving documents in OviPro.

Fetch documents

Fetch metadata of documents by their owner entity

Authorizations:
bearerAuth
query Parameters
ownerCode
required
string (DocumentOwnerCode)
Enum: "PARTY" "REALTY" "ASSIGNMENT" "OFFER" "BILLING" "TRADE" "RENTAL_SETTLEMENT"
Example: ownerCode=REALTY

Search by the document owner code to get a list of documents that belong to the certain document owner such as a realty.

ownerEntityId
required
string <uuid> (OwnerEntityId)
Example: ownerEntityId=212114ec-819e-483c-a8e0-f82289ac6e19

Search by the document owner identifier to get a list of documents that belong to the certain document owner such as a realty.

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

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

size
integer <int32> [ 1 .. 200 ]
Default: 100
Example: size=40

Documents returned per page.

sort
string
Example: sort=documentId|desc,creationTime|desc

Sort the documents based on the specified fields. One of more fields can also include a sort order as follows:

sort={field_name}|{asc|desc},{field_name}|{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": 3,
  • "documents": [
    ]
}

Create a new document using uploaded file contents

This endpoint assumes that file has been uploaded to document storage using grant from GET document/uploadGrant endpoint. With this endpoint meta data for document must be saved to make document accessible.

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
uploadedDocumentKey
required
string (UploadedDocumentKey)

Value of key property from upload grant.

ownerCode
required
string (DocumentOwnerCode)
Enum: "PARTY" "REALTY" "ASSIGNMENT" "OFFER" "BILLING" "TRADE" "RENTAL_SETTLEMENT"

Defines the document owner type. Possible values are:

  • PARTY. The document is associated with a specific party.
  • REALTY. The document is associated with a specific realty.
  • ASSIGNMENT. The document is associated with an assignment.
  • OFFER. The document is associated with an offer.
  • BILLING. The document is associated with billing.
  • TRADE. The document is associated with trade settlement.
  • RENTAL_SETTLEMENT. The document is associated with rental settlement.
ownerEntityId
required
string <uuid> (OwnerEntityId)

Unique identifier for document owner entity in the UUID format. Depending on ownerCode value, this identifier refers to the actual entity. For example, if ownerCode has the value SALES_ASSIGNMENT, this entity identifier refers to the assignment identifier.

agencyOfficeId
required
string <uuid> (AgencyOfficeId)

Unique identifier for the agency office in the UUID format.

documentTypeCode
required
string (DocumentTypeCode)
Enum: "AREA_ASSESSMENT_MINUTES" "ARTICLES_OF_ASSOCIATION" "ASSIGNMENT" "BROCHURE" "BUILDING_MANAGEMENT_PLAN" "CONDITION_REPORTS" "CONDITION_SURVEY_REPORT" "CONTINUATION_AGREEMENT" "COUNTER_OFFER" "DRAWINGS_FOR_BUILDING_PERMIT" "ENCUMBRANCE_CERTIFICATE" "ENERGY_PERFORMANCE_CERTICIFATE" "ESTATE_INVENTORY_DEED" "ESTATE_INVENTORY_DEED_ATTACHMENT" "ESTATE_INVENTORY_DEED_SHAREHOLDERS_CERTIFICATION" "EXPLANATORY_APPENDIX" "EXTRACT_OF_LAND_REGISTRY" "FINAL_INSPECTION_MINUTES" "FINANCIAL_STATEMENT" "FLOOR_PLAN" "HOUSING_MANAGER_CERTIFICATE" "INVOICE" "JOINT_POSSESSION_AGREEMENT" "LEASEHOLD_CERTIFICATE" "LEASEHOLD_ENCUMBRANCE_CERTIFICATE" "LEASE_CONTRACT" "LETTER_OF_ATTORNEY" "MAINTENANCE_NEEDS_STATEMENT" "MAINTENANCE_PLAN" "MAP" "MINUTES_EXTRACT" "OTHER" "OWNERSHIP_TRANSFER_POWER_OF_ATTORNEY" "OWNER_APARTMENT_PRINTOUT" "PARTY_COMPLIANCE_VERIFICATION" "PARTY_IDENTIFICATION_DOCUMENT" "POPULATION_REGISTER_EXTRACT" "PURCHASE_OFFER" "RENTAL_AGREEMENT" "REPAIR_REPORTS" "SALES_AND_MARKETING_PLAN" "SALES_DEED" "SHARE_CERTIFICATE" "SHARE_REGISTER_PRINTOUT" "SPOUSES_CONSENT" "SUBSET_OF_FINAL_INSPECTION_MINUTES" "TITLE_CERTIFICATE" "TRADE_REGISTER_EXTRACT" "TRANSFER_TAX_RECEIPT" "TRANSFER_TAX_RETURN_RECEIPT" "TRANSFER_TERMS" "WINDOW_CARD" "ZONING_DOCUMENTS"

Defines the document type. Available types:

  • AREA_ASSESSMENT_MINUTES (Pinta-alan mittauspöytäkirja)
  • ARTICLES_OF_ASSOCIATION (Yhtiöjärjestys)
  • ASSIGNMENT (Toimeksiantosopimus)
  • BROCHURE (Esite)
  • BUILDING_MANAGEMENT_PLAN (Pitkän tähtäimen suunnitelma (PTS))
  • CONDITION_REPORTS (Yhtiön kuntoon liittyvät selvitykset)
  • CONDITION_SURVEY_REPORT (Kuntotarkastusraportti)
  • CONTINUATION_AGREEMENT (Jatkosopimus)
  • COUNTER_OFFER (Vastatarjous)
  • DRAWINGS_FOR_BUILDING_PERMIT (Rakennuslupapiirrustukset)
  • ENCUMBRANCE_CERTIFICATE (Rasitustodistus)
  • ENERGY_PERFORMANCE_CERTICIFATE (Energiatodistus)
  • ESTATE_INVENTORY_DEED (Perukirja)
  • ESTATE_INVENTORY_DEED_ATTACHMENT (Perukirjan liite)
  • `ESTATE_INVENTORY_DEED_SHAREHOLDERS_CERTIFICATION (Perukirjan osakasluettelon vahvistus)
  • EXPLANATORY_APPENDIX (Selostusliite)
  • EXTRACT_OF_LAND_REGISTRY (Kiinteistörekisteriote)
  • FINAL_INSPECTION_MINUTES (Loppukatselmuspöytäkirja)
  • FINANCIAL_STATEMENT (Tilinpäätös)
  • FLOOR_PLAN (Pohjapiirros)
  • HOUSING_MANAGER_CERTIFICATE (Isännöitsijäntodistus)
  • INVOICE (Lasku)
  • JOINT_POSSESSION_AGREEMENT (Hallinnanjakosopimus)
  • LEASEHOLD_CERTIFICATE (Maanvuokrasopimus)
  • LEASEHOLD_ENCUMBRANCE_CERTIFICATE (Vuokraoikeuden rasitustodistus)
  • LEASE_CONTRACT (Vuokrasopimus)
  • LETTER_OF_ATTORNEY (Valtakirja)
  • MAINTENANCE_NEEDS_STATEMENT (Kunnossapitotarveselvitys)
  • MAINTENANCE_PLAN (Kunnossapitosuunnitelma)
  • MAP (Kartta)
  • MINUTES_EXTRACT (Pöytäkirjaote)
  • OTHER (Muu)
  • `OWNERSHIP_TRANSFER_POWER_OF_ATTORNEY
  • OWNER_APARTMENT_PRINTOUT (Osakehuoneistotuloste)
  • PARTY_COMPLIANCE_VERIFICATION (PEP ja henkilöllisyyden todentaminen)
  • PARTY_IDENTIFICATION_DOCUMENT (Henkilöllisyystodistus)
  • POPULATION_REGISTER_EXTRACT (Väestörekisteriote)
  • PURCHASE_OFFER (Ostotarjous)
  • RENTAL_AGREEMENT (Vuokrasopimus)
  • REPAIR_REPORTS (Huoneiston korjaus- ja muutostöihin liittyvät selvitykset)
  • SALES_AND_MARKETING_PLAN (Myynti- ja markkinointisopimus)
  • SALES_DEED (Kauppakirja)
  • SHARE_CERTIFICATE (Osakekirja)
  • SHARE_REGISTER_PRINTOUT (Osakeluettelotuloste)
  • SPOUSES_CONSENT (Puolison suostumus)
  • SUBSET_OF_FINAL_INSPECTION_MINUTES (Loppukatselmuspöytäkirja, osittainen` (käyttööottotarkastus))
  • TITLE_CERTIFICATE (Lainhuutotodistus)
  • TRADE_REGISTER_EXTRACT (Kaupparekisteriote)
  • TRANSFER_TAX_RECEIPT (Kuitti varainsiirtoveron maksusta)
  • TRANSFER_TAX_RETURN_RECEIPT (Kuitti varainsiirtoveroilmoituksen jättämisestä)
  • TRANSFER_TERMS (Kaupan ehdot)
  • WINDOW_CARD (Ikkunakortti)
  • ZONING_DOCUMENTS (Kaava-asiakirjat)
documentName
required
string (DocumentName) <= 200 characters

User provided name for document.

canBeShared
required
boolean

Indicates whether the document can be shared.

isReadOnly
required
boolean

Indicates whether the document's metadata can be modified or document can deleted by users.

canBeReplaced
required
boolean

Indicates whether document's file content can be replaced with new version.

Responses

Request samples

Content type
application/json
{
  • "uploadedDocumentKey": "uploads/b91d3115-9890-4cd3-8bc8-b93ac8c0596c",
  • "ownerCode": "REALTY",
  • "ownerEntityId": "c9afe69c-87c2-4631-bd06-770aae582a95",
  • "agencyOfficeId": "a6e221fb-f4de-41cf-ba16-b0c309e34126",
  • "documentTypeCode": "BROCHURE",
  • "documentName": "Esite Perustie 7 v2",
  • "canBeShared": true,
  • "isReadOnly": false,
  • "canBeReplaced": true
}

Response samples

Content type
application/json
{
  • "documentId": "eec25843-7b14-43c0-9c2a-602bc30f7099"
}

Delete documents found by search criteria

If documents are found by document owner code and owner identifier removes those.

Authorizations:
bearerAuth
query Parameters
ownerCode
required
string (DocumentOwnerCode)
Enum: "PARTY" "REALTY" "ASSIGNMENT" "OFFER" "BILLING" "TRADE" "RENTAL_SETTLEMENT"
Example: ownerCode=REALTY

Owner entity type code used to define documents that will be deleted.

ownerEntityId
required
string <uuid> (OwnerEntityId)
Example: ownerEntityId=4b80e9ba-d4e4-4667-9b97-f4d7176f4fcb

Owner entity id used to define documents that will be deleted.

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
{ }

Updates metadata of given document

Updates metadata of given document if document is not readOnly.

Authorizations:
bearerAuth
path Parameters
documentId
required
string <uuid>
Example: 940bf547-122f-4811-8ca0-6ffb9776f035

ID of the document to retrieve file content 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.

Request Body schema: application/json
documentTypeCode
required
string (DocumentTypeCode)
Enum: "AREA_ASSESSMENT_MINUTES" "ARTICLES_OF_ASSOCIATION" "ASSIGNMENT" "BROCHURE" "BUILDING_MANAGEMENT_PLAN" "CONDITION_REPORTS" "CONDITION_SURVEY_REPORT" "CONTINUATION_AGREEMENT" "COUNTER_OFFER" "DRAWINGS_FOR_BUILDING_PERMIT" "ENCUMBRANCE_CERTIFICATE" "ENERGY_PERFORMANCE_CERTICIFATE" "ESTATE_INVENTORY_DEED" "ESTATE_INVENTORY_DEED_ATTACHMENT" "ESTATE_INVENTORY_DEED_SHAREHOLDERS_CERTIFICATION" "EXPLANATORY_APPENDIX" "EXTRACT_OF_LAND_REGISTRY" "FINAL_INSPECTION_MINUTES" "FINANCIAL_STATEMENT" "FLOOR_PLAN" "HOUSING_MANAGER_CERTIFICATE" "INVOICE" "JOINT_POSSESSION_AGREEMENT" "LEASEHOLD_CERTIFICATE" "LEASEHOLD_ENCUMBRANCE_CERTIFICATE" "LEASE_CONTRACT" "LETTER_OF_ATTORNEY" "MAINTENANCE_NEEDS_STATEMENT" "MAINTENANCE_PLAN" "MAP" "MINUTES_EXTRACT" "OTHER" "OWNERSHIP_TRANSFER_POWER_OF_ATTORNEY" "OWNER_APARTMENT_PRINTOUT" "PARTY_COMPLIANCE_VERIFICATION" "PARTY_IDENTIFICATION_DOCUMENT" "POPULATION_REGISTER_EXTRACT" "PURCHASE_OFFER" "RENTAL_AGREEMENT" "REPAIR_REPORTS" "SALES_AND_MARKETING_PLAN" "SALES_DEED" "SHARE_CERTIFICATE" "SHARE_REGISTER_PRINTOUT" "SPOUSES_CONSENT" "SUBSET_OF_FINAL_INSPECTION_MINUTES" "TITLE_CERTIFICATE" "TRADE_REGISTER_EXTRACT" "TRANSFER_TAX_RECEIPT" "TRANSFER_TAX_RETURN_RECEIPT" "TRANSFER_TERMS" "WINDOW_CARD" "ZONING_DOCUMENTS"

Defines the document type. Available types:

  • AREA_ASSESSMENT_MINUTES (Pinta-alan mittauspöytäkirja)
  • ARTICLES_OF_ASSOCIATION (Yhtiöjärjestys)
  • ASSIGNMENT (Toimeksiantosopimus)
  • BROCHURE (Esite)
  • BUILDING_MANAGEMENT_PLAN (Pitkän tähtäimen suunnitelma (PTS))
  • CONDITION_REPORTS (Yhtiön kuntoon liittyvät selvitykset)
  • CONDITION_SURVEY_REPORT (Kuntotarkastusraportti)
  • CONTINUATION_AGREEMENT (Jatkosopimus)
  • COUNTER_OFFER (Vastatarjous)
  • DRAWINGS_FOR_BUILDING_PERMIT (Rakennuslupapiirrustukset)
  • ENCUMBRANCE_CERTIFICATE (Rasitustodistus)
  • ENERGY_PERFORMANCE_CERTICIFATE (Energiatodistus)
  • ESTATE_INVENTORY_DEED (Perukirja)
  • ESTATE_INVENTORY_DEED_ATTACHMENT (Perukirjan liite)
  • `ESTATE_INVENTORY_DEED_SHAREHOLDERS_CERTIFICATION (Perukirjan osakasluettelon vahvistus)
  • EXPLANATORY_APPENDIX (Selostusliite)
  • EXTRACT_OF_LAND_REGISTRY (Kiinteistörekisteriote)
  • FINAL_INSPECTION_MINUTES (Loppukatselmuspöytäkirja)
  • FINANCIAL_STATEMENT (Tilinpäätös)
  • FLOOR_PLAN (Pohjapiirros)
  • HOUSING_MANAGER_CERTIFICATE (Isännöitsijäntodistus)
  • INVOICE (Lasku)
  • JOINT_POSSESSION_AGREEMENT (Hallinnanjakosopimus)
  • LEASEHOLD_CERTIFICATE (Maanvuokrasopimus)
  • LEASEHOLD_ENCUMBRANCE_CERTIFICATE (Vuokraoikeuden rasitustodistus)
  • LEASE_CONTRACT (Vuokrasopimus)
  • LETTER_OF_ATTORNEY (Valtakirja)
  • MAINTENANCE_NEEDS_STATEMENT (Kunnossapitotarveselvitys)
  • MAINTENANCE_PLAN (Kunnossapitosuunnitelma)
  • MAP (Kartta)
  • MINUTES_EXTRACT (Pöytäkirjaote)
  • OTHER (Muu)
  • `OWNERSHIP_TRANSFER_POWER_OF_ATTORNEY
  • OWNER_APARTMENT_PRINTOUT (Osakehuoneistotuloste)
  • PARTY_COMPLIANCE_VERIFICATION (PEP ja henkilöllisyyden todentaminen)
  • PARTY_IDENTIFICATION_DOCUMENT (Henkilöllisyystodistus)
  • POPULATION_REGISTER_EXTRACT (Väestörekisteriote)
  • PURCHASE_OFFER (Ostotarjous)
  • RENTAL_AGREEMENT (Vuokrasopimus)
  • REPAIR_REPORTS (Huoneiston korjaus- ja muutostöihin liittyvät selvitykset)
  • SALES_AND_MARKETING_PLAN (Myynti- ja markkinointisopimus)
  • SALES_DEED (Kauppakirja)
  • SHARE_CERTIFICATE (Osakekirja)
  • SHARE_REGISTER_PRINTOUT (Osakeluettelotuloste)
  • SPOUSES_CONSENT (Puolison suostumus)
  • SUBSET_OF_FINAL_INSPECTION_MINUTES (Loppukatselmuspöytäkirja, osittainen` (käyttööottotarkastus))
  • TITLE_CERTIFICATE (Lainhuutotodistus)
  • TRADE_REGISTER_EXTRACT (Kaupparekisteriote)
  • TRANSFER_TAX_RECEIPT (Kuitti varainsiirtoveron maksusta)
  • TRANSFER_TAX_RETURN_RECEIPT (Kuitti varainsiirtoveroilmoituksen jättämisestä)
  • TRANSFER_TERMS (Kaupan ehdot)
  • WINDOW_CARD (Ikkunakortti)
  • ZONING_DOCUMENTS (Kaava-asiakirjat)
documentName
required
string (DocumentName) <= 200 characters

User provided name for document.

canBeShared
required
boolean

Indicates whether the document can be shared.

Responses

Request samples

Content type
application/json
{
  • "documentTypeCode": "BROCHURE",
  • "documentName": "Esite Perustie 7 v2",
  • "canBeShared": true
}

Response samples

Content type
application/json
{ }

Deletes a document

Deletes a document if document is not readOnly.

Authorizations:
bearerAuth
path Parameters
documentId
required
string <uuid>
Example: 940bf547-122f-4811-8ca0-6ffb9776f035

ID of the document to be deleted.

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
{ }

Get short-lived grant for uploading the document

Uploading a document starts with call to this endpoint. Response contains short-lived grant for uploading document's file content. Uploading the document is done using AWS S3's presigned POST.

After uploading file content document's metadata must be saved using POST /documents endpoint.

Authorizations:
bearerAuth
query Parameters
contentType
required
string
Example: contentType=image/png

Content-type for document that is going to be uploaded.

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
{
  • "url": "http://examplebucket.s3.amazonaws.com/",
  • "fields": {
    }
}

Get file content of a document

Returns url that can be used to download file contents of a document with specified Id.

Authorizations:
bearerAuth
path Parameters
documentId
required
string <uuid>
Example: 940bf547-122f-4811-8ca0-6ffb9776f035

ID of the document to retrieve file content 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

Content type
application/json
{}

Replace file content of a document

Replaces file contents of a document with specified Id.

Authorizations:
bearerAuth
path Parameters
documentId
required
string <uuid>
Example: 940bf547-122f-4811-8ca0-6ffb9776f035

ID of the document which file content will be replaced.

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
uploadedDocumentKey
required
string (UploadedDocumentKey)

Value of key property from upload grant.

Responses

Request samples

Content type
application/json
{
  • "uploadedDocumentKey": "uploads/b91d3115-9890-4cd3-8bc8-b93ac8c0596c"
}

Response samples

Content type
application/json
{ }

Document sharing

API for sharing documents.

Share documents

Send email containing links to documents stored using Document API to recipients. Recipients can be either Parties in Party API or non-customers using email addresses.

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
Array of objects non-empty

Identifiers of documents that will be shared.

required
Array of PartyRecipient (object) or EmailRecipient (object) non-empty

Recipients for shared documents.

required
object

Information about sender who shares the document.

required
object

Properties used in emails that are sent to recipients.

Responses

Request samples

Content type
application/json
{
  • "documents": [
    ],
  • "recipients": [
    ],
  • "sender": {
    },
  • "emailContent": {
    }
}

Response samples

Content type
application/json
{ }

Document sharings history

Returns list of log entries that are produced when document is sharead to a party. Results are sorted in ascending order using sharing time.

Either documentId or recipientPartyId query parameter must be provided.

Authorizations:
bearerAuth
query Parameters
documentId
string <uuid>
Example: documentId=940bf547-122f-4811-8ca0-6ffb9776f035

Id of the document that was shared

recipientPartyId
string <uuid>
Example: recipientPartyId=940bf547-122f-4811-8ca0-6ffb9776f035

Id of the party to who documents were shared.

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

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

size
integer <int32> [ 1 .. 200 ]
Default: 100
Example: size=40

Items returned per page.

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
{
  • "items": [
    ],
  • "totalCount": 2
}