Alma logo
API docs by Redocly

Meeting API (1.0)

Download OpenAPI specification:Download

Introduction

Meeting API allows an agent to manage meetings

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.
410 GONE The requested resource is no longer available.
415 UNSUPPORTED_MEDIA_TYPE Unsupported media type.
500 TECHNICAL_ERROR A technical error has occurred.
503 SERVICE_UNAVAILABLE Service is unavailable.

Meeting

Meeting API allows you to manage meetings

Create a new meeting

Create a new meeting.

Authorizations:
bearerAuth
header Parameters
Request-ID
required
string <uuid>
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Request Body schema: application/json

Request body contains details of the meeting.

typeCode
required
string (MeetingTypeCode)
Enum: "SALES_MEETING" "EVALUATION_VISIT"

The type of meeting.

statusCode
required
string (StatusCode)
Enum: "WAITING" "WON" "LOST" "CANCELLED"

The status of the meeting.

  • WAITING. Meeting is waiting for the next action.
  • WON. Meeting have been won. In this state meeting statusCode can only be changed to LOST and parties and visitTime can't be modified anymore.
  • LOST. Meeting have been lost. In this state meeting statusCode can only be changed to WON and parties and visitTime can't be modified anymore.
  • CANCELLED. Meeting have been cancelled. Meeting status will be locked and parties and visitTime can't be modified anymore.
required
Array of objects non-empty

The parties related to the meeting.

realtyId
string <uuid>

The realty id related to the meeting.

visitTime
required
string <date-time>

The date and time of the meeting.

agencyOfficeId
required
string <uuid>

The agency office id related to the meeting.

required
Array of objects non-empty

The agents related to the meeting.

sourceTypeCode
required
string (SourceTypeCode)
Enum: "ETUOVI" "OIKOTIE" "ASUNTOJENMYYNTI_FI" "ASUNTOJENHINNAT_FI" "NELIOHINTA_FI" "ASUNTOARVIO_FI" "HOME_PAGE" "CHATBOT" "BANK_COOPERATION" "SHOWING" "BOUGHT_FROM_US" "OLD_CUSTOMER" "RECOMMENDATION" "DIRECT_CONTACT" "AGENT_CONTACT"

The source of the meeting.

required
object (MeetingRealty)
object (PriceEstimate)

Price estimate of the realty related to meeting.

notes
string

Notes about meeting.

Responses

Request samples

Content type
application/json
{
  • "typeCode": "SALES_MEETING",
  • "statusCode": "WAITING",
  • "parties": [
    ],
  • "realtyId": "123e4567-e89b-12d3-a456-426655440000",
  • "visitTime": "2022-12-31T23:59:59Z",
  • "agencyOfficeId": "123e4567-e89b-12d3-a456-426655440000",
  • "agents": [
    ],
  • "sourceTypeCode": "ETUOVI",
  • "meetingRealty": {
    },
  • "priceEstimate": {
    },
  • "notes": "string"
}

Response samples

Content type
application/json
{
  • "meetingId": "c6d2288d-2ecb-448a-aef3-fd5144920e0b"
}

Search meetings

Search meetings.

Authorizations:
bearerAuth
query Parameters
sourceTypeCode
Array of strings (SourceTypeCode)
Items Enum: "ETUOVI" "OIKOTIE" "ASUNTOJENMYYNTI_FI" "ASUNTOJENHINNAT_FI" "NELIOHINTA_FI" "ASUNTOARVIO_FI" "HOME_PAGE" "CHATBOT" "BANK_COOPERATION" "SHOWING" "BOUGHT_FROM_US" "OLD_CUSTOMER" "RECOMMENDATION" "DIRECT_CONTACT" "AGENT_CONTACT"
Example: sourceTypeCode=ETUOVI
statusCode
Array of strings (StatusCode)
Items Enum: "WAITING" "WON" "LOST" "CANCELLED"
Example: statusCode=WAITING
agencyOfficeId
Array of strings <uuid>
Example: agencyOfficeId=123e4567-e89b-12d3-a456-426655440000

Search by the agency office id to get a list of meetings.

typeCode
Array of strings (MeetingTypeCode)
Items Enum: "SALES_MEETING" "EVALUATION_VISIT"
Example: typeCode=SALES_MEETING
freeTextSearch
string

Search with free text to match meeting information with the given search text.

visitTimeBefore
string <date-time>

Search by the date to get a list of meeting happening before the given date.

visitTimeAfter
string <date-time>

Search by the date to get a list of meeting happening after the given date.

modifiedAfter
string <date-time>

Search by the modification time to get a list of meetings that were modified after given timestamp.

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

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

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

Meetings returned per page.

sort
Array of strings
Example: sort=visitTime|desc

Sort meetings based on the specified fields. Each fields must also include a sort order as follows:

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

Supported sort fields are:

  • visitTime
  • modificationTime
header Parameters
Request-ID
required
string <uuid>
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Responses

Response samples

Content type
application/json
{
  • "meetings": [
    ],
  • "totalCount": 10
}

Get details of a meeting

Get details of a meeting.

Authorizations:
bearerAuth
path Parameters
meetingId
required
string <uuid>
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

Identifier of the meeting

header Parameters
Request-ID
required
string <uuid>
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Responses

Response samples

Content type
application/json
{
  • "meetingId": "c6d2288d-2ecb-448a-aef3-fd5144920e0b",
  • "typeCode": "SALES_MEETING",
  • "statusCode": "WAITING",
  • "parties": [
    ],
  • "realtyId": "123e4567-e89b-12d3-a456-426655440000",
  • "visitTime": "2022-12-31T23:59:59Z",
  • "agencyOfficeId": "123e4567-e89b-12d3-a456-426655440000",
  • "agents": [
    ],
  • "sourceTypeCode": "ETUOVI",
  • "meetingRealty": {
    },
  • "priceEstimate": {
    },
  • "notes": "string"
}

Delete a meeting

Delete a meeting. Meeting can be deleted only if it is in WAITING state.

Authorizations:
bearerAuth
path Parameters
meetingId
required
string <uuid>
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

Identifier of the meeting

header Parameters
Request-ID
required
string <uuid>
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Responses

Response samples

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

Update a meeting

Update a meeting. Note that when meetings statusCode is set to WON or LOST "parties" and "visitTime" can't be modified anymore.

Authorizations:
bearerAuth
path Parameters
meetingId
required
string <uuid>
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

Identifier of the meeting

header Parameters
Request-ID
required
string <uuid>
Example: 9031d1c5-7d40-41dd-b2b8-7919a2fc4fe9

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

Request Body schema: application/json

Request body contains details of the meeting.

typeCode
required
string (MeetingTypeCode)
Enum: "SALES_MEETING" "EVALUATION_VISIT"

The type of meeting.

statusCode
required
string (StatusCode)
Enum: "WAITING" "WON" "LOST" "CANCELLED"

The status of the meeting.

  • WAITING. Meeting is waiting for the next action.
  • WON. Meeting have been won. In this state meeting statusCode can only be changed to LOST and parties and visitTime can't be modified anymore.
  • LOST. Meeting have been lost. In this state meeting statusCode can only be changed to WON and parties and visitTime can't be modified anymore.
  • CANCELLED. Meeting have been cancelled. Meeting status will be locked and parties and visitTime can't be modified anymore.
required
Array of objects non-empty

The parties related to the meeting.

realtyId
string <uuid>

The realty id related to the meeting.

visitTime
required
string <date-time>

The date and time of the meeting.

agencyOfficeId
required
string <uuid>

The agency office id related to the meeting.

required
Array of objects non-empty

The agents related to the meeting.

sourceTypeCode
required
string (SourceTypeCode)
Enum: "ETUOVI" "OIKOTIE" "ASUNTOJENMYYNTI_FI" "ASUNTOJENHINNAT_FI" "NELIOHINTA_FI" "ASUNTOARVIO_FI" "HOME_PAGE" "CHATBOT" "BANK_COOPERATION" "SHOWING" "BOUGHT_FROM_US" "OLD_CUSTOMER" "RECOMMENDATION" "DIRECT_CONTACT" "AGENT_CONTACT"

The source of the meeting.

required
object (MeetingRealty)
object (PriceEstimate)

Price estimate of the realty related to meeting.

notes
string

Notes about meeting.

Responses

Request samples

Content type
application/json
{
  • "typeCode": "SALES_MEETING",
  • "statusCode": "WAITING",
  • "parties": [
    ],
  • "realtyId": "123e4567-e89b-12d3-a456-426655440000",
  • "visitTime": "2022-12-31T23:59:59Z",
  • "agencyOfficeId": "123e4567-e89b-12d3-a456-426655440000",
  • "agents": [
    ],
  • "sourceTypeCode": "ETUOVI",
  • "meetingRealty": {
    },
  • "priceEstimate": {
    },
  • "notes": "string"
}

Response samples

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