Alma logo
API docs by Redocly

Commission API (1.0)

Download OpenAPI specification:

Introduction

Commission API allows the users to manage the commission sharing between agents and agency offices in real estate transactions. This API provides comprehensive functionality for calculating, allocating, and tracking commission distributions based on predefined rules and agreements.

Key Features

  • Commission Calculation: Automatically calculate commissions based on transaction amounts and predefined percentages or fractions
  • Multi-party Distribution: Support for complex commission splits between multiple agents and agency offices
  • Invoice synchronization: The commission share is synchronized with the invoice costs that are defined included in commission sharing. If the invoice costs have been modified since the commission share was last calculated and the recalculation shows that the commission share is not in sync with the invoice costs, the commission share is marked as not in sync with the invoice costs and GET /commission returns isCommissionShareInSyncWithInvoice as false.

Contact

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

Commission

Commission API allows you to manage the commission sharing between agents and agency offices in real estate transactions.

Commission share includes the agents and agency offices who will be paid for the commissions. A commission is based on an invoice, trade settlement or rental settlement.

Create a commission

The commissions to be shared between the agents for the invoice, trade settlement or rental settlement.

  • The commission cannot be set for invoice if invoicingReasonCode is ASSIGNMENT_INITIAL_FEE.
  • The commission cannot be set for trade settlement or rental settlement if settlement status is not IN_PROGRESS.
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
required

Contains the details for the commission.

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.

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

Unique identifier for the agency office in the UUID format.

commissionShareType
required
string

The type of the commission share.

required
InvoiceFixedAmountShare (object) or InvoicePercentageShare (object) or InvoiceFractionShare (object) (InvoiceShare)

Responses

Request samples

Content type
application/json
{
  • "commissionShareType": "INVOICE",
  • "invoiceId": "4a30bb37-96a7-47cc-9dec-f369c5651db4",
  • "agencyOfficeId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
  • "share": {
    }
}

Response samples

Content type
application/json
{
  • "commissionId": "ddc25849-7bc7-43c0-9c3b-602cb03f7806"
}

Fetch commissions

Fetch commissions by using different search criteria. You can combine the search criteria.

Authorizations:
bearerAuth
query Parameters
commissionId
Array of strings <uuid> (CommissionId) <= 50 items [ items <uuid >^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... ]
Example: commissionId=7bdffe48-0077-4de0-acd4-d9b9b1ab49f8

Search by the commission id to fetch specific commissions.

invoiceId
Array of strings <uuid> (InvoiceId) <= 50 items [ items <uuid >^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... ]
Example: invoiceId=4a30bb37-96a7-47cc-9dec-f369c5651db4

Search by the invoice id to fetch commissions having specific invoice.

tradeSettlementId
Array of strings <uuid> (TradeSettlementId) <= 50 items [ items <uuid >^([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 commission shares having specific trade settlement.

rentalSettlementId
Array of strings <uuid> (RentalSettlementId) <= 50 items [ items <uuid >^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... ]
Example: rentalSettlementId=4a30bb37-96a7-47cc-9dec-f369c5651db4

Search by the rental settlement id to fetch commission shares having specific rental settlement.

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

Return commission shares starting from this index. Indexing starts from 0.

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

Specify the maximum number of items to return for this request.

sort
Array of strings <= 2 items [ items^(creationTime|modificationTime)\|(asc|ASC|de... ]
Example: sort=creationTime|asc

Sort commissions based on the specified fields. Each field 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": 3,
  • "commissions": [
    ]
}

Update a commission

Update details for the specified commission.

Authorizations:
bearerAuth
path Parameters
commissionId
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 commission 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
required

Contains the details for the commission share.

One of
sharingStrategy
required
string
Value: "FIXED_AMOUNT"

The strategy used for sharing the commission. When using only fixed amounts, this must be set to FIXED_AMOUNT.

totalShareAmount
required
integer (CommissionTotalShareAmount) [ 0 .. 10000000000 ]

The total amount excluding VAT to be shared between the agents and/or agency offices in the currency's minor unit. For example, if the currency is EUR, the value is in cents.

currencyCode
required
string (CurrencyCode) = 3 characters ^[A-Z]{3}$

Currency code as specified in ISO 4217 with alphabetic code.

required
Array of AgentCommissionShareInFixedAmount (object) or AgencyOfficeCommissionShareInFixedAmount (object) non-empty

Array of fixed amount shares. When using only fixed amounts, the sum of these shares must equal the total amount of costs that are included in the commission.

Responses

Request samples

Content type
application/json
{
  • "sharingStrategy": "PERCENTAGE",
  • "totalShareAmount": 1000000,
  • "currencyCode": "EUR",
  • "percentageShares": [
    ]
}

Response samples

Content type
application/json
{ }

Delete a commission

Delete commission sharing. If commission sharing is related to an invoice, invoice must be in DRAFT or READY_FOR_APPROVAL state. If commission sharing is related to a trade settlement or rental settlement, settlement must be in IN_PROGRESS state.

Authorizations:
bearerAuth
path Parameters
commissionId
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 commission identifier in UUID format.

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

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

Responses

Response samples

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