Alma logo
API docs by Redocly

Clearing API (1.0)

Download OpenAPI specification:Download

Introduction

Clearing API allows the agent to manage the clearing of a realty trade and a realty rental.

Contact

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

Error codes

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

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

Trade Settlement

Trade Settlement API allows you to initiate and complete a trade settlement for a set of assets.

Create a trade settlement

Create a new trade settlement.

Authorizations:
bearerAuth
header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Request Body schema: application/json

Contains the details for the trade settlement.

required
object (TradeSettlement)

Details for the trade settlement.

creationTime
string <date-time> (Timestamp)

Timestamp as defined by ISO 8601 with time offset.

Responses

Request samples

Content type
application/json
{
  • "tradeSettlement": {
    }
}

Response samples

Content type
application/json
{
  • "tradeSettlementId": "4a30bb37-96a7-47cc-9dec-f369c5651db4"
}

Fetch a trade settlement

Fetch details for the specified trade settlement.

Authorizations:
bearerAuth
path Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Responses

Response samples

Content type
application/json
{
  • "tradeSettlementId": "4a30bb37-96a7-47cc-9dec-f369c5651db4",
  • "statusCode": "COMPLETED",
  • "tradeSettlement": {
    },
  • "creationTime": "2022-12-30T17:32:28Z",
  • "modificationTime": "2022-12-30T17:32:28Z"
}

Update a trade settlement

Update details for the specified trade settlement. The trade settlement contents can be updated only if it is in a IN_PROGRESS state.

Authorizations:
bearerAuth
path Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Request Body schema: application/json

Contains the details for the 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:

  • IN_PROGRESS. The trade settlement has been initiated and can be modified.
  • COMPLETED. The trade settlement has been completed. A completed trade settlement cannot be modified. If a change is required, the trade settlement must be dismantled.
  • DISMANTLED. The trade settlement has been dismantled.
required
object (TradeSettlement)

Details for the trade settlement.

Responses

Request samples

Content type
application/json
{
  • "tradeSettlementId": "4a30bb37-96a7-47cc-9dec-f369c5651db4",
  • "statusCode": "COMPLETED",
  • "tradeSettlement": {
    }
}

Response samples

Content type
application/json
{ }

Sales Deed

Sales deed API allows you to create sales deed document for trade settlement.

Fetch trade settlement's sales deed contents

Fetch contents of the sales deed for given trade settlement.

Authorizations:
bearerAuth
path Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Responses

Response samples

Content type
application/json
{
  • "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 a contents of a sales deed

Save contents of sales deed for given trade settlement. Note: Related sales deed PDF document is not updated automatically.

Authorizations:
bearerAuth
path Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Request Body schema: application/json

Contains the content of the sales deed.

salesDeedContent
required
string

JSON escaped markdown content for sales deed.

Responses

Request samples

Content type
application/json
{
  • "salesDeedContent": "# **KAUPPAKIRJA**\r\n\r\n\r\n\r\n# KAUPAN OSAPUOLET\r\n\r\n\r\n\r\n**Myyjä:**..."
}

Response samples

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

Generate and save PDF using sales deed content

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.

Authorizations:
bearerAuth
path Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Request Body schema: application/json

Empty body

object (PostSalesDeedDocument)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "salesDeedDocumentId": "77ac2031-8c8f-43e1-8ab6-6f0dd7c1d1d6"
}

Transfer Terms

Transfer Terms API allows you to create transfer terms document for trade settlement.

Fetch trade settlement's transfer terms contents

Fetch contents of the transfer terms for given trade settlement.

Authorizations:
bearerAuth
path Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Responses

Response samples

Content type
application/json
{
  • "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 a contents of a transfer terms

Save contents of transfer terms for given trade settlement. Note: Related transfer terms PDF document is not updated automatically.

Authorizations:
bearerAuth
path Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Request Body schema: application/json

Contains the content of the transfer terms.

transferTermsContent
required
string

JSON escaped markdown content for transfer terms.

Responses

Request samples

Content type
application/json
{
  • "transferTermsContent": "# **KAUPAN EHDOT**\r\n\r\n\r\n\r\n# KAUPAN OSAPUOLET\r\n\r\n\r\n\r\n**Myyjä:**..."
}

Response samples

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

Generate and save PDF using transfer terms content

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.

Authorizations:
bearerAuth
path Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Request Body schema: application/json

Empty body

object (PostTransferTermsDocument)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "transferTermsDocumentId": "77ac2031-8c8f-43e1-8ab6-6f0dd7c1d1d6"
}

Rental Settlement

Rental Settlement API allows you to initiate and complete a rental settlement for a set of assets.

Create a rental settlement

Create a new rental settlement.

Authorizations:
bearerAuth
header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Request Body schema: application/json

Contains the details for the rental settlement.

required
object (RentalSettlement)

Details for the rental settlement.

creationTime
string <date-time> (Timestamp)

Timestamp as defined by ISO 8601 with time offset.

Responses

Request samples

Content type
application/json
{
  • "rentalSettlement": {
    }
}

Response samples

Content type
application/json
{
  • "rentalSettlementId": "48978afa-bebb-4226-8ff0-c38ec5e05512"
}

Search rental settlements

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.

Authorizations:
bearerAuth
query Parameters
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)
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> (Date)
Example: modifiedAfter=2022-06-01

Search by a date to get a list of rental settlements which were modified after the specified date.

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:

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

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Responses

Response samples

Content type
application/json
{
  • "totalCount": 8,
  • "rentalSettlements": [
    ]
}

Fetch a rental settlement

Fetch details for the specified rental settlement.

Authorizations:
bearerAuth
path Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Responses

Response samples

Content type
application/json
{
  • "rentalSettlementId": "48978afa-bebb-4226-8ff0-c38ec5e05512",
  • "statusCode": "IN_PROGRESS",
  • "rentalSettlement": {
    },
  • "creationTime": "2023-11-17T17:23:08Z",
  • "modificationTime": "2023-11-19T13:32:28Z"
}

Update a rental settlement

Update details for the specified rental settlement. The rental settlement contents can be updated only if it is in a IN_PROGRESS state.

Authorizations:
bearerAuth
path Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Request Body schema: application/json

Contains the details for the 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:

  • IN_PROGRESS. The rental settlement has been initiated and can be modified.
  • COMPLETED. The rental settlement has been completed. A completed rental settlement cannot be modified. If a change is required, the rental settlement must be dismantled.
  • DISMANTLED. The rental settlement has been dismantled.
required
object (RentalSettlement)

Details for the rental settlement.

Responses

Request samples

Content type
application/json
{
  • "rentalSettlementId": "48978afa-bebb-4226-8ff0-c38ec5e05512",
  • "statusCode": "IN_PROGRESS",
  • "rentalSettlement": {
    }
}

Response samples

Content type
application/json
{ }

Lease Agreement

Sales deed API allows you to create lease agreement document for rental settlement.

Fetch rental settlement's lease agreement contents

Fetch contents of the lease agreement for given rental settlement.

Authorizations:
bearerAuth
path Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Responses

Response samples

Content type
application/json
{
  • "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 a lease agreement

Save contents of lease agreement for given rental settlement. Note: Related lease agreement PDF document is not updated automatically.

Authorizations:
bearerAuth
path Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Request Body schema: application/json

Contains the content of the lease agreement.

leaseAgreementContent
required
string

JSON escaped markdown content for lease agreement.

Responses

Request samples

Content type
application/json
{
  • "leaseAgreementContent": "# **KAUPPAKIRJA**\r\n\r\n\r\n\r\n# KAUPAN OSAPUOLET\r\n\r\n\r\n\r\n**Myyjä:**..."
}

Response samples

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

Generate and save PDF using lease agreement content

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.

Authorizations:
bearerAuth
path Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Request Body schema: application/json

Empty body

object (PostLeaseAgreementDocument)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "leaseAgreementDocumentId": "77ac2031-8c8f-43e1-8ab6-6f0dd7c1d1d6"
}

Billing

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 billing

Create a new billing which includes items to be invoiced.

Authorizations:
bearerAuth
header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Request Body schema: application/json

Contains the details for the 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.

Responses

Request samples

Content type
application/json
{
  • "billing": {
    },
  • "creationTime": "2022-12-10T17:32:28Z"
}

Response samples

Content type
application/json
{
  • "billingId": "fe0b70fc-6ced-4cac-a3be-cce4e76c93ec"
}

Fetch billings

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.

Authorizations:
bearerAuth
query Parameters
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)
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.

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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Responses

Response samples

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

Fetch a billing

Fetch details for the specified billing.

Authorizations:
bearerAuth
path Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Responses

Response samples

Content type
application/json
{
  • "billingId": "fe0b70fc-6ced-4cac-a3be-cce4e76c93ec",
  • "statusCode": "APPROVED",
  • "billing": {
    },
  • "creationTime": "2022-12-10T17:32:28Z",
  • "modificationTime": "2022-12-10T17:32:28Z"
}

Update a billing

Update details for the specified billing. The billing contents can be updated only if it is in a DRAFT state.

Authorizations:
bearerAuth
path Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Request Body schema: application/json

Contains the details for the 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:

  • DRAFT. The billing can be modified.
  • APPROVED. The billing has been approved and the invoices can be delivered to the recipient. An approved billing cannot be modified.
  • CREDITED. The billing has been credited. Each invoice belonging to this billing has been credited.
  • REJECTED. The billing has been rejected and a credit notes must be created for each invoice.
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.

Responses

Request samples

Content type
application/json
{
  • "billingId": "fe0b70fc-6ced-4cac-a3be-cce4e76c93ec",
  • "statusCode": "APPROVED",
  • "billing": {
    }
}

Response samples

Content type
application/json
{ }

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 an invoice

Create a new invoice or credit note. The invoiceTypeCode field specifies whether this is an INVOICE or a CREDIT_NOTE.

Authorizations:
bearerAuth
header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Request Body schema: application/json

Contains the details for the 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.

Responses

Request samples

Content type
application/json
{
  • "invoice": {
    },
  • "creationTime": "2022-12-10T17:32:28Z"
}

Response samples

Content type
application/json
{
  • "invoiceId": "9f30b223-b516-4b54-8d41-2040e4d5ac21",
  • "officialInvoiceId": "2022-1400-412"
}

Fetch invoices

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.

Authorizations:
bearerAuth
query Parameters
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)
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Responses

Response samples

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

Fetch an invoice

Fetch details for the specified invoice.

Authorizations:
bearerAuth
path Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Responses

Response samples

Content type
application/json
{
  • "invoiceId": "a6d1e6ae-f4c9-4774-86f8-14b2e2b68350",
  • "officialInvoiceId": "2022-1400-412",
  • "statusCode": "APPROVED",
  • "invoice": {
    },
  • "creationTime": "2022-12-10T13:07:23.000Z",
  • "modificationTime": "2022-12-10T09:04:44.000Z"
}

Update an invoice

Update details for the specified invoice. The invoice contents can be updated only if it is in a DRAFT state.

Authorizations:
bearerAuth
path Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Request Body schema: application/json

Contains the details for the 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:

  • DRAFT. The invoice can be modified.
  • APPROVED. The invoice has been approved and can be delivered to the recipient. An approved invoice cannot be modified.
  • CREDITED. The invoice has been credited.
  • PAID. The invoice has been paid.
  • REJECTED. The invoice has been rejected and a credit note must be created for the recipient.
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.

Responses

Request samples

Content type
application/json
{
  • "invoiceId": "a6d1e6ae-f4c9-4774-86f8-14b2e2b68350",
  • "statusCode": "APPROVED",
  • "invoice": {
    }
}

Response samples

Content type
application/json
{ }

Invoice Numbering Settings

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

Fetch invoice numbering settings for given agency office.

Authorizations:
bearerAuth
query Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Responses

Response samples

Content type
application/json
{
  • "agencyOfficeId": "2e4c26f5-bd4c-45e9-a227-b35d8222ce08",
  • "officeIdentifier": "00012",
  • "nextSequenceNumberToBeIssued": 44
}

Reset invoice numbering sequence number

Reset invoice numbering sequence number for given agency office.

Authorizations:
bearerAuth
query Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Responses

Response samples

Content type
application/json
{ }

Transfer Tax Return

Transfer tax return API allows you to file transfer tax return for trade settlement buyers.

Fetch transfer tax statuses

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.

Authorizations:
bearerAuth
path Parameters
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.

query Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Responses

Response samples

Content type
application/json
{
  • "tradeSettlementId": "1397e367-b49c-4d4b-b624-9d0ee97e3a93",
  • "taxpayerParties": [
    ]
}

Fetch transfer tax return preview

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.

Authorizations:
bearerAuth
path Parameters
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.

query Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Responses

Response samples

Content type
application/json
{
  • "tradeSettlementId": "82570f0d-39cf-4306-a0d3-65d4415e8e7a",
  • "taxpayerPartyId": "15bd5398-420e-461f-884f-4af99b3d05d6",
  • "transferTaxReturnFilingV1": {
    }
}

File transfer tax return

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.

Authorizations:
bearerAuth
path Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Request Body schema: application/json
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.

Responses

Request samples

Content type
application/json
{
  • "taxpayerPartyId": "8fa1f7a6-db1d-41c7-b074-3e08bb10aff8",
  • "replacedReturnId": "03c56d7e-b03c-4aac-850d-3f735c6ed145"
}

Response samples

Content type
application/json
{
  • "transferTaxReturnId": "73aa1c0d-8fa3-4a9b-b987-ef34a8cce12d"
}

Fetch transfer tax return

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.

Authorizations:
bearerAuth
path Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Responses

Response samples

Content type
application/json
{
  • "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": {
    }
}

Fetch transfer tax payment reference

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.

Authorizations:
bearerAuth
query Parameters
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.

header Parameters
Request-ID
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Responses

Response samples

Content type
application/json
{
  • "taxpayerPartyId": "8fa1f7a6-db1d-41c7-b074-3e08bb10aff8",
  • "referenceNumber": "mcio3n3e309d3d13er44225deo"
}