Alma logo
API docs by Redocly

Invoice API (v1)

Download OpenAPI specification:

Introduction

Invoice API allows the users to manage the invoicing of a realty trade and realty rental, and other invoices.

Contact

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

Invoice

Invoice API allows you to summarize costs and invoice them to the invoiced parties.

Invoice includes the invoiced parties who will be invoiced for the costs. If the costs are the basis for commissions, the invoice also includes a summary of commissions.

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.

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.

All monetary values must be given in the currency's minor unit. For example, if the currency is EUR, the values must be given in cents.

Create an invoice

Create a new invoice. For credit notes, see Create a credit note /invoices/{invoiceId}/creditNotes.

All monetary values must be given in the currency's minor unit. For example, if the currency is EUR, the values must be given in cents.

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

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

A unique identifier for the assignment in the UUID format.

required
object (BaseInvoice)

Invoice details

Responses

Request samples

Content type
application/json
{
  • "invoicingReasonCode": "CLEARING_SALE",
  • "tradeSettlementId": "5bdffe48-0077-4de0-acd4-d9b9b1ab49f5",
  • "invoice": {
    }
}

Response samples

Content type
application/json
{
  • "invoiceId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8"
}

Search invoices

Search 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
statusCode
Array of strings (InvoiceStatusCode)
Items Enum: "DRAFT" "READY_FOR_APPROVAL" "APPROVED" "REJECTED" "CREDITED"
Example: statusCode=DRAFT

Search by the invoice status code to fetch invoices having specific statuses.

invoiceNumber
string (InvoiceNumber) [ 1 .. 100 ] characters
Example: invoiceNumber=20250200001

Search by the invoice number to get a specific invoice.

partyName
string

Search by the party name to fetch a list of invoices that belong to parties with matching names.

agencyOfficeId
Array of strings <uuid> (AgencyOfficeId) [ items <uuid >^([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.

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 a list of invoices that belong to certain 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 a list of invoices that belong to certain trade settlement.

rentalSettlementId
string <uuid> (RentalSettlementId) ^([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 a list of invoices that belong to certain rental 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 a list of invoices that belong to certain party.

realtyId
string <uuid> (RealtyId) ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: realtyId=9fd9124c-e6c1-4368-9f17-6938f0e2f524

Search by the realty id to fetch a list of invoices that belong to certain realty.

responsibleAgentId
string <uuid> (AgentId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: responsibleAgentId=7bdffe48-0077-4de0-acd4-d9b9b1ab49f8

Filter invoices by the responsible agent's ID.

freeTextSearch
string [ 3 .. 50 ] characters
Example: freeTextSearch=John

Search with free text to match invoice information with the given search text. The parameter is matched against party name, invoice number, and assignment address.

modifiedAfter
string <date-time> (Timestamp)
Example: modifiedAfter=2021-09-21T17:32:28Z

Search by the modified date after to fetch a list of invoices that were modified after the specified date.

invoiceTypeCode
Array of strings (InvoiceTypeCode)
Items Enum: "INVOICE" "CREDIT_NOTE"
Example: invoiceTypeCode=CREDIT_NOTE

Search by the invoice type code to fetch invoices of a specific type.

invoicingReasonCode
Array of strings (InvoicingReasonCode)
Items Enum: "ASSIGNMENT" "CLEARING_SALE" "CLEARING_RENTAL" "OFFER_DOWN_PAYMENT" "ASSIGNMENT_INITIAL_FEE" "REALTY" "DOCUMENT_MANAGEMENT" "OTHER"
Example: invoicingReasonCode=CLEARING_SALE

Search by the invoicing reason code to fetch invoices with specific invoicing reasons.

issueDateAfter
string <date> (IssueDate) ^(?:(\d{4})-(0[13578]|1[02])-(0[1-9]|[12]\d|3...
Example: issueDateAfter=2023-01-01

Fetch invoices issued on or after the specified date.

issueDateBefore
string <date> (IssueDate) ^(?:(\d{4})-(0[13578]|1[02])-(0[1-9]|[12]\d|3...
Example: issueDateBefore=2023-01-01

Search by the issue date before to fetch a list of invoices that were issued before the specified date.

dueDateAfter
string <date> (DueDate) ^(?:(\d{4})-(0[13578]|1[02])-(0[1-9]|[12]\d|3...
Example: dueDateAfter=2023-01-15

Search by the due date after to fetch a list of invoices that are due after the specified date.

dueDateBefore
string <date> (DueDate) ^(?:(\d{4})-(0[13578]|1[02])-(0[1-9]|[12]\d|3...
Example: dueDateBefore=2023-01-15

Search by the due date before to fetch a list of invoices that are due before the specified date.

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.

sort
Array of strings[ items^(modificationTime|invoicingDate|issueDate|du... ]
Example: sort=invoicingDate|desc

Sort invoices based on the specified fields. Each field must also include a sort order as follows: sort={fieldName}|{asc|desc}&sort={anotherFieldName}|{asc|desc}

Allowed fields: modificationTime, invoicingDate, issueDate, dueDate, invoiceNumber, statusCode

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

Create a credit note

Create a credit note for an existing invoice. The credit note will be created based on the details of the referenced invoice. A credit note applies to the entire invoice, so no partial credit notes can be created.

All monetary values must be given in the currency's minor unit. For example, if the currency is EUR, the values must be given in cents.

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
required

Contains the details for the credit note.

invoicingDate
required
string <date> (InvoicingDate) ^(?:(\d{4})-(0[13578]|1[02])-(0[1-9]|[12]\d|3...

The date when the invoice is to be sent to the recipient (laskutuspäivä).

issueDate
required
string <date> (IssueDate) ^(?:(\d{4})-(0[13578]|1[02])-(0[1-9]|[12]\d|3...

The date when the invoice is issued (tapahtumapäivä).

dueDate
required
string <date> (DueDate) ^(?:(\d{4})-(0[13578]|1[02])-(0[1-9]|[12]\d|3...

The date when the payment is due (eräpäivä).

creditNoteReason
required
string (CreditNoteReason) [ 1 .. 200 ] characters

Reason for the credit note (laskutusperuste).

required
Electronic invoicing (object) or Non-electronic invoicing (object) (Invoicing)

Invoicing delivery requirements as indicated by the invoice recipient. When invoicingMethodCode is 'EINVOICING', the eInvoicing property is required.

Responses

Request samples

Content type
application/json
{
  • "invoicingDate": "2024-03-20",
  • "issueDate": "2024-03-20",
  • "dueDate": "2024-04-03",
  • "creditNoteReason": "Incorrect amount in original invoice",
  • "paymentTerms": "Paid within 14 days",
  • "invoicing": {
    }
}

Response samples

Content type
application/json
{
  • "invoiceId": "7bc7ddc2-5849-43c0-9c3b-602cb03f7806"
}

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": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
  • "statusCode": "DRAFT",
  • "invoiceTypeCode": "CREDIT_NOTE",
  • "invoicingReasonCode": "CLEARING_SALE",
  • "tradeSettlementId": "5bdffe48-0077-4de0-acd4-d9b9b1ab49f5",
  • "invoiceDocumentId": "9bdffe48-0077-4de0-acd4-d9b9b1ab49f7",
  • "previewInvoiceDocumentId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f9",
  • "creditNote": {
    },
  • "creationTime": "2024-02-17T10:30:00Z",
  • "modificationTime": "2024-02-17T10:30:00Z",
  • "invoice": {
    }
}

Update an invoice

Update details for the specified invoice. Invoice 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
required

Contains the details for the invoice.

invoiceTypeCode
required
string

Invoice is a regular invoice

required
object (BasePutInvoice)

Invoice details

Responses

Request samples

Content type
application/json
{
  • "invoiceTypeCode": "INVOICE",
  • "invoice": {
    }
}

Response samples

Content type
application/json
{ }

Delete an invoice

Deletes an invoice that is in a DRAFT state and does not have invoiceNumber and referenceNumber set.

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
{
  • "errorCode": "BAD_REQUEST_PARAMETERS",
  • "message": "Invalid request parameters",
  • "description": "Request parameters are missing or have invalid type.",
  • "errors": [
    ]
}

Execute an invoice action

Create an action 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.

Request Body schema: application/json
required

Contains the details for the invoice action.

actionTypeCode
required
string (InvoiceActionTypeCode)
Enum: "LOCK" "APPROVE" "REJECT" "UNLOCK" "MARK_AS_PAID" "MARK_AS_UNPAID"

The type of the action to be performed on the invoice. Possible values are:

  • LOCK. Changes invoices status from DRAFT to READY_FOR_APPROVAL.
  • APPROVE. Approve the invoice. Changes invoices status from READY_FOR_APPROVAL to APPROVED.
  • REJECT. Reject the invoice. Changes invoices status from DRAFT or READY_FOR_APPROVAL to REJECTED.
  • UNLOCK. Return the invoice to draft. Changes invoices status from READY_FOR_APPROVAL to DRAFT.
  • MARK_AS_PAID. Mark the invoice as paid.
  • MARK_AS_UNPAID. Mark the invoice as unpaid.

Responses

Request samples

Content type
application/json
{
  • "actionTypeCode": "LOCK"
}

Response samples

Content type
application/json
{ }

Update invoice to it's final status

This endpoint allows migration users to update the invoice to it's final status.

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
required

Contains the details for the invoice final status override.

invoiceTypeCode
required
string

Invoice is a regular invoice

required
object (CreateRegularInvoiceFinalStatusOverride)

Regular invoice's details for final status override

Responses

Request samples

Content type
application/json
{
  • "invoiceTypeCode": "INVOICE",
  • "invoice": {
    }
}

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 a preview pdf document for an invoice

Generates a preview pdf document for an invoice. If invoice has not changed since last preview document was generated, a new preview document is not generated and the existing preview document is returned instead. An invoice always refers to the latest preview document but Document API will have all previous preview documents saved.

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
required

Empty body

object (PostInvoicePreviewDocument)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "previewInvoiceDocumentId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8"
}

Agency Office Invoice Settings

Create or update agency office invoice settings

Create or update agency office invoice settings

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 agency office invoice settings.

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.

required
object (InvoiceSettings)

Invoice settings for the agency office. These settings are applied to all invoices created for the agency office.

Responses

Request samples

Content type
application/json
{
  • "agencyOfficeId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
  • "invoiceSettings": {
    }
}

Response samples

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

Get agency office invoice settings

Get agency office invoice settings

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": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
  • "invoiceSettings": {
    }
}

Agency Office Invoice Numbering Settings

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": "212114ec-819e-483c-a8e0-f82289ac6e19",
  • "officeIdentifier": "123",
  • "nextSequenceNumberToBeIssued": 1001
}

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