Download OpenAPI specification:Download
Clearing API allows the agent to manage the clearing of a realty trade and a realty rental.
If you have any questions, comments or feedback regarding our APIs, please contact developer@ovipro.fi.
Trade Settlement API allows you to initiate and complete a trade settlement for a set of assets.
Search trade settlement matching specified query parameters.
realtyId | string <uuid> Example: realtyId=212114ec-819e-483c-a8e0-f82289ac6e19 Search by realty identifier to get a list of trade settlements for the realty. |
assignmentId | Array of strings <uuid> [ items <uuid > ] Example: assignmentId=212114ec-819e-483c-a8e0-f82289ac6e19 Search by assignment identifiers to get a list of trade settlements that belong to certain assignments. |
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 trade settlements the agent is related to. |
agencyOfficeId | Array of strings <uuid> (AgencyOfficeId) [^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...] Example: agencyOfficeId=212114ec-819e-483c-a8e0-f82289ac6e19 Search by the agency office identifiers to get a list of trade settlements that belong to certain agency offices. |
statusCode | Array of strings (TradeSettlementStatusCode) Items Enum: "IN_PROGRESS" "COMPLETED" "DISMANTLED" Example: statusCode=COMPLETED Search by the trade settlement status code to fetch trade settlements having specific statuses. |
modifiedAfter | string <date-time> (Timestamp) Example: modifiedAfter=2024-09-05T13:50:22.204Z Search by a timestamp to get a list of trade settlements which were modified after the specified time. |
tradeDateBefore | string <date> (Date) Example: tradeDateBefore=2021-01-15 Search by a date to get a list of trade settlements which have trade date before or equal to the specified date. |
tradeDateAfter | string <date> (Date) Example: tradeDateAfter=2021-01-15 Search by a date to get a list of trade settlements which have trade date after or equal to the specified date. |
startIndex | integer <int32> >= 0 Default: 0 Example: startIndex=20 Paginate returned trade settlements starting from this index. Index starts from 0. |
size | integer <int32> [ 1 .. 100 ] Default: 50 Example: size=40 Trade settlements returned per page. |
sort | Array of strings Example: sort=validAfter|desc Sort trade settlements based on the specified fields. Each fields must also include a sort order as follows:
|
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. |
{- "totalCount": 2,
- "tradeSettlements": [
- {
- "tradeSettlementId": "4a30bb37-96a7-47cc-9dec-f369c5651db4",
- "statusCode": "IN_PROGRESS",
- "agencyOfficeId": "4a30bb37-96a7-47cc-9dec-f369c5651db4",
- "agents": [
- {
- "agentId": "b8b9bc07-72c6-4241-a1a4-530ead372435",
- "roleCode": "RESPONSIBLE_AGENT"
}
], - "assignmentId": "4a30bb37-96a7-47cc-9dec-f369c5651db4",
- "tradeDate": "2022-01-01",
- "digitalTrading": true,
- "assets": [
- {
- "realtyId": "4a30bb37-96a7-47cc-9dec-f369c5651db4",
- "realtyTypeCode": "RESIDENTIAL_SHARE",
- "subcategoryCode": "SHARE",
- "address": {
- "addressLine1": "Hämeentie 6",
- "postcode": "33100",
- "postalArea": "Tampere",
- "localityCode": "FI_PIRKANMAA_TAMPERE",
- "regionCode": "FI_PIRKANMAA",
- "countryCode": "FI"
}, - "price": {
- "sellingPrice": 250000,
- "debtFreePriceAmount": 200000,
- "debtAmount": 50000,
- "currencyCode": "EUR",
- "housingCompanyDebtDate": "2022-01-01",
- "housingManagerCertificateDate": "2022-02-02"
}
}
], - "creationTime": "2022-01-01T12:00:00Z",
- "modificationTime": "2022-01-01T12:30:00Z"
}, - {
- "tradeSettlementId": "4a30bb37-96a7-47cc-9dec-f369c5651db4",
- "statusCode": "COMPLETED",
- "agencyOfficeId": "4a30bb37-96a7-47cc-9dec-f369c5651db4",
- "agents": [
- {
- "agentId": "b8b9bc07-72c6-4241-a1a4-530ead372435",
- "roleCode": "RESPONSIBLE_AGENT"
}
], - "assignmentId": "4a30bb37-96a7-47cc-9dec-f369c5651db4",
- "tradeDate": "2022-02-01",
- "digitalTrading": false,
- "assets": [
- {
- "realtyId": "4a30bb37-96a7-47cc-9dec-f369c5651db4",
- "realtyTypeCode": "RESIDENTIAL_PROPERTY",
- "subcategoryCode": "PROPERTY",
- "address": {
- "addressLine1": "Satakunnankatu 16",
- "postcode": "33100",
- "postalArea": "Tampere",
- "localityCode": "FI_PIRKANMAA_TAMPERE",
- "regionCode": "FI_PIRKANMAA",
- "countryCode": "FI"
}, - "price": {
- "sellingPrice": 150000,
- "currencyCode": "EUR"
}
}
], - "creationTime": "2022-02-01T10:00:00Z",
- "modificationTime": "2022-02-01T10:30:00Z"
}
]
}
Create a new trade settlement.
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. |
Contains the details for the trade settlement.
required | object (TradeSettlement) Details for the trade settlement. |
creationTime | string <date-time> (Timestamp) Timestamp as defined by ISO 8601 with time offset. |
{- "tradeSettlement": {
- "agencyOfficeId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
- "agents": [
- {
- "agentId": "5d2a6d47-da73-4b11-8940-27cffabb6de5",
- "roleCode": "RESPONSIBLE_AGENT"
}
], - "trade": {
- "marketingTimeInDays": 46,
- "assignmentId": "9238cf7b-b86a-49a5-b54f-cbdfcd03e9c9",
- "officialAssignmentId": "201252021",
- "assignmentStartDate": "2022-10-11",
- "acceptedOfferId": "1064fb85-6948-4a6b-8cd0-de80189e5252",
- "offerAcceptanceDate": "2022-12-04",
- "offersReceived": 7,
- "tradeDate": "2022-12-30",
- "digitalTrading": true,
- "deadlineForSigningBillOfSale": "2023-08-31T10:19:34Z",
- "compensationUponDelayedPayment": 30000,
- "description": "DIAS-kauppa osapuolten välillä"
}, - "realEstateTransferNotice": {
- "purposeOfUse": "OTHER_USE",
- "isTransferBetweenRelatives": false,
- "isShorePlot": false,
- "buildingInformation": "TRANSFER_PART_OF_BUILDINGS",
- "zoningType": "CITY_PLAN"
}, - "sellerCustomerParties": [
- {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "PERSON_PARTY",
- "primaryContact": true,
- "transferTaxDetails": {
- "interestCorporateBuyerIndividualSeller": false,
- "interestIndividualBuyerCorporateSeller": false,
- "interestCorporateBuyerSeller": false
}
}
], - "buyerCustomerParties": [
- {
- "partyId": "7172e9e1-0beb-49ab-a553-c1c3022d93f3",
- "partyTypeCode": "PERSON_PARTY",
- "primaryContact": true,
- "transferTaxDetails": {
- "bankAuthorizedToPayTransferTax": true,
- "preliminaryRulingForBuyer": false,
- "paymentIdentifier": "20231500154"
}
}, - {
- "partyId": "8a89c381-2188-412f-8226-f07649a90df4",
- "partyTypeCode": "ORGANIZATION_PARTY",
- "transferTaxDetails": {
- "bankAuthorizedToPayTransferTax": true,
- "preliminaryRulingForBuyer": false,
- "paymentIdentifier": "20231500154"
}
}
], - "consentorParties": [
- {
- "partyId": "ace3c93a-c347-41e8-a069-6a4e550258f7",
- "consentorType": "WIDOW"
}
], - "assets": [
- {
- "realtyId": "9fd9124c-e6c1-4368-9f17-6938f0e2f524",
- "realtyTypeCode": "RESIDENTIAL_SHARE",
- "subcategoryCode": "SHARE",
- "address": {
- "addressLine1": "Hämeenkatu 24",
- "stairwell": "B",
- "apartmentNumber": "55",
- "postcode": "33100",
- "postalArea": "Tampere",
- "localityCode": "FI_PIRKANMAA_TAMPERE",
- "regionCode": "FI_PIRKANMAA",
- "countryCode": "FI"
}, - "share": {
- "quantityOfShares": 65,
- "shareGroupIdentifiers": [
- "300-365"
], - "digitalShareGroupIdentifiers": [
- "OH96D7L5KFMSP421"
], - "sellerShareCertificateStatus": "ONE_OF_SELLERS_HAS_SHARE_CERTIFICATE",
- "shareCertificateFormCode": "DIGITAL",
- "shareCertificateLocation": "Tampereen Seudun Osuuspankki",
- "redemptionClauseExists": false
}, - "price": {
- "sellingPrice": 190000,
- "debtFreePriceAmount": 230000,
- "debtAmount": 40000,
- "currencyCode": "EUR",
- "housingCompanyDebtDate": "2022-12-31",
- "housingManagerCertificateDate": "2022-12-31"
}, - "termsAndConditions": {
- "shareCertificateUsedAsPledge": true,
- "pledgeHolder": "Tampereen Seudun Osuuspankki",
- "realtySoldAsLeased": true,
- "leaseConditions": {
- "rentPayableToBuyerSinceDate": "2022-12-31",
- "depositTransferDate": "2022-12-31",
- "rentAmount": 1000,
- "currencyCode": "EUR"
}
}, - "paymentTermsCode": "CASH",
- "highestRejectedOfferPrice": 165000,
- "ownershipTransferDate": "2022-12-31",
- "assetIdentifier": "A6",
- "includesAdditionalConditionForPrice": false,
- "hasEstimationForAdditionalPrice": false,
- "hspTransferEnabled": false,
- "sellerCustomerParties": [
- {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "PERSON_PARTY",
- "shareOfOwnership": {
- "divisible": 1,
- "divider": 1,
- "percentage": 100
}
}
], - "buyerCustomerParties": [
- {
- "partyId": "7172e9e1-0beb-49ab-a553-c1c3022d93f3",
- "partyTypeCode": "PERSON_PARTY",
- "shareOfOwnership": {
- "divisible": 1,
- "divider": 2,
- "percentage": 50
}, - "transferTaxRequiredCode": "TRANSFER_TAX_REQUIRED"
}, - {
- "partyId": "8a89c381-2188-412f-8226-f07649a90df4",
- "partyTypeCode": "ORGANIZATION_PARTY",
- "shareOfOwnership": {
- "divisible": 1,
- "divider": 2,
- "percentage": 50
}
}
]
}, - {
- "realtyId": "c948184b-0c53-41c3-ab45-82990bc59af2",
- "realtyTypeCode": "RESIDENTIAL_PROPERTY",
- "subcategoryCode": "PROPERTY",
- "address": {
- "addressLine1": "Hämeentie 6",
- "postcode": "33100",
- "postalArea": "Tampere",
- "localityCode": "FI_PIRKANMAA_TAMPERE",
- "regionCode": "FI_PIRKANMAA",
- "countryCode": "FI"
}, - "property": {
- "facilityId": "323-123-5423-8234-L1",
- "holdingTypeCode": "LEASEHOLD",
- "realEstateTypeCode": "WHOLE_PROPERTY",
- "propertyId": "323-123-5423-8234-L2",
- "mortgageDeedCodes": [
- "AAA",
- "BBB"
], - "nonTransferableMortgageDeedCodes": [
- "CCC",
- "DDD"
]
}, - "price": {
- "debtFreePriceAmount": 120000,
- "currencyCode": "EUR"
}, - "termsAndConditions": {
- "realtySoldAsLeased": true,
- "leaseConditions": {
- "rentPayableToBuyerSinceDate": "2023-01-31",
- "depositTransferDate": "2022-12-31",
- "rentAmount": 900,
- "currencyCode": "EUR"
}
}, - "paymentTermsCode": "CASH",
- "highestRejectedOfferPrice": 99000,
- "ownershipTransferDate": "2022-12-31",
- "includesAdditionalConditionForPrice": false,
- "hasEstimationForAdditionalPrice": false,
- "sellerCustomerParties": [
- {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "PERSON_PARTY",
- "shareOfOwnership": {
- "divisible": 1,
- "divider": 1,
- "percentage": 100
}
}
], - "buyerCustomerParties": [
- {
- "partyId": "7172e9e1-0beb-49ab-a553-c1c3022d93f3",
- "partyTypeCode": "PERSON_PARTY",
- "shareOfOwnership": {
- "divisible": 1,
- "divider": 2,
- "percentage": 50
}, - "transferTaxRequiredCode": "TRANSFER_TAX_REQUIRED"
}, - {
- "partyId": "8a89c381-2188-412f-8226-f07649a90df4",
- "partyTypeCode": "ORGANIZATION_PARTY",
- "shareOfOwnership": {
- "divisible": 1,
- "divider": 2,
- "percentage": 50
}
}
]
}
]
}
}
{- "tradeSettlementId": "4a30bb37-96a7-47cc-9dec-f369c5651db4"
}
Fetch details for the specified trade settlement.
tradeSettlementId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: 6d9d4946-d170-4730-b818-37901edb961b Unique trade settlement identifier in UUID format. |
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. |
{- "tradeSettlementId": "4a30bb37-96a7-47cc-9dec-f369c5651db4",
- "statusCode": "COMPLETED",
- "tradeSettlement": {
- "agencyOfficeId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
- "agents": [
- {
- "agentId": "5d2a6d47-da73-4b11-8940-27cffabb6de5",
- "roleCode": "RESPONSIBLE_AGENT"
}
], - "trade": {
- "marketingTimeInDays": 46,
- "assignmentId": "9238cf7b-b86a-49a5-b54f-cbdfcd03e9c9",
- "officialAssignmentId": "201252021",
- "assignmentStartDate": "2022-10-11",
- "acceptedOfferId": "1064fb85-6948-4a6b-8cd0-de80189e5252",
- "offerAcceptanceDate": "2022-12-04",
- "offersReceived": 7,
- "tradeDate": "2022-12-30",
- "digitalTrading": true,
- "deadlineForSigningBillOfSale": "2023-08-31T10:19:34Z",
- "compensationUponDelayedPayment": 30000,
- "description": "DIAS-kauppa osapuolten välillä"
}, - "realEstateTransferNotice": {
- "purposeOfUse": "OTHER_USE",
- "isTransferBetweenRelatives": false,
- "isShorePlot": false,
- "buildingInformation": "TRANSFER_PART_OF_BUILDINGS",
- "zoningType": "CITY_PLAN"
}, - "sellerCustomerParties": [
- {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "PERSON_PARTY",
- "primaryContact": true,
- "transferTaxDetails": {
- "interestCorporateBuyerIndividualSeller": false,
- "interestIndividualBuyerCorporateSeller": false,
- "interestCorporateBuyerSeller": false
}
}
], - "buyerCustomerParties": [
- {
- "partyId": "7172e9e1-0beb-49ab-a553-c1c3022d93f3",
- "partyTypeCode": "PERSON_PARTY",
- "primaryContact": true,
- "transferTaxDetails": {
- "bankAuthorizedToPayTransferTax": true,
- "preliminaryRulingForBuyer": false,
- "paymentIdentifier": "20231500154"
}
}, - {
- "partyId": "8a89c381-2188-412f-8226-f07649a90df4",
- "partyTypeCode": "ORGANIZATION_PARTY",
- "transferTaxDetails": {
- "bankAuthorizedToPayTransferTax": true,
- "preliminaryRulingForBuyer": false,
- "paymentIdentifier": "20231500154"
}
}
], - "consentorParties": [
- {
- "partyId": "ace3c93a-c347-41e8-a069-6a4e550258f7",
- "consentorType": "WIDOW"
}
], - "assets": [
- {
- "realtyId": "9fd9124c-e6c1-4368-9f17-6938f0e2f524",
- "realtyTypeCode": "RESIDENTIAL_SHARE",
- "subcategoryCode": "SHARE",
- "address": {
- "addressLine1": "Hämeenkatu 24",
- "stairwell": "B",
- "apartmentNumber": "55",
- "postcode": "33100",
- "postalArea": "Tampere",
- "localityCode": "FI_PIRKANMAA_TAMPERE",
- "regionCode": "FI_PIRKANMAA",
- "countryCode": "FI"
}, - "share": {
- "quantityOfShares": 65,
- "shareGroupIdentifiers": [
- "300-365"
], - "digitalShareGroupIdentifiers": [
- "OH96D7L5KFMSP421"
], - "sellerShareCertificateStatus": "ONE_OF_SELLERS_HAS_SHARE_CERTIFICATE",
- "shareCertificateFormCode": "DIGITAL",
- "shareCertificateLocation": "Tampereen Seudun Osuuspankki",
- "redemptionClauseExists": false
}, - "price": {
- "sellingPrice": 190000,
- "debtFreePriceAmount": 230000,
- "debtAmount": 40000,
- "currencyCode": "EUR",
- "housingCompanyDebtDate": "2022-12-31",
- "housingManagerCertificateDate": "2022-12-31"
}, - "termsAndConditions": {
- "shareCertificateUsedAsPledge": true,
- "pledgeHolder": "Tampereen Seudun Osuuspankki",
- "realtySoldAsLeased": true,
- "leaseConditions": {
- "rentPayableToBuyerSinceDate": "2022-12-31",
- "depositTransferDate": "2022-12-31",
- "rentAmount": 1000,
- "currencyCode": "EUR"
}
}, - "paymentTermsCode": "CASH",
- "highestRejectedOfferPrice": 165000,
- "ownershipTransferDate": "2022-12-31",
- "assetIdentifier": "A6",
- "includesAdditionalConditionForPrice": false,
- "hasEstimationForAdditionalPrice": false,
- "hspTransferEnabled": false,
- "sellerCustomerParties": [
- {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "PERSON_PARTY",
- "shareOfOwnership": {
- "divisible": 1,
- "divider": 1,
- "percentage": 100
}
}
], - "buyerCustomerParties": [
- {
- "partyId": "7172e9e1-0beb-49ab-a553-c1c3022d93f3",
- "partyTypeCode": "PERSON_PARTY",
- "shareOfOwnership": {
- "divisible": 1,
- "divider": 2,
- "percentage": 50
}, - "transferTaxRequiredCode": "TRANSFER_TAX_REQUIRED"
}, - {
- "partyId": "8a89c381-2188-412f-8226-f07649a90df4",
- "partyTypeCode": "ORGANIZATION_PARTY",
- "shareOfOwnership": {
- "divisible": 1,
- "divider": 2,
- "percentage": 50
}
}
]
}, - {
- "realtyId": "c948184b-0c53-41c3-ab45-82990bc59af2",
- "realtyTypeCode": "RESIDENTIAL_PROPERTY",
- "subcategoryCode": "PROPERTY",
- "address": {
- "addressLine1": "Hämeentie 6",
- "postcode": "33100",
- "postalArea": "Tampere",
- "localityCode": "FI_PIRKANMAA_TAMPERE",
- "regionCode": "FI_PIRKANMAA",
- "countryCode": "FI"
}, - "property": {
- "facilityId": "323-123-5423-8234-L1",
- "holdingTypeCode": "LEASEHOLD",
- "realEstateTypeCode": "WHOLE_PROPERTY",
- "propertyId": "323-123-5423-8234-L2",
- "mortgageDeedCodes": [
- "AAA",
- "BBB"
], - "nonTransferableMortgageDeedCodes": [
- "CCC",
- "DDD"
]
}, - "price": {
- "debtFreePriceAmount": 120000,
- "currencyCode": "EUR"
}, - "termsAndConditions": {
- "realtySoldAsLeased": true,
- "leaseConditions": {
- "rentPayableToBuyerSinceDate": "2023-01-31",
- "depositTransferDate": "2022-12-31",
- "rentAmount": 900,
- "currencyCode": "EUR"
}
}, - "paymentTermsCode": "CASH",
- "highestRejectedOfferPrice": 99000,
- "ownershipTransferDate": "2022-12-31",
- "includesAdditionalConditionForPrice": false,
- "hasEstimationForAdditionalPrice": false,
- "sellerCustomerParties": [
- {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "PERSON_PARTY",
- "shareOfOwnership": {
- "divisible": 1,
- "divider": 1,
- "percentage": 100
}
}
], - "buyerCustomerParties": [
- {
- "partyId": "8a89c381-2188-412f-8226-f07649a90df4",
- "partyTypeCode": "ORGANIZATION_PARTY",
- "shareOfOwnership": {
- "divisible": 1,
- "divider": 1,
- "percentage": 100
}
}
]
}
]
}, - "creationTime": "2022-12-30T17:32:28Z",
- "modificationTime": "2022-12-30T17:32:28Z"
}
Update details for the specified trade settlement. The trade settlement contents can be updated only if it is in a IN_PROGRESS
state.
tradeSettlementId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: 6d9d4946-d170-4730-b818-37901edb961b Unique trade settlement identifier in UUID format. |
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. |
Contains the details for the trade settlement.
tradeSettlementId | string <uuid> (TradeSettlementId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... A unique id which identifies the trade settlement. |
statusCode | string (TradeSettlementStatusCode) Enum: "IN_PROGRESS" "COMPLETED" "DISMANTLED" Trade settlement status. The status defines what actions can be performed for trade settlement. Possible values are:
|
required | object (TradeSettlement) Details for the trade settlement. |
{- "tradeSettlementId": "4a30bb37-96a7-47cc-9dec-f369c5651db4",
- "statusCode": "COMPLETED",
- "tradeSettlement": {
- "agencyOfficeId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
- "agents": [
- {
- "agentId": "5d2a6d47-da73-4b11-8940-27cffabb6de5",
- "roleCode": "RESPONSIBLE_AGENT"
}
], - "trade": {
- "marketingTimeInDays": 46,
- "assignmentId": "9238cf7b-b86a-49a5-b54f-cbdfcd03e9c9",
- "officialAssignmentId": "201252021",
- "assignmentStartDate": "2022-10-11",
- "acceptedOfferId": "1064fb85-6948-4a6b-8cd0-de80189e5252",
- "offerAcceptanceDate": "2022-12-04",
- "offersReceived": 7,
- "tradeDate": "2022-12-30",
- "digitalTrading": true,
- "deadlineForSigningBillOfSale": "2023-08-31T10:19:34Z",
- "compensationUponDelayedPayment": 30000,
- "description": "DIAS-kauppa osapuolten välillä"
}, - "realEstateTransferNotice": {
- "purposeOfUse": "OTHER_USE",
- "isTransferBetweenRelatives": false,
- "isShorePlot": false,
- "buildingInformation": "TRANSFER_PART_OF_BUILDINGS",
- "zoningType": "CITY_PLAN"
}, - "sellerCustomerParties": [
- {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "PERSON_PARTY",
- "primaryContact": true,
- "transferTaxDetails": {
- "interestCorporateBuyerIndividualSeller": false,
- "interestIndividualBuyerCorporateSeller": false,
- "interestCorporateBuyerSeller": false
}
}
], - "buyerCustomerParties": [
- {
- "partyId": "7172e9e1-0beb-49ab-a553-c1c3022d93f3",
- "partyTypeCode": "PERSON_PARTY",
- "primaryContact": true,
- "transferTaxDetails": {
- "bankAuthorizedToPayTransferTax": true,
- "preliminaryRulingForBuyer": false,
- "paymentIdentifier": "20231500154"
}
}, - {
- "partyId": "8a89c381-2188-412f-8226-f07649a90df4",
- "partyTypeCode": "ORGANIZATION_PARTY",
- "transferTaxDetails": {
- "bankAuthorizedToPayTransferTax": true,
- "preliminaryRulingForBuyer": false,
- "paymentIdentifier": "20231500154"
}
}
], - "consentorParties": [
- {
- "partyId": "ace3c93a-c347-41e8-a069-6a4e550258f7",
- "consentorType": "WIDOW"
}
], - "assets": [
- {
- "realtyId": "9fd9124c-e6c1-4368-9f17-6938f0e2f524",
- "realtyTypeCode": "RESIDENTIAL_SHARE",
- "subcategoryCode": "SHARE",
- "address": {
- "addressLine1": "Hämeenkatu 24",
- "stairwell": "B",
- "apartmentNumber": "55",
- "postcode": "33100",
- "postalArea": "Tampere",
- "localityCode": "FI_PIRKANMAA_TAMPERE",
- "regionCode": "FI_PIRKANMAA",
- "countryCode": "FI"
}, - "share": {
- "quantityOfShares": 65,
- "shareGroupIdentifiers": [
- "300-365"
], - "digitalShareGroupIdentifiers": [
- "OH96D7L5KFMSP421"
], - "sellerShareCertificateStatus": "ONE_OF_SELLERS_HAS_SHARE_CERTIFICATE",
- "shareCertificateFormCode": "DIGITAL",
- "shareCertificateLocation": "Tampereen Seudun Osuuspankki",
- "redemptionClauseExists": false
}, - "price": {
- "sellingPrice": 190000,
- "debtFreePriceAmount": 230000,
- "debtAmount": 40000,
- "currencyCode": "EUR",
- "housingCompanyDebtDate": "2022-12-31",
- "housingManagerCertificateDate": "2022-12-31"
}, - "termsAndConditions": {
- "shareCertificateUsedAsPledge": true,
- "pledgeHolder": "Tampereen Seudun Osuuspankki",
- "realtySoldAsLeased": true,
- "leaseConditions": {
- "rentPayableToBuyerSinceDate": "2022-12-31",
- "depositTransferDate": "2022-12-31",
- "rentAmount": 1000,
- "currencyCode": "EUR"
}
}, - "paymentTermsCode": "CASH",
- "highestRejectedOfferPrice": 165000,
- "ownershipTransferDate": "2022-12-31",
- "assetIdentifier": "A6",
- "includesAdditionalConditionForPrice": false,
- "hasEstimationForAdditionalPrice": false,
- "hspTransferEnabled": false,
- "sellerCustomerParties": [
- {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "PERSON_PARTY",
- "shareOfOwnership": {
- "divisible": 1,
- "divider": 1,
- "percentage": 100
}
}
], - "buyerCustomerParties": [
- {
- "partyId": "7172e9e1-0beb-49ab-a553-c1c3022d93f3",
- "partyTypeCode": "PERSON_PARTY",
- "shareOfOwnership": {
- "divisible": 1,
- "divider": 2,
- "percentage": 50
}, - "transferTaxRequiredCode": "TRANSFER_TAX_REQUIRED"
}, - {
- "partyId": "8a89c381-2188-412f-8226-f07649a90df4",
- "partyTypeCode": "ORGANIZATION_PARTY",
- "shareOfOwnership": {
- "divisible": 1,
- "divider": 2,
- "percentage": 50
}
}
]
}, - {
- "realtyId": "c948184b-0c53-41c3-ab45-82990bc59af2",
- "realtyTypeCode": "RESIDENTIAL_PROPERTY",
- "subcategoryCode": "PROPERTY",
- "address": {
- "addressLine1": "Hämeentie 6",
- "postcode": "33100",
- "postalArea": "Tampere",
- "localityCode": "FI_PIRKANMAA_TAMPERE",
- "regionCode": "FI_PIRKANMAA",
- "countryCode": "FI"
}, - "property": {
- "facilityId": "323-123-5423-8234-L1",
- "holdingTypeCode": "LEASEHOLD",
- "realEstateTypeCode": "WHOLE_PROPERTY",
- "propertyId": "323-123-5423-8234-L2",
- "mortgageDeedCodes": [
- "AAA",
- "BBB"
], - "nonTransferableMortgageDeedCodes": [
- "CCC",
- "DDD"
]
}, - "price": {
- "debtFreePriceAmount": 120000,
- "currencyCode": "EUR"
}, - "termsAndConditions": {
- "realtySoldAsLeased": true,
- "leaseConditions": {
- "rentPayableToBuyerSinceDate": "2023-01-31",
- "depositTransferDate": "2022-12-31",
- "rentAmount": 900,
- "currencyCode": "EUR"
}
}, - "paymentTermsCode": "CASH",
- "highestRejectedOfferPrice": 99000,
- "ownershipTransferDate": "2022-12-31",
- "includesAdditionalConditionForPrice": false,
- "hasEstimationForAdditionalPrice": false,
- "sellerCustomerParties": [
- {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "PERSON_PARTY",
- "shareOfOwnership": {
- "divisible": 1,
- "divider": 1,
- "percentage": 100
}
}
], - "buyerCustomerParties": [
- {
- "partyId": "7172e9e1-0beb-49ab-a553-c1c3022d93f3",
- "partyTypeCode": "PERSON_PARTY",
- "shareOfOwnership": {
- "divisible": 1,
- "divider": 2,
- "percentage": 50
}, - "transferTaxRequiredCode": "TRANSFER_TAX_REQUIRED"
}, - {
- "partyId": "8a89c381-2188-412f-8226-f07649a90df4",
- "partyTypeCode": "ORGANIZATION_PARTY",
- "shareOfOwnership": {
- "divisible": 1,
- "divider": 2,
- "percentage": 50
}
}
]
}
]
}
}
{ }
Fetch contents of the sales deed for given trade settlement.
tradeSettlementId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: 6d9d4946-d170-4730-b818-37901edb961b Unique trade settlement identifier in UUID format. |
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. |
{- "tradeSettlementId": "2bad0571-1d9e-49b6-af7a-61ab73f330b6",
- "salesDeedContent": "# **KAUPPAKIRJA**\r\n\r\n\r\n\r\n# KAUPAN OSAPUOLET\r\n\r\n\r\n\r\n**Myyjä:** Etunimi Sukunimi\r\n\r\n**Henkilötunnus:**...",
- "salesDeedDocumentId": "20a61558-71a7-4672-9533-8b3b8a5812dc",
- "salesDeedContentModificationTime": "2024-08-24T14:59:22Z",
- "salesDeedDocumentCreationTime": "2024-08-24T15:01:22Z"
}
Save contents of sales deed for given trade settlement. Note: Related sales deed PDF document is not updated automatically.
tradeSettlementId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: 6d9d4946-d170-4730-b818-37901edb961b Unique trade settlement identifier in UUID format. |
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. |
Contains the content of the sales deed.
salesDeedContent required | string <= 100000 characters JSON escaped markdown content for sales deed. |
{- "salesDeedContent": "# **KAUPPAKIRJA**\r\n\r\n\r\n\r\n# KAUPAN OSAPUOLET\r\n\r\n\r\n\r\n**Myyjä:**..."
}
{- "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"
}
]
}
Generates a PDF document using sales deed content and saves it to Document API. If trade settlement has existing sales deed PDF it will be overwritten.
tradeSettlementId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: 6d9d4946-d170-4730-b818-37901edb961b Unique trade settlement identifier in UUID format. |
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. |
Empty body
{ }
{- "salesDeedDocumentId": "77ac2031-8c8f-43e1-8ab6-6f0dd7c1d1d6"
}
Fetch contents of the transfer terms for given trade settlement.
tradeSettlementId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: 6d9d4946-d170-4730-b818-37901edb961b Unique trade settlement identifier in UUID format. |
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. |
{- "tradeSettlementId": "2bad0571-1d9e-49b6-af7a-61ab73f330b6",
- "transferTermsContent": "# **KAUPAN EHDOT**\r\n\r\n\r\n\r\n# KAUPAN OSAPUOLET\r\n\r\n\r\n\r\n**Myyjä:** Etunimi Sukunimi\r\n\r\n**Henkilötunnus:**...",
- "transferTermsDocumentId": "20a61558-71a7-4672-9533-8b3b8a5812dc",
- "transferTermsContentModificationTime": "2024-08-24T14:59:22Z",
- "transferTermsDocumentCreationTime": "2024-08-24T15:01:22Z"
}
Save contents of transfer terms for given trade settlement. Note: Related transfer terms PDF document is not updated automatically.
tradeSettlementId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: 6d9d4946-d170-4730-b818-37901edb961b Unique trade settlement identifier in UUID format. |
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. |
Contains the content of the transfer terms.
transferTermsContent required | string JSON escaped markdown content for transfer terms. |
{- "transferTermsContent": "# **KAUPAN EHDOT**\r\n\r\n\r\n\r\n# KAUPAN OSAPUOLET\r\n\r\n\r\n\r\n**Myyjä:**..."
}
{- "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"
}
]
}
Generates a PDF document using transfer terms content and saves it to Document API. If trade settlement has existing sales deed PDF it will be overwritten.
tradeSettlementId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: 6d9d4946-d170-4730-b818-37901edb961b Unique trade settlement identifier in UUID format. |
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. |
Empty body
{ }
{- "transferTermsDocumentId": "77ac2031-8c8f-43e1-8ab6-6f0dd7c1d1d6"
}
Rental Settlement API allows you to initiate and complete a rental settlement for a set of assets.
Create a new rental settlement.
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. |
Contains the details for the rental settlement.
required | object (RentalSettlement) Details for the rental settlement. |
creationTime | string <date-time> (Timestamp) Timestamp as defined by ISO 8601 with time offset. |
{- "rentalSettlement": {
- "agencyOfficeId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
- "agents": [
- {
- "agentId": "5d2a6d47-da73-4b11-8940-27cffabb6de5",
- "roleCode": "RESPONSIBLE_AGENT"
}
], - "rental": {
- "assignmentId": "9238cf7b-b86a-49a5-b54f-cbdfcd03e9c9",
- "assignmentStartDate": "2023-10-31",
- "marketingTimeInDays": 16,
- "rentalDate": "2023-11-18",
- "rentalStartDate": "2023-12-31",
- "description": "Vuokrasopimuksessa useampi vuokranantaja"
}, - "lessorCustomerParties": [
- {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "PERSON_PARTY"
}, - {
- "partyId": "fed513ce-2626-447d-91ad-d8788dc89447",
- "partyTypeCode": "PERSON_PARTY"
}
], - "tenantCustomerParties": [
- {
- "partyId": "a4f0f4d1-aa16-4bc7-92ce-7edac11085fc",
- "partyTypeCode": "PERSON_PARTY",
- "underageTenant": true,
- "guardianParties": [
- {
- "partyId": "ddf2c76a-d9f8-446a-b80f-c781736dab89",
- "partyTypeCode": "PERSON_PARTY"
}
]
}
], - "otherResidentDescription": "Kolme lasta",
- "assets": [
- {
- "realtyId": "9fd9124c-e6c1-4368-9f17-6938f0e2f524",
- "realtyTypeCode": "RESIDENTIAL_SHARE",
- "subcategoryCode": "SHARE",
- "address": {
- "addressLine1": "Yliopistonkatu 55",
- "stairwell": "C",
- "apartmentNumber": "55",
- "postcode": "33100",
- "postalArea": "Tampere",
- "localityName": "Tampere",
- "localityCode": "FI_PIRKANMAA_TAMPERE",
- "regionCode": "FI_PIRKANMAA",
- "countryCode": "FI"
}, - "rentalPrice": {
- "monthlyRent": 890,
- "currencyCode": "EUR"
}
}
]
}
}
{- "rentalSettlementId": "48978afa-bebb-4226-8ff0-c38ec5e05512"
}
Search rental settlements matching specified query parameters. You can combine the search criteria, for example to search for completed rental settlements by a specified agency office.
realtyId | string <uuid> Example: realtyId=b482a6a0-34cb-41e1-9817-1f734d7d3a06 Search by realty identifier to get a list of rental settlements for the realty. |
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 rental settlements the for agent. |
agencyOfficeId | Array of strings <uuid> (AgencyOfficeId) [^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...] Example: agencyOfficeId=212114ec-819e-483c-a8e0-f82289ac6e19 Search by the agency office identifiers to get a list of rental settlements that belong to certain agency offices. |
statusCode | Array of strings (RentalSettlementStatusCode) Items Enum: "IN_PROGRESS" "COMPLETED" "DISMANTLED" Example: statusCode=COMPLETED Search by the status code to fetch rental settlements having specific statuses. |
modifiedAfter | string <date-time> (Timestamp) Example: modifiedAfter=2024-09-05T13:50:22.204Z Search by a timestamp to get a list of rental settlements which were modified after the specified time. |
startIndex | integer <int32> >= 0 Default: 0 Example: startIndex=20 Return rental settlements starting from this index. Index starts from 0. |
size | integer <int32> [ 1 .. 100 ] Default: 50 Example: size=40 Specify the maximum number of items to return for this request. |
sort | Array of strings Example: sort=validAfter|desc Sort rental settlements based on the specified fields. Each field to be sorted must also include a sort order as follows:
|
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. |
{- "totalCount": 8,
- "rentalSettlements": [
- {
- "rentalSettlementId": "48978afa-bebb-4226-8ff0-c38ec5e05512",
- "statusCode": "IN_PROGRESS",
- "agencyOfficeId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
- "agents": [
- {
- "agentId": "5d2a6d47-da73-4b11-8940-27cffabb6de5",
- "roleCode": "RESPONSIBLE_AGENT"
}
], - "assignmentId": "9238cf7b-b86a-49a5-b54f-cbdfcd03e9c9",
- "rentalDate": "2022-12-31",
- "assets": [
- {
- "realtyId": "9fd9124c-e6c1-4368-9f17-6938f0e2f524",
- "realtyTypeCode": "RESIDENTIAL_SHARE",
- "subcategoryCode": "SHARE",
- "address": {
- "addressLine1": "Yliopistonkatu 55",
- "stairwell": "C",
- "apartmentNumber": "55",
- "postcode": "33100",
- "postalArea": "Tampere",
- "localityName": "Tampere",
- "localityCode": "FI_PIRKANMAA_TAMPERE",
- "regionCode": "FI_PIRKANMAA",
- "countryCode": "FI"
}, - "rentalPrice": {
- "monthlyRent": 690,
- "currencyCode": "EUR"
}
}
], - "creationTime": "2023-11-17T17:23:08Z",
- "modificationTime": "2023-11-19T13:32:28Z"
}
]
}
Fetch details for the specified rental settlement.
rentalSettlementId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: a82e4fdd-a3d8-440b-987c-b1c24f62d3b6 Unique rental settlement identifier in UUID format. |
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. |
{- "rentalSettlementId": "48978afa-bebb-4226-8ff0-c38ec5e05512",
- "statusCode": "IN_PROGRESS",
- "rentalSettlement": {
- "agencyOfficeId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
- "agents": [
- {
- "agentId": "5d2a6d47-da73-4b11-8940-27cffabb6de5",
- "roleCode": "RESPONSIBLE_AGENT"
}
], - "rental": {
- "assignmentId": "9238cf7b-b86a-49a5-b54f-cbdfcd03e9c9",
- "assignmentStartDate": "2023-10-31",
- "marketingTimeInDays": 16,
- "rentalDate": "2023-11-18",
- "rentalStartDate": "2023-12-31",
- "description": "Vuokrasopimuksessa useampi vuokranantaja"
}, - "lessorCustomerParties": [
- {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "PERSON_PARTY"
}, - {
- "partyId": "fed513ce-2626-447d-91ad-d8788dc89447",
- "partyTypeCode": "PERSON_PARTY"
}
], - "tenantCustomerParties": [
- {
- "partyId": "a4f0f4d1-aa16-4bc7-92ce-7edac11085fc",
- "partyTypeCode": "PERSON_PARTY",
- "underageTenant": true,
- "guardianParties": [
- {
- "partyId": "ddf2c76a-d9f8-446a-b80f-c781736dab89",
- "partyTypeCode": "PERSON_PARTY"
}
]
}
], - "otherResidentDescription": "Kolme lasta",
- "assets": [
- {
- "realtyId": "9fd9124c-e6c1-4368-9f17-6938f0e2f524",
- "realtyTypeCode": "RESIDENTIAL_SHARE",
- "subcategoryCode": "SHARE",
- "address": {
- "addressLine1": "Yliopistonkatu 55",
- "stairwell": "C",
- "apartmentNumber": "55",
- "postcode": "33100",
- "postalArea": "Tampere",
- "localityName": "Tampere",
- "localityCode": "FI_PIRKANMAA_TAMPERE",
- "regionCode": "FI_PIRKANMAA",
- "countryCode": "FI"
}, - "rentalPrice": {
- "monthlyRent": 890,
- "currencyCode": "EUR"
}
}
]
}, - "creationTime": "2023-11-17T17:23:08Z",
- "modificationTime": "2023-11-19T13:32:28Z"
}
Update details for the specified rental settlement. The rental settlement contents can be updated only if it is in a IN_PROGRESS
state.
rentalSettlementId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: a82e4fdd-a3d8-440b-987c-b1c24f62d3b6 Unique rental settlement identifier in UUID format. |
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. |
Contains the details for the rental settlement.
rentalSettlementId | string <uuid> (RentalSettlementId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... A unique id that identifies the rental settlement. |
statusCode | string (RentalSettlementStatusCode) Enum: "IN_PROGRESS" "COMPLETED" "DISMANTLED" Rental settlement status. The status defines what actions can be performed for rental settlement. Possible values are:
|
required | object (RentalSettlement) Details for the rental settlement. |
{- "rentalSettlementId": "48978afa-bebb-4226-8ff0-c38ec5e05512",
- "statusCode": "IN_PROGRESS",
- "rentalSettlement": {
- "agencyOfficeId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
- "agents": [
- {
- "agentId": "5d2a6d47-da73-4b11-8940-27cffabb6de5",
- "roleCode": "RESPONSIBLE_AGENT"
}
], - "rental": {
- "assignmentId": "9238cf7b-b86a-49a5-b54f-cbdfcd03e9c9",
- "assignmentStartDate": "2023-10-31",
- "marketingTimeInDays": 16,
- "rentalDate": "2023-11-18",
- "rentalStartDate": "2023-12-31",
- "description": "Vuokrasopimuksessa useampi vuokranantaja"
}, - "lessorCustomerParties": [
- {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "PERSON_PARTY"
}, - {
- "partyId": "fed513ce-2626-447d-91ad-d8788dc89447",
- "partyTypeCode": "PERSON_PARTY"
}
], - "tenantCustomerParties": [
- {
- "partyId": "a4f0f4d1-aa16-4bc7-92ce-7edac11085fc",
- "partyTypeCode": "PERSON_PARTY",
- "underageTenant": true,
- "guardianParties": [
- {
- "partyId": "ddf2c76a-d9f8-446a-b80f-c781736dab89",
- "partyTypeCode": "PERSON_PARTY"
}
]
}
], - "otherResidentDescription": "Kolme lasta",
- "assets": [
- {
- "realtyId": "9fd9124c-e6c1-4368-9f17-6938f0e2f524",
- "realtyTypeCode": "RESIDENTIAL_SHARE",
- "subcategoryCode": "SHARE",
- "address": {
- "addressLine1": "Yliopistonkatu 55",
- "stairwell": "C",
- "apartmentNumber": "55",
- "postcode": "33100",
- "postalArea": "Tampere",
- "localityName": "Tampere",
- "localityCode": "FI_PIRKANMAA_TAMPERE",
- "regionCode": "FI_PIRKANMAA",
- "countryCode": "FI"
}, - "rentalPrice": {
- "monthlyRent": 890,
- "currencyCode": "EUR"
}
}
]
}
}
{ }
Fetch contents of the lease agreement for given rental settlement.
rentalSettlementId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: a82e4fdd-a3d8-440b-987c-b1c24f62d3b6 Unique rental settlement identifier in UUID format. |
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. |
{- "rentalSettlementId": "2bad0571-1d9e-49b6-af7a-61ab73f330b6",
- "leaseAgreementContent": "# **VUOKRASOPIMUS**\r\n\r\n\r\n\r\n# OSAPUOLET\r\n\r\n\r\n\r\n**Vuokraaja:** Etunimi Sukunimi\r\n\r\n**Henkilötunnus:**...",
- "leaseAgreementDocumentId": "20a61558-71a7-4672-9533-8b3b8a5812dc",
- "leaseAgreementContentModificationTime": "2024-08-24T14:59:22Z",
- "leaseAgreementDocumentCreationTime": "2024-08-24T15:01:22Z"
}
Save contents of lease agreement for given rental settlement. Note: Related lease agreement PDF document is not updated automatically.
rentalSettlementId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: a82e4fdd-a3d8-440b-987c-b1c24f62d3b6 Unique rental settlement identifier in UUID format. |
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. |
Contains the content of the lease agreement.
leaseAgreementContent required | string JSON escaped markdown content for lease agreement. |
{- "leaseAgreementContent": "# **KAUPPAKIRJA**\r\n\r\n\r\n\r\n# KAUPAN OSAPUOLET\r\n\r\n\r\n\r\n**Myyjä:**..."
}
{- "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"
}
]
}
Generates a PDF document using lease agreement content and saves it to Document API. If rental settlement has existing lease agreement PDF it will be overwritten.
rentalSettlementId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: a82e4fdd-a3d8-440b-987c-b1c24f62d3b6 Unique rental settlement identifier in UUID format. |
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. |
Empty body
{ }
{- "leaseAgreementDocumentId": "77ac2031-8c8f-43e1-8ab6-6f0dd7c1d1d6"
}
Billing API allows you to summarize costs and invoice them to the accounting customer parties.
Billing includes the accounting customer parties who will be invoiced for the costs. If the costs are the basis for commissions, the billing also includes a summary of commissions.
Create a new billing which includes items to be invoiced.
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. |
Contains the details for the billing.
required | object (Billing) Billing entity summarizes the costs and commissions associated with the trade settlement or some other service conducted by the agent. The costs have typically incurred as a result of a sale assignment or a purchase assignment. The costs to be invoiced will be paid by the accounting customer parties. The one of more accounting customer party may be different than the seller(s) in a sales assignment or the buyer(s) in a purchase assignment. If a down payment was paid for the agency’s dedicated account, down payment will be deducted from the commission as part of allowance charges. If the down payment was more than the commission amount, then a credit note must be sent to the accounting customer party. |
creationTime | string <date-time> (Timestamp) Timestamp as defined by ISO 8601 with time offset. |
{- "billing": {
- "billingReasonCode": "CLEARING",
- "agencyOfficeId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
- "assignmentId": "9238cf7b-b86a-49a5-b54f-cbdfcd03e9c9",
- "officialAssignmentId": "201252021",
- "tradeSettlementId": "4a30bb37-96a7-47cc-9dec-f369c5651db4",
- "documentCurrencyCode": "EUR",
- "actualDeliveryDate": "2022-12-05",
- "issueDate": "2022-12-10",
- "dueDate": "2022-12-24",
- "note": "Toimeksiantopalkkio kahden kohteen myynnistä",
- "paymentTerms": "Netto 14 päivää",
- "downPayment": {
- "downPaymentAmount": 100,
- "paymentMethodCode": "PAYMENT_TO_BANK_ACCOUNT",
- "currencyCode": "EUR",
- "dueDate": "2022-09-30"
}, - "latePaymentFee": 5,
- "noticePeriod": 14,
- "allowanceCharges": [
- {
- "chargeIndicator": false,
- "reasonCode": "DISCOUNT",
- "allowanceChargeReason": "Alennus, koska ostaja löytyi ilman markkinointia",
- "multiplierFactorNumeric": 10,
- "amount": 30,
- "taxInclusiveAmount": 37.2,
- "baseAmount": 300,
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}
], - "taxTotal": {
- "taxAmount": 64.8,
- "currencyCode": "EUR",
- "taxSubtotals": [
- {
- "taxableAmount": 270,
- "taxAmount": 64.8,
- "currencyCode": "EUR",
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}
]
}, - "legalMonetaryTotal": {
- "lineExtensionAmount": 270,
- "taxInclusiveAmount": 372,
- "allowanceTotalAmount": 30,
- "prepaidAmount": 100,
- "payableAmount": 234.8
}, - "costItems": [
- {
- "id": "01",
- "excludeCommissions": false,
- "excludeRoyalties": false,
- "invoicedQuantity": {
- "quantity": 2,
- "unitCode": "E49"
}, - "item": {
- "name": "Kauppakirja",
- "standardItemId": "DOCUMENT_MANAGEMENT",
- "sellersItemId": "EXPENSE_DOCUMENTS",
- "description": "Kauppakirjan valmistelu ja kirjoitus",
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}, - "price": {
- "priceAmount": 150,
- "taxInclusiveAmount": 186
}, - "lineExtensionAmount": 270,
- "allowanceCharges": [
- {
- "chargeIndicator": false,
- "reasonCode": "DISCOUNT",
- "allowanceChargeReason": "Alennus, koska ostaja löytyi ilman markkinointia",
- "multiplierFactorNumeric": 10,
- "amount": 30,
- "taxInclusiveAmount": 37.2,
- "baseAmount": 300,
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}
]
}
], - "accountingCustomerParties": [
- {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "PERSON_PARTY",
- "partyName": "Matti Virtanen",
- "officialIdentifiers": [
- {
- "officialId": "FI06412765",
- "schemeId": "VAT"
}
], - "address": {
- "addressLine1": "Yliopistonkatu 55",
- "addressLine2": "Tampere-talo",
- "postcode": "33100",
- "postalArea": "Tampere",
- "localityName": "Tampere",
- "regionCode": "FI_PIRKANMAA",
- "countryCode": "FI"
}, - "invoicing": {
- "invoicingMethodCode": "EINVOICING",
- "eInvoicing": {
- "eInvoicingAddress": "003702472382",
- "operatorId": "E204503",
- "operatorName": "OpusCapita Solutions Oy"
}
}, - "costSharingPercentage": 100
}
], - "commissionSummary": {
- "totalAmount": 260,
- "agentCommissions": [
- {
- "agent": {
- "agentId": "5d2a6d47-da73-4b11-8940-27cffabb6de5",
- "agencyOfficeId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
- "roleCode": "RESPONSIBLE_AGENT",
- "firstName": "Veikko",
- "lastName": "Viljanen"
}, - "totalAmount": 260,
- "sharePercentage": 100
}
]
}, - "invoices": [
- {
- "invoiceId": "bd946512-ade1-4dc2-ac72-5e05febd0a29",
- "officialInvoiceId": "2023-1400-1",
- "invoiceTypeCode": "CREDIT_NOTE"
}
]
}, - "creationTime": "2022-12-10T17:32:28Z"
}
{- "billingId": "fe0b70fc-6ced-4cac-a3be-cce4e76c93ec"
}
Fetch billings by using different search criteria. You can combine the search criteria, for example to search for draft billings by a specified agency office.
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 id to fetch billings for the specific assignment. |
tradeSettlementId | string <uuid> (TradeSettlementId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: tradeSettlementId=4a30bb37-96a7-47cc-9dec-f369c5651db4 Search by the trade settlement id to fetch billings for the specific settlement. |
rentalSettlementId | string <uuid> (RentalSettlementId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: rentalSettlementId=48978afa-bebb-4226-8ff0-c38ec5e05512 Search by the rental settlement id to fetch billings for the specific settlement. |
partyId | string <uuid> (PartyId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: partyId=62701576-2621-4a27-8d2b-63cea492abb6 Search by the party id to fetch billings for the specific party. |
statusCode | string (BillingStatusCode) Enum: "DRAFT" "APPROVED" "REJECTED" "CREDITED" Example: statusCode=APPROVED Search by the billing status code to fetch billings having specific statuses. |
issueDate | string <date> (IssueDate) Example: issueDate=2023-01-01 Search by the issue date to fetch billings issued on specific date. |
agencyOfficeId | Array of strings <uuid> (AgencyOfficeId) [^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...] Example: agencyOfficeId=212114ec-819e-483c-a8e0-f82289ac6e19 Search by the agency office identifiers to get a list of billings that belong to certain agency offices. |
organizationGroupId | string <uuid> (Uuid) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: organizationGroupId=aa12dfe8-3881-43a9-b47b-f9bd1dae1d87 Search by the organization group identifier to fetch a list of billings that belong to certain agency organization group. |
invoiceTypeCode | Array of strings (InvoiceTypeCode) Items Enum: "INVOICE" "CREDIT_NOTE" Example: invoiceTypeCode=CREDIT_NOTE Search by the invoice type code to fetch a list of billings that contain invoices with the mentioned type code. |
issueDateBefore | string <date> (IssueDate) Example: issueDateBefore=2023-01-16 Search by the issue date to fetch billings issued before a specific date. |
issueDateAfter | string <date> (IssueDate) Example: issueDateAfter=2023-01-14 Search by the issue date to fetch billings issued after a specific date. |
freeTextSearch | string Example: freeTextSearch=2023-1400-1 Search with free text to match billing information with the given search text. |
modifiedAfter | string <date-time> (Timestamp) Example: modifiedAfter=2021-09-21T17:32:28Z Search by a timestamp to fetch billings which have been modified after the specified timestamp. |
startIndex | integer <int32> >= 0 Example: startIndex=20 Return billing starting from this index. Indexing starts from 0. |
size | integer <int32> >= 1 Default: 40 Example: size=40 Specify the maximum number of items to return for this request. |
sort | Array of strings Example: sort=issueDate|desc Sort billings based on the specified fields. Each fields must also include a sort order as follows:
|
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. |
{- "totalCount": 1,
- "billings": [
- {
- "billingId": "fe0b70fc-6ced-4cac-a3be-cce4e76c93ec",
- "statusCode": "APPROVED",
- "legalMonetaryTotal": {
- "lineExtensionAmount": 270,
- "taxInclusiveAmount": 372,
- "allowanceTotalAmount": 30,
- "prepaidAmount": 0,
- "payableAmount": 334.8
}, - "invoices": [
- {
- "invoiceId": "bd946512-ade1-4dc2-ac72-5e05febd0a29",
- "officialInvoiceId": "2023-1400-54",
- "invoiceTypeCode": "INVOICE",
- "partyName": "Matti Virtanen",
- "invoiceStatusCode": "DRAFT",
- "legalMonetaryTotal": {
- "lineExtensionAmount": 136,
- "taxInclusiveAmount": 186,
- "allowanceTotalAmount": 15,
- "prepaidAmount": 0,
- "payableAmount": 167.4
}
}, - {
- "invoiceId": "4e36cb78-f4be-4e31-9a6b-7737990b5c9b",
- "officialInvoiceId": "2023-1400-55",
- "invoiceTypeCode": "INVOICE",
- "partyName": "Pohjolan Matkat Oy",
- "invoiceStatusCode": "APPROVED",
- "legalMonetaryTotal": {
- "lineExtensionAmount": 136,
- "taxInclusiveAmount": 186,
- "allowanceTotalAmount": 15,
- "prepaidAmount": 0,
- "payableAmount": 167.4
}
}
], - "issueDate": "2023-01-15",
- "dueDate": "2023-02-01",
- "creationTime": "2021-09-21T17:32:28Z",
- "modificationTime": "2023-09-21T17:32:28Z"
}
]
}
Fetch details for the specified billing.
billingId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: ddc25849-7bc7-43c0-9c3b-602cb03f7806 Unique billing identifier in UUID format. |
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. |
{- "billingId": "fe0b70fc-6ced-4cac-a3be-cce4e76c93ec",
- "statusCode": "APPROVED",
- "billing": {
- "billingReasonCode": "CLEARING",
- "agencyOfficeId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
- "assignmentId": "9238cf7b-b86a-49a5-b54f-cbdfcd03e9c9",
- "officialAssignmentId": "201252021",
- "tradeSettlementId": "4a30bb37-96a7-47cc-9dec-f369c5651db4",
- "documentCurrencyCode": "EUR",
- "actualDeliveryDate": "2022-12-05",
- "issueDate": "2022-12-20",
- "dueDate": "2022-12-24",
- "note": "Toimeksiantopalkkio kohteen myynnistä",
- "paymentTerms": "Netto 14 päivää",
- "downPayment": {
- "downPaymentAmount": 100,
- "paymentMethodCode": "PAYMENT_TO_BANK_ACCOUNT",
- "currencyCode": "EUR",
- "dueDate": "2022-10-31"
}, - "latePaymentFee": 5,
- "noticePeriod": 14,
- "allowanceCharges": [
- {
- "chargeIndicator": false,
- "reasonCode": "DISCOUNT",
- "allowanceChargeReason": "Alennus, koska ostaja löytyi ilman markkinointia",
- "multiplierFactorNumeric": 10,
- "amount": 30,
- "taxInclusiveAmount": 37.2,
- "baseAmount": 300,
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}
], - "taxTotal": {
- "taxAmount": 64.8,
- "currencyCode": "EUR",
- "taxSubtotals": [
- {
- "taxableAmount": 270,
- "taxAmount": 64.8,
- "currencyCode": "EUR",
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}
]
}, - "legalMonetaryTotal": {
- "lineExtensionAmount": 270,
- "taxInclusiveAmount": 372,
- "allowanceTotalAmount": 30,
- "prepaidAmount": 100,
- "payableAmount": 234.8
}, - "costItems": [
- {
- "id": "01",
- "excludeCommissions": false,
- "excludeRoyalties": false,
- "invoicedQuantity": {
- "quantity": 2,
- "unitCode": "E49"
}, - "item": {
- "name": "Kauppakirja",
- "standardItemId": "DOCUMENT_MANAGEMENT",
- "sellersItemId": "EXPENSE_DOCUMENTS",
- "description": "Kauppakirjan valmistelu ja kirjoitus",
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}, - "price": {
- "priceAmount": 150,
- "taxInclusiveAmount": 186
}, - "lineExtensionAmount": 270,
- "allowanceCharges": [
- {
- "chargeIndicator": false,
- "reasonCode": "DISCOUNT",
- "allowanceChargeReason": "Alennus, koska ostaja löytyi ilman markkinointia",
- "multiplierFactorNumeric": 10,
- "amount": 30,
- "taxInclusiveAmount": 37.2,
- "baseAmount": 300,
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}
]
}
], - "accountingCustomerParties": [
- {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "PERSON_PARTY",
- "partyName": "Matti Virtanen",
- "address": {
- "addressLine1": "Yliopistonkatu 55",
- "addressLine2": "Tampere-talo",
- "postcode": "33100",
- "postalArea": "Tampere",
- "localityName": "Tampere",
- "regionCode": "FI_PIRKANMAA",
- "countryCode": "FI"
}, - "invoicing": {
- "invoicingMethodCode": "EMAIL"
}, - "costSharingPercentage": 30
}, - {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "ORGANIZATION_PARTY",
- "partyName": "Pohjolan Matkat Oy",
- "officialIdentifiers": [
- {
- "officialId": "FI06412765",
- "schemeId": "VAT"
}, - {
- "officialId": "0641276-5",
- "schemeId": "FI:ORGNR"
}
], - "address": {
- "addressLine1": "Mannerheimintie 6 B 16",
- "postcode": "33100",
- "postalArea": "Tampere",
- "countryCode": "FI"
}, - "invoicing": {
- "invoicingMethodCode": "EINVOICING",
- "eInvoicing": {
- "eInvoicingAddress": "003706412765",
- "operatorId": "E204503",
- "operatorName": "OpusCapita Solutions Oy"
}
}, - "costSharingPercentage": 70
}
], - "commissionSummary": {
- "totalAmount": 260,
- "agentCommissions": [
- {
- "agent": {
- "agentId": "5d2a6d47-da73-4b11-8940-27cffabb6de5",
- "agencyOfficeId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
- "roleCode": "RESPONSIBLE_AGENT",
- "firstName": "Veikko",
- "lastName": "Viljanen"
}, - "totalAmount": 260,
- "sharePercentage": 100
}
]
}, - "invoices": [
- {
- "invoiceId": "bd946512-ade1-4dc2-ac72-5e05febd0a29",
- "officialInvoiceId": "2023-1400-1",
- "invoiceTypeCode": "CREDIT_NOTE"
}
]
}, - "creationTime": "2022-12-10T17:32:28Z",
- "modificationTime": "2022-12-10T17:32:28Z"
}
Update details for the specified billing. The billing contents can be updated only if it is in a DRAFT
state.
billingId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: ddc25849-7bc7-43c0-9c3b-602cb03f7806 Unique billing identifier in UUID format. |
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. |
Contains the details for the billing.
billingId | string <uuid> (BillingId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... A unique identifier for the billing in the UUID format. |
statusCode required | string (BillingStatusCode) Enum: "DRAFT" "APPROVED" "REJECTED" "CREDITED" Billing status. The status defines what actions can be performed for the billing. Possible values are:
|
required | object (Billing) Billing entity summarizes the costs and commissions associated with the trade settlement or some other service conducted by the agent. The costs have typically incurred as a result of a sale assignment or a purchase assignment. The costs to be invoiced will be paid by the accounting customer parties. The one of more accounting customer party may be different than the seller(s) in a sales assignment or the buyer(s) in a purchase assignment. If a down payment was paid for the agency’s dedicated account, down payment will be deducted from the commission as part of allowance charges. If the down payment was more than the commission amount, then a credit note must be sent to the accounting customer party. |
{- "billingId": "fe0b70fc-6ced-4cac-a3be-cce4e76c93ec",
- "statusCode": "APPROVED",
- "billing": {
- "billingReasonCode": "CLEARING",
- "agencyOfficeId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
- "assignmentId": "9238cf7b-b86a-49a5-b54f-cbdfcd03e9c9",
- "officialAssignmentId": "201252021",
- "tradeSettlementId": "4a30bb37-96a7-47cc-9dec-f369c5651db4",
- "documentCurrencyCode": "EUR",
- "actualDeliveryDate": "2022-12-05",
- "issueDate": "2022-12-10",
- "dueDate": "2022-12-24",
- "note": "Toimeksiantopalkkio kohteen myynnistä",
- "paymentTerms": "Netto 14 päivää",
- "downPayment": {
- "downPaymentAmount": 100,
- "paymentMethodCode": "PAYMENT_TO_BANK_ACCOUNT",
- "currencyCode": "EUR",
- "dueDate": "2022-09-30"
}, - "latePaymentFee": 5,
- "noticePeriod": 14,
- "allowanceCharges": [
- {
- "chargeIndicator": false,
- "reasonCode": "DISCOUNT",
- "allowanceChargeReason": "Alennus, koska ostaja löytyi ilman markkinointia",
- "multiplierFactorNumeric": 10,
- "amount": 30,
- "taxInclusiveAmount": 37.2,
- "baseAmount": 300,
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}
], - "taxTotal": {
- "taxAmount": 64.8,
- "currencyCode": "EUR",
- "taxSubtotals": [
- {
- "taxableAmount": 270,
- "taxAmount": 64.8,
- "currencyCode": "EUR",
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}
]
}, - "legalMonetaryTotal": {
- "lineExtensionAmount": 270,
- "taxInclusiveAmount": 372,
- "allowanceTotalAmount": 30,
- "prepaidAmount": 100,
- "payableAmount": 234.8
}, - "costItems": [
- {
- "id": "01",
- "excludeCommissions": false,
- "excludeRoyalties": false,
- "invoicedQuantity": {
- "quantity": 2,
- "unitCode": "E49"
}, - "item": {
- "name": "Kauppakirja",
- "standardItemId": "DOCUMENT_MANAGEMENT",
- "sellersItemId": "EXPENSE_DOCUMENTS",
- "description": "Kauppakirjan valmistelu ja kirjoitus",
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}, - "price": {
- "priceAmount": 150,
- "taxInclusiveAmount": 186
}, - "lineExtensionAmount": 270,
- "allowanceCharges": [
- {
- "chargeIndicator": false,
- "reasonCode": "DISCOUNT",
- "allowanceChargeReason": "Alennus, koska ostaja löytyi ilman markkinointia",
- "multiplierFactorNumeric": 10,
- "amount": 30,
- "taxInclusiveAmount": 37.2,
- "baseAmount": 300,
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}
]
}
], - "accountingCustomerParties": [
- {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "PERSON_PARTY",
- "partyName": "Matti Virtanen",
- "address": {
- "addressLine1": "Yliopistonkatu 55",
- "addressLine2": "Tampere-talo",
- "postcode": "33100",
- "postalArea": "Tampere",
- "localityName": "Tampere",
- "regionCode": "FI_PIRKANMAA",
- "countryCode": "FI"
}, - "invoicing": {
- "invoicingMethodCode": "EMAIL"
}, - "costSharingPercentage": 30
}, - {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "ORGANIZATION_PARTY",
- "partyName": "Pohjolan Matkat Oy",
- "officialIdentifiers": [
- {
- "officialId": "FI06412765",
- "schemeId": "VAT"
}, - {
- "officialId": "0641276-5",
- "schemeId": "FI:ORGNR"
}
], - "address": {
- "addressLine1": "Mannerheimintie 6 B 16",
- "postcode": "33100",
- "postalArea": "Tampere",
- "countryCode": "FI"
}, - "invoicing": {
- "invoicingMethodCode": "EINVOICING",
- "eInvoicing": {
- "eInvoicingAddress": "003706412765",
- "operatorId": "E204503",
- "operatorName": "OpusCapita Solutions Oy"
}
}, - "costSharingPercentage": 70
}
], - "commissionSummary": {
- "totalAmount": 260,
- "agentCommissions": [
- {
- "agent": {
- "agentId": "5d2a6d47-da73-4b11-8940-27cffabb6de5",
- "agencyOfficeId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
- "roleCode": "RESPONSIBLE_AGENT",
- "firstName": "Veikko",
- "lastName": "Viljanen"
}, - "totalAmount": 260,
- "sharePercentage": 100
}
]
}, - "invoices": [
- {
- "invoiceId": "bd946512-ade1-4dc2-ac72-5e05febd0a29",
- "officialInvoiceId": "2023-1400-54",
- "invoiceTypeCode": "INVOICE"
}, - {
- "invoiceId": "4e36cb78-f4be-4e31-9a6b-7737990b5c9b",
- "officialInvoiceId": "2023-1400-55",
- "invoiceTypeCode": "INVOICE"
}
]
}
}
{ }
Invoice API allows you to create invoices and credit notes. An invoice is typically based on an assignment. An invoice can be created on other grounds as well. A credit note can be created for an existing invoice to annulate a previous invoice. Credit note applies to the entire invoice, so no partial credit notes can be created.
An invoice in a DRAFT
state can be updated. Once the invoice has been approved, it can no longer be modified.
If there is a need to update an invoice after approval, a credit note must be sent and the original invoice must be referred in the credit note.
The /invoices
endpoint covers both the invoice and the credit note.
The "invoice" term here means also credit note unless differently specified.
Create a new invoice or credit note. The invoiceTypeCode
field specifies whether this is an INVOICE
or a CREDIT_NOTE
.
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. |
Contains the details for the invoice.
required | object (InvoiceWrite) Details for the invoice. The fields are applied from Peppol BIS Billing 3.0 standard for Invoice and Credit Note. An invoice belongs to a specific billing entity which forms the basis for the agent commissions. |
creationTime | string <date-time> (Timestamp) Timestamp as defined by ISO 8601 with time offset. |
{- "invoice": {
- "invoiceTypeCode": "CREDIT_NOTE",
- "billingId": "d403554b-d40f-4c89-a5bc-c56da3ae7117",
- "agencyOfficeId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
- "actualDeliveryDate": "2022-12-05",
- "issueDate": "2022-12-10",
- "dueDate": "2022-12-24",
- "approvalDate": "2022-12-10",
- "note": "Toimeksiantopalkkio kahden kohteen myynnistä",
- "documentCurrencyCode": "EUR",
- "buyerReference": "4020-5123-4421",
- "orderReference": "ACC-43-1438",
- "billingReferences": [
- {
- "invoiceId": "bd946512-ade1-4dc2-ac72-5e05febd0a29",
- "officialInvoiceId": "2022-1400-380",
- "issueDate": "2022-11-14"
}
], - "accountingSupplierParty": {
- "agencyId": "b7c7c8c0-fd56-4b11-8c75-6e78905cc41b",
- "partyName": "Kiinteistöykkönen Pirkanmaa Oy LKV",
- "officialIdentifiers": [
- {
- "officialId": "0247238-2",
- "schemeId": "FI:ORGNR"
}, - {
- "officialId": "FI02472382",
- "schemeId": "VAT"
}
], - "address": {
- "addressLine1": "Yliopistonkatu 55",
- "postcode": "33100",
- "postalArea": "Tampere",
- "countryCode": "FI"
}, - "invoicing": {
- "invoicingMethodCode": "EINVOICING",
- "eInvoicing": {
- "eInvoicingAddress": "003702472382",
- "operatorId": "OKOYFIHH",
- "operatorName": "OP CORPORATE BANK PLC"
}
}
}, - "accountingCustomerParty": {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "ORGANIZATION_PARTY",
- "partyName": "Pohjolan Matkat Oy",
- "officialIdentifiers": [
- {
- "officialId": "FI06412765",
- "schemeId": "VAT"
}, - {
- "officialId": "0641276-5",
- "schemeId": "FI:ORGNR"
}
], - "address": {
- "addressLine1": "Mannerheimintie 6 B 16",
- "postcode": "33100",
- "postalArea": "Tampere",
- "countryCode": "FI"
}, - "invoicing": {
- "invoicingMethodCode": "EINVOICING",
- "eInvoicing": {
- "eInvoicingAddress": "003706412765",
- "operatorId": "E204503",
- "operatorName": "OpusCapita Solutions Oy"
}
}
}, - "latePaymentFee": 5,
- "noticePeriod": 14,
- "paymentTerms": "Netto 14 päivää",
- "paymentMeans": {
- "paymentMeansCode": "31",
- "payeeFinancialAccounts": [
- {
- "financialAccountId": "F12180000012345678",
- "financialInstitutionName": "Danske Bank A/S",
- "financialInstitutionId": "DABAFIHH"
}
]
}, - "allowanceCharges": [
- {
- "chargeIndicator": false,
- "reasonCode": "DISCOUNT",
- "multiplierFactorNumeric": 2,
- "amount": 60,
- "taxInclusiveAmount": 74.4,
- "baseAmount": 3000,
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}
], - "taxTotal": {
- "taxAmount": 770.4,
- "currencyCode": "EUR",
- "taxSubtotals": [
- {
- "taxableAmount": 3210,
- "taxAmount": 770.4,
- "currencyCode": "EUR",
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}
]
}, - "legalMonetaryTotal": {
- "lineExtensionAmount": 3240,
- "taxInclusiveAmount": 4092,
- "allowanceTotalAmount": 60,
- "prepaidAmount": 1000,
- "payableAmount": 3017.6
}, - "documentLines": [
- {
- "id": "01",
- "excludeCommissions": false,
- "excludeRoyalties": false,
- "invoicedQuantity": {
- "quantity": 2,
- "unitCode": "E49"
}, - "item": {
- "name": "Kauppakirja",
- "standardItemId": "DOCUMENT_MANAGEMENT",
- "sellersItemId": "EXPENSE_DOCUMENTS",
- "description": "Kauppakirjan valmistelu ja kirjoitus",
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}, - "price": {
- "priceAmount": 150,
- "taxInclusiveAmount": 186
}, - "lineExtensionAmount": 270,
- "allowanceCharges": [
- {
- "chargeIndicator": false,
- "reasonCode": "DISCOUNT",
- "multiplierFactorNumeric": 10,
- "amount": 30,
- "taxInclusiveAmount": 37.2,
- "baseAmount": 300,
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}
]
}, - {
- "id": "02",
- "excludeCommissions": true,
- "excludeRoyalties": false,
- "invoicedQuantity": {
- "quantity": 1,
- "unitCode": "E50"
}, - "item": {
- "name": "Myyntipalkkio",
- "standardItemId": "COMMISSION",
- "sellersItemId": "SALES_COMMISSION",
- "description": "Kiinteä myyntipalkkio",
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}, - "price": {
- "priceAmount": 3000,
- "taxInclusiveAmount": 3720
}, - "lineExtensionAmount": 3000
}
]
}, - "creationTime": "2022-12-10T17:32:28Z"
}
{- "invoiceId": "9f30b223-b516-4b54-8d41-2040e4d5ac21",
- "officialInvoiceId": "2022-1400-412"
}
Fetch invoices by using different search criteria. You can combine the search criteria, for example to search for draft invoices by a specified agency office.
billingId | string <uuid> (BillingId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: billingId=fe0b70fc-6ced-4cac-a3be-cce4e76c93ec Search by the billing id to fetch invoices for a specific billing. |
invoiceStatusCode | string (InvoiceStatusCode) Enum: "DRAFT" "APPROVED" "CREDITED" "PAID" "REJECTED" Example: invoiceStatusCode=APPROVED Search by the invoice status code to fetch invoices having specific statuses. |
issueDate | string <date> (IssueDate) Example: issueDate=2023-01-01 Search by the issue date to fetch invoices issued on specific date. |
officialInvoiceId | string (OfficialInvoiceId) Example: officialInvoiceId=2023-1400-1 Search by the official invoice identifier to get a specific invoice. |
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 id to fetch invoices by a specific agent. |
agencyOfficeId | Array of strings <uuid> (AgencyOfficeId) [^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...] Example: agencyOfficeId=212114ec-819e-483c-a8e0-f82289ac6e19 Search by the agency office identifiers to get a list of invoices that belong to certain agency offices. |
organizationGroupId | string <uuid> (Uuid) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: organizationGroupId=aa12dfe8-3881-43a9-b47b-f9bd1dae1d87 Search by the organization group identifier to fetch a list of invoices that belong to certain agency organization group. |
startIndex | integer <int32> >= 0 Example: startIndex=20 Return invoices starting from this index. Indexing starts from 0. |
size | integer <int32> >= 1 Default: 40 Example: size=40 Specify the maximum number of items to return for this request. |
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. |
{- "totalCount": 1,
- "legalMonetaryTotal": {
- "lineExtensionAmount": 3240,
- "taxInclusiveAmount": 4092,
- "allowanceTotalAmount": 60,
- "prepaidAmount": 1000,
- "payableAmount": 3017.6
}, - "invoices": [
- {
- "invoiceId": "bd946512-ade1-4dc2-ac72-5e05febd0a29",
- "officialInvoiceId": "2023-1400-1",
- "invoiceStatusCode": "APPROVED",
- "accountingCustomerParty": {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "ORGANIZATION_PARTY",
- "partyName": "Pohjolan Matkat Oy"
}, - "issueDate": "2023-01-15",
- "dueDate": "2023-01-15",
- "legalMonetaryTotal": {
- "lineExtensionAmount": 3240,
- "taxInclusiveAmount": 4092,
- "allowanceTotalAmount": 60,
- "prepaidAmount": 1000,
- "payableAmount": 3017.6
}, - "invoiceDocumentId": "23d8e92a-30d6-4b14-87d9-68c2cff7181c",
- "creationTime": "2021-09-21T17:32:28Z",
- "modificationTime": "2023-09-21T17:32:28Z"
}
]
}
Fetch details for the specified invoice.
invoiceId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: ddc25849-7bc7-43c0-9c3b-602cb03f7806 Unique invoice identifier in UUID format. |
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. |
{- "invoiceId": "a6d1e6ae-f4c9-4774-86f8-14b2e2b68350",
- "officialInvoiceId": "2022-1400-412",
- "statusCode": "APPROVED",
- "invoice": {
- "invoiceTypeCode": "CREDIT_NOTE",
- "billingId": "d403554b-d40f-4c89-a5bc-c56da3ae7117",
- "agencyOfficeId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
- "actualDeliveryDate": "2022-12-05",
- "issueDate": "2022-12-10",
- "dueDate": "2022-12-24",
- "approvalDate": "2022-12-10",
- "note": "Toimeksiantopalkkio kahden kohteen myynnistä",
- "invoiceDocumentId": "23d8e92a-30d6-4b14-87d9-68c2cff7181c",
- "documentCurrencyCode": "EUR",
- "buyerReference": "4020-5123-4421",
- "orderReference": "ACC-43-1438",
- "billingReferences": [
- {
- "invoiceId": "bd946512-ade1-4dc2-ac72-5e05febd0a29",
- "officialInvoiceId": "2022-1400-380",
- "issueDate": "2022-11-14"
}
], - "accountingSupplierParty": {
- "agencyId": "b7c7c8c0-fd56-4b11-8c75-6e78905cc41b",
- "partyName": "Kiinteistöykkönen Pirkanmaa Oy LKV",
- "officialIdentifiers": [
- {
- "officialId": "0247238-2",
- "schemeId": "FI:ORGNR"
}, - {
- "officialId": "FI02472382",
- "schemeId": "VAT"
}
], - "address": {
- "addressLine1": "Yliopistonkatu 55",
- "postcode": "33100",
- "postalArea": "Tampere",
- "countryCode": "FI"
}, - "invoicing": {
- "invoicingMethodCode": "EINVOICING",
- "eInvoicing": {
- "eInvoicingAddress": "003702472382",
- "operatorId": "OKOYFIHH",
- "operatorName": "OP CORPORATE BANK PLC"
}
}
}, - "accountingCustomerParty": {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "ORGANIZATION_PARTY",
- "partyName": "Pohjolan Matkat Oy",
- "officialIdentifiers": [
- {
- "officialId": "FI06412765",
- "schemeId": "VAT"
}, - {
- "officialId": "0641276-5",
- "schemeId": "FI:ORGNR"
}
], - "address": {
- "addressLine1": "Mannerheimintie 6 B 16",
- "postcode": "33100",
- "postalArea": "Tampere",
- "countryCode": "FI"
}, - "invoicing": {
- "invoicingMethodCode": "EINVOICING",
- "eInvoicing": {
- "eInvoicingAddress": "003706412765",
- "operatorId": "E204503",
- "operatorName": "OpusCapita Solutions Oy"
}
}
}, - "latePaymentFee": 5,
- "noticePeriod": 14,
- "paymentTerms": "Netto 14 päivää",
- "paymentMeans": {
- "paymentIdentifier": "20231400158",
- "paymentMeansCode": "31",
- "payeeFinancialAccounts": [
- {
- "financialAccountId": "F12180000012345678",
- "financialInstitutionName": "Danske Bank A/S",
- "financialInstitutionId": "DABAFIHH"
}
]
}, - "allowanceCharges": [
- {
- "chargeIndicator": false,
- "reasonCode": "DISCOUNT",
- "multiplierFactorNumeric": 2,
- "amount": 60,
- "taxInclusiveAmount": 74.4,
- "baseAmount": 3000,
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}
], - "taxTotal": {
- "taxAmount": 770.4,
- "currencyCode": "EUR",
- "taxSubtotals": [
- {
- "taxableAmount": 3210,
- "taxAmount": 770.4,
- "currencyCode": "EUR",
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}
]
}, - "legalMonetaryTotal": {
- "lineExtensionAmount": 3240,
- "taxInclusiveAmount": 4092,
- "allowanceTotalAmount": 60,
- "prepaidAmount": 1000,
- "payableAmount": 3017.6
}, - "documentLines": [
- {
- "id": "01",
- "excludeCommissions": false,
- "excludeRoyalties": false,
- "invoicedQuantity": {
- "quantity": 2,
- "unitCode": "E49"
}, - "item": {
- "name": "Kauppakirja",
- "standardItemId": "DOCUMENT_MANAGEMENT",
- "sellersItemId": "EXPENSE_DOCUMENTS",
- "description": "Kauppakirjan valmistelu ja kirjoitus",
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}, - "price": {
- "priceAmount": 150,
- "taxInclusiveAmount": 186
}, - "lineExtensionAmount": 240,
- "allowanceCharges": [
- {
- "chargeIndicator": false,
- "reasonCode": "DISCOUNT",
- "multiplierFactorNumeric": 10,
- "amount": 30,
- "taxInclusiveAmount": 37.2,
- "baseAmount": 300,
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}
]
}, - {
- "id": "02",
- "excludeCommissions": true,
- "excludeRoyalties": false,
- "invoicedQuantity": {
- "quantity": 1,
- "unitCode": "E50"
}, - "item": {
- "name": "Myyntipalkkio",
- "standardItemId": "COMMISSION",
- "sellersItemId": "SALES_COMMISSION",
- "description": "Kiinteä myyntipalkkio",
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}, - "price": {
- "priceAmount": 3000,
- "taxInclusiveAmount": 3720
}, - "lineExtensionAmount": 3000
}
]
}, - "creationTime": "2022-12-10T13:07:23.000Z",
- "modificationTime": "2022-12-10T09:04:44.000Z"
}
Update details for the specified invoice. The invoice contents can be updated only if it is in a DRAFT
state.
invoiceId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: ddc25849-7bc7-43c0-9c3b-602cb03f7806 Unique invoice identifier in UUID format. |
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. |
Contains the details for the invoice.
invoiceId required | string <uuid> (InvoiceId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... A unique id which identifies the invoice. |
statusCode required | string (InvoiceStatusCode) Enum: "DRAFT" "APPROVED" "CREDITED" "PAID" "REJECTED" Invoice status. The status defines what actions can be performed for the invoice. Possible values are:
|
required | object (InvoiceWrite) Details for the invoice. The fields are applied from Peppol BIS Billing 3.0 standard for Invoice and Credit Note. An invoice belongs to a specific billing entity which forms the basis for the agent commissions. |
{- "invoiceId": "a6d1e6ae-f4c9-4774-86f8-14b2e2b68350",
- "statusCode": "APPROVED",
- "invoice": {
- "invoiceTypeCode": "CREDIT_NOTE",
- "billingId": "d403554b-d40f-4c89-a5bc-c56da3ae7117",
- "agencyOfficeId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
- "actualDeliveryDate": "2022-12-05",
- "issueDate": "2022-12-10",
- "dueDate": "2022-12-24",
- "approvalDate": "2022-12-10",
- "note": "Toimeksiantopalkkio kahden kohteen myynnistä",
- "documentCurrencyCode": "EUR",
- "buyerReference": "4020-5123-4421",
- "orderReference": "ACC-43-1438",
- "billingReferences": [
- {
- "invoiceId": "bd946512-ade1-4dc2-ac72-5e05febd0a29",
- "officialInvoiceId": "2022-1400-380",
- "issueDate": "2022-11-14"
}
], - "accountingSupplierParty": {
- "agencyId": "b7c7c8c0-fd56-4b11-8c75-6e78905cc41b",
- "partyName": "Kiinteistöykkönen Pirkanmaa Oy LKV",
- "officialIdentifiers": [
- {
- "officialId": "0247238-2",
- "schemeId": "FI:ORGNR"
}, - {
- "officialId": "FI02472382",
- "schemeId": "VAT"
}
], - "address": {
- "addressLine1": "Yliopistonkatu 55",
- "postcode": "33100",
- "postalArea": "Tampere",
- "countryCode": "FI"
}, - "invoicing": {
- "invoicingMethodCode": "EINVOICING",
- "eInvoicing": {
- "eInvoicingAddress": "003702472382",
- "operatorId": "OKOYFIHH",
- "operatorName": "OP CORPORATE BANK PLC"
}
}
}, - "accountingCustomerParty": {
- "partyId": "62701576-2621-4a27-8d2b-63cea492abb6",
- "partyTypeCode": "ORGANIZATION_PARTY",
- "partyName": "Pohjolan Matkat Oy",
- "officialIdentifiers": [
- {
- "officialId": "FI06412765",
- "schemeId": "VAT"
}, - {
- "officialId": "0641276-5",
- "schemeId": "FI:ORGNR"
}
], - "address": {
- "addressLine1": "Mannerheimintie 6 B 16",
- "postcode": "33100",
- "postalArea": "Tampere",
- "countryCode": "FI"
}, - "invoicing": {
- "invoicingMethodCode": "EINVOICING",
- "eInvoicing": {
- "eInvoicingAddress": "003706412765",
- "operatorId": "E204503",
- "operatorName": "OpusCapita Solutions Oy"
}
}
}, - "latePaymentFee": 5,
- "noticePeriod": 14,
- "paymentTerms": "Netto 14 päivää",
- "paymentMeans": {
- "paymentMeansCode": "31",
- "payeeFinancialAccounts": [
- {
- "financialAccountId": "F12180000012345678",
- "financialInstitutionName": "Danske Bank A/S",
- "financialInstitutionId": "DABAFIHH"
}
]
}, - "allowanceCharges": [
- {
- "chargeIndicator": false,
- "reasonCode": "DISCOUNT",
- "multiplierFactorNumeric": 2,
- "amount": 60,
- "taxInclusiveAmount": 74.4,
- "baseAmount": 3000,
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}
], - "taxTotal": {
- "taxAmount": 770.4,
- "currencyCode": "EUR",
- "taxSubtotals": [
- {
- "taxableAmount": 3210,
- "taxAmount": 770.4,
- "currencyCode": "EUR",
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}
]
}, - "legalMonetaryTotal": {
- "lineExtensionAmount": 3240,
- "taxInclusiveAmount": 4092,
- "allowanceTotalAmount": 60,
- "prepaidAmount": 1000,
- "payableAmount": 3017.6
}, - "documentLines": [
- {
- "id": "01",
- "excludeCommissions": false,
- "excludeRoyalties": false,
- "invoicedQuantity": {
- "quantity": 2,
- "unitCode": "E49"
}, - "item": {
- "name": "Kauppakirja",
- "standardItemId": "DOCUMENT_MANAGEMENT",
- "sellersItemId": "EXPENSE_DOCUMENTS",
- "description": "Kauppakirjan valmistelu ja kirjoitus",
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}, - "price": {
- "priceAmount": 150,
- "taxInclusiveAmount": 185
}, - "lineExtensionAmount": 270,
- "allowanceCharges": [
- {
- "chargeIndicator": false,
- "reasonCode": "DISCOUNT",
- "multiplierFactorNumeric": 10,
- "amount": 30,
- "taxInclusiveAmount": 37.2,
- "baseAmount": 300,
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}
]
}, - {
- "id": "02",
- "excludeCommissions": false,
- "excludeRoyalties": false,
- "invoicedQuantity": {
- "quantity": 1,
- "unitCode": "E50"
}, - "item": {
- "name": "Myyntipalkkio",
- "standardItemId": "COMMISSION",
- "sellersItemId": "SALES_COMMISSION",
- "description": "Kiinteä myyntipalkkio",
- "taxCategory": {
- "id": "S",
- "percent": 24,
- "schemeId": "VAT"
}
}, - "price": {
- "priceAmount": 3000,
- "taxInclusiveAmount": 3234
}, - "lineExtensionAmount": 3000
}
]
}
}
{ }
Invoice Numbering Settings API can be used by main users of the agency or agency office to define how invoice numbers are generated.
Fetch invoice numbering settings for given agency office.
agencyOfficeId required | string <uuid> (AgencyOfficeId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: agencyOfficeId=7bdffe48-0077-4de0-acd4-d9b9b1ab49f8 Unique identifier for the agency office in the UUID format. |
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. |
{- "agencyOfficeId": "2e4c26f5-bd4c-45e9-a227-b35d8222ce08",
- "officeIdentifier": "00012",
- "nextSequenceNumberToBeIssued": 44
}
Reset invoice numbering sequence number for given agency office.
agencyOfficeId required | string <uuid> (AgencyOfficeId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: agencyOfficeId=7bdffe48-0077-4de0-acd4-d9b9b1ab49f8 Unique identifier for the agency office in the UUID format. |
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. |
{ }
Transfer tax return API allows you to file transfer tax return for trade settlement buyers.
Fetch list of trade settlement buyers (taxpayers) with their transfer tax return statuses. The endpoint returns all buyers regardless of whether they have filed transfer tax return or not.
tradeSettlementId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: 6d9d4946-d170-4730-b818-37901edb961b Unique trade settlement identifier in UUID format. |
taxpayerPartyId | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: taxpayerPartyId=15bd5398-420e-461f-884f-4af99b3d05d6 Unique taxpayer buyer party identifier in UUID format. |
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. |
{- "tradeSettlementId": "1397e367-b49c-4d4b-b624-9d0ee97e3a93",
- "taxpayerParties": [
- {
- "party": {
- "partyId": "50b0517e-4bc6-447f-8013-9dded9f3fdb2",
- "partyTypeCode": "PERSON_PARTY",
- "name": "Veikko Viljanen"
}, - "transferTaxPayment": {
- "paymentReferenceNumber": "mcio3n3e309d3d13er44225deo",
- "totalTransferTaxAmount": 1234.56,
- "currencyCode": "EUR"
}, - "transferTaxReturns": [
- {
- "transferTaxReturnId": "97cfcf15-679a-4f49-91fc-5bf8951ffcc2",
- "receiptDocumentId": "5be9dc64-807b-459a-b7f0-663857f05385",
- "acceptedTime": "2021-09-21T17:32:28Z"
}, - {
- "transferTaxReturnId": "72393117-853f-4d60-a282-3aeab8018a15",
- "receiptDocumentId": "6be9dc64-807b-459a-b7f0-663857f05386",
- "acceptedTime": "2021-09-23T15:12:28Z"
}
]
}, - {
- "party": {
- "partyId": "fae961b8-34f5-41b5-8b12-403f5c143d42",
- "partyTypeCode": "PERSON_PARTY",
- "name": "Virpi Viljanen"
}, - "transferTaxPayment": {
- "paymentReferenceNumber": "mcio3n3e309d3d13er44225deo",
- "totalTransferTaxAmount": 5678.9,
- "currencyCode": "EUR"
}, - "transferTaxReturns": [ ]
}
]
}
Fetch transfer tax return preview for the specified party in specified trade settlement. The transferTaxReturnFilingV1
element in response body is specified and required by Finnish tax authority.
tradeSettlementId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: 6d9d4946-d170-4730-b818-37901edb961b Unique trade settlement identifier in UUID format. |
taxpayerPartyId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: taxpayerPartyId=15bd5398-420e-461f-884f-4af99b3d05d6 Unique taxpayer buyer party identifier in UUID format. |
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. |
{- "tradeSettlementId": "82570f0d-39cf-4306-a0d3-65d4415e8e7a",
- "taxpayerPartyId": "15bd5398-420e-461f-884f-4af99b3d05d6",
- "transferTaxReturnFilingV1": {
- "ReplacementReturn": true,
- "PreviousReturnKey": "1234567890",
- "Sender": 1,
- "BuyerID": "310183-123A",
- "BuyerDateOfBirth": "1980-01-31",
- "BuyerIndividualForeignID": "1234567890",
- "BuyerName": "Matti Meikäläinen",
- "RealEstateAgencyID": "FI12345678",
- "RealEstateAgencyName": "Asuntovälitys Oy",
- "AgencyContactPersonName": "Anna Asuntonen",
- "RealEstateAgencyPhone": "0401234567",
- "RealEstateAgencyAddress": "Esimerkkikatu 123",
- "RealEstateAgencyPostCode": "00100",
- "SigningDate": "2023-10-11",
- "TransferType": 1,
- "AdvanceRuling": false,
- "AssetDetails": [
- {
- "Asset": 1,
- "AcquiredPortionFractions": "1/2",
- "AcquiredPortionPercentage": 50,
- "CompanyID": "1234567-8",
- "CompanyName": "AS Oy Taloyhtiö",
- "ShareNumbers": "123-456",
- "AreaM2": 100.5,
- "QuantityOfShares": 10,
- "ResidentialID": "ASD123",
- "NewConstruction": true,
- "OwnershipTransferDate": "2023-11-01",
- "BuyerShareSellingPrice": 500000,
- "BuyerShareLoan": 200000,
- "BuyerShareSellerHouseLoan": 100000,
- "BuyerShareSellerDebt": 50000,
- "BuyerShareOtherCompensation": 0,
- "AddSellingPrice": true,
- "AdditionalSellingPrice": [
- {
- "AddSellingPriceWhenClarified": false,
- "BuyerShareAddSellingPrice": 10000,
- "AddSellingPriceClarifiedDate": "2023-11-01"
}, - {
- "AddSellingPriceWhenClarified": true,
- "BuyerShareAddSellingPrice": 20000,
- "AddSellingPriceClarifiedDate": "2023-11-15"
}
], - "BuyerShareTotalSellingPrice": 250000,
- "AmountTransferTax": 10000,
- "SellerDetails": [
- {
- "SellerIndividualOrCorporate": 1,
- "SellerID": "010191-123B",
- "SellerDateOfBirth": "1991-01-01",
- "SellerIndividualForeignID": "0987654321",
- "SellerName": "Maija Myyjäinen",
- "InterestCorporateBuyerIndividualSeller": true,
- "InterestIndividualBuyerCorporateSeller": false,
- "InterestCorporateBuyerSeller": false,
- "SellerOwnershipShareFractions": "1/1",
- "SellerOwnershipSharePercentage": 100,
- "NonresidentSellerBuyer": false
}
], - "FirstTimeHomebuyer": [
- {
- "Conditions": 1,
- "PortionOfSellingPrice": 250000
}
]
}
]
}
}
File transfer tax return for trade settlement buyer party. In addition to the validation performed by this endpoint, the Finnish tax authority API will perform additional validation and may reject the filing. In case of rejection, 400 INVALID_ENTITY_STATE
error is returned including rejection reasons in the errors
field of the response body.
tradeSettlementId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: 6d9d4946-d170-4730-b818-37901edb961b Unique trade settlement identifier in UUID format. |
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. |
taxpayerPartyId required | string <uuid> (TaxpayerPartyId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... The unique identifier of the taxpayer party. |
replacedReturnId | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... When executing a replacement filing this is the unique identifier of the transfer tax return which is being replaced. The value must reference to the most recent return of the trade settlement buyer. |
{- "taxpayerPartyId": "8fa1f7a6-db1d-41c7-b074-3e08bb10aff8",
- "replacedReturnId": "03c56d7e-b03c-4aac-850d-3f735c6ed145"
}
{- "transferTaxReturnId": "73aa1c0d-8fa3-4a9b-b987-ef34a8cce12d"
}
Fetch transfer tax return data which was filed to tax authority. The transferTaxReturnFilingV1
element in response body is specified and required by Finnish tax authority.
tradeSettlementId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: 6d9d4946-d170-4730-b818-37901edb961b Unique trade settlement identifier in UUID format. |
transferTaxReturnId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: 374c97dc-6a08-43ea-b1f7-371509726634 Unique transfer tax return identifier in UUID format. |
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. |
{- "transferTaxReturnId": "8c0a1ec6-b81e-442d-a960-a7f739f74fa9",
- "tradeSettlementId": "82570f0d-39cf-4306-a0d3-65d4415e8e7a",
- "taxpayerPartyId": "15bd5398-420e-461f-884f-4af99b3d05d6",
- "veroId": "abcd1234",
- "acceptedTime": "2023-12-11T12:00:00.000Z",
- "receiptDocumentId": "6726d5d6-b591-496f-9d4e-b5adbbb3f100",
- "transferTaxReturnFilingV1": {
- "ReplacementReturn": true,
- "PreviousReturnKey": "1234567890",
- "Sender": 1,
- "BuyerID": "310183-123A",
- "BuyerDateOfBirth": "1980-01-31",
- "BuyerIndividualForeignID": "1234567890",
- "BuyerName": "Matti Meikäläinen",
- "RealEstateAgencyID": "FI12345678",
- "RealEstateAgencyName": "Asuntovälitys Oy",
- "AgencyContactPersonName": "Anna Asuntonen",
- "RealEstateAgencyPhone": "0401234567",
- "RealEstateAgencyAddress": "Esimerkkikatu 123",
- "RealEstateAgencyPostCode": "00100",
- "SigningDate": "2023-10-11",
- "TransferType": 1,
- "AdvanceRuling": false,
- "AssetDetails": [
- {
- "Asset": 1,
- "AcquiredPortionFractions": "1/2",
- "AcquiredPortionPercentage": 50,
- "CompanyID": "1234567-8",
- "CompanyName": "AS Oy Taloyhtiö",
- "ShareNumbers": "123-456",
- "AreaM2": 100.5,
- "QuantityOfShares": 10,
- "ResidentialID": "ASD123",
- "NewConstruction": true,
- "OwnershipTransferDate": "2023-11-01",
- "BuyerShareSellingPrice": 500000,
- "BuyerShareLoan": 200000,
- "BuyerShareSellerHouseLoan": 100000,
- "BuyerShareSellerDebt": 50000,
- "BuyerShareOtherCompensation": 0,
- "AddSellingPrice": true,
- "AdditionalSellingPrice": [
- {
- "AddSellingPriceWhenClarified": false,
- "BuyerShareAddSellingPrice": 10000,
- "AddSellingPriceClarifiedDate": "2023-11-01"
}, - {
- "AddSellingPriceWhenClarified": true,
- "BuyerShareAddSellingPrice": 20000,
- "AddSellingPriceClarifiedDate": "2023-11-15"
}
], - "BuyerShareTotalSellingPrice": 250000,
- "AmountTransferTax": 10000,
- "SellerDetails": [
- {
- "SellerIndividualOrCorporate": 1,
- "SellerID": "010191-123B",
- "SellerDateOfBirth": "1991-01-01",
- "SellerIndividualForeignID": "0987654321",
- "SellerName": "Maija Myyjäinen",
- "InterestCorporateBuyerIndividualSeller": true,
- "InterestIndividualBuyerCorporateSeller": false,
- "InterestCorporateBuyerSeller": false,
- "SellerOwnershipShareFractions": "1/1",
- "SellerOwnershipSharePercentage": 100,
- "NonresidentSellerBuyer": false
}
], - "FirstTimeHomebuyer": [
- {
- "Conditions": 1,
- "PortionOfSellingPrice": 250000
}
]
}
]
}
}
Fetch transfer tax payment reference for specified party. The reference is fetched from third party service and request may fail if the service is down.
taxpayerPartyId required | string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... Example: taxpayerPartyId=15bd5398-420e-461f-884f-4af99b3d05d6 Unique taxpayer buyer party identifier in UUID format. |
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. |
{- "taxpayerPartyId": "8fa1f7a6-db1d-41c7-b074-3e08bb10aff8",
- "referenceNumber": "mcio3n3e309d3d13er44225deo"
}