Alma logo
API docs by Redocly

Assignment API (1.0)

Download OpenAPI specification:Download

Introduction

Assignment API allows an agent to manage an assignment for realty. Assignment is required to purchase, sell or rent a realty. Assignments are divided into different types:

  • Sales assignment - An assignment for seller customer party to sell one or more realties.
  • Purchase assignment - An assignment for buyer to purchase a realty.
  • Rental assignment - An assignment for lessor to let a realty for rent.

Each assignment type has its own endpoint with POST, PUT, GET and DELETE methods.

Assignment can be continued to extend its validity period. This can be achieved by creating a continuation agreement with /assignments/{assignmentId}/continuationAgreements endpoint.

In addition, there is an endpoint /assignments to query assignments with different search criteria.

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.

Assignment

Assignment API allows you to fetch assignments by using different search criteria.

Fetch assignments

Fetch assignments by using different search criteria. You can combine the search criteria, for example to search for active sales assignments for a specified agent office.

Authorizations:
bearerAuth
query Parameters
partyId
string <uuid>

Search by the party identifier to fetch the specified assignment.

realtyId
string <uuid>

Search by the realty identifier to fetch the specified assignment.

assetRequirementId
string <uuid>

Search by the asset requirement identifier to fetch the specified assignment.

assignmentTypeCode
Array of strings (AssignmentTypeCode)
Items Enum: "SALES" "PURCHASE" "RENTAL"
Example: assignmentTypeCode=PURCHASE

Search by the assignment type to fetch the specified types of assignments.

agencyOfficeId
Array of strings <uuid> (AgencyOfficeId)
Example: agencyOfficeId=212114ec-819e-483c-a8e0-f82289ac6e19

Search by the agency office identifiers to get a list of assignment that belong to certain agency offices.

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

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

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

Assignments returned per page.

sort
Array of strings
Example: sort=validAfter|desc

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

Execute assignment action

Execute assignment action.

Authorizations:
bearerAuth
path Parameters
assignmentId
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 assignment 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 action to be executed for the assignment.

actionCode
required
string
Enum: "REJECT" "LOCK" "UNLOCK" "ACTIVATE" "FINISH"

Action to be executed. The actions can be used to trigger the following status transitions:

  • REJECT = DRAFT -> REJECTED
  • LOCK = DRAFT -> READY_FOR_SIGNING
  • UNLOCK = READY_FOR_SIGNING -> DRAFT
  • ACTIVATE = READY_FOR_SIGNING -> ACTIVE
  • FINISH = ACTIVE -> FINISHED

Responses

Request samples

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

Response samples

Content type
application/json
{ }

Purchase Assignment

Purchase Assignment API allows you to create, update and fetch purchase assignments.

Asset requirements can be linked to the purchase assignment upon creation or update of the assignment.

Create a purchase assignment

Create a new purchase assignment.

The asset requirements entity is defined separately and can be linked to the purchase assignment by providing value for the assetRequirementId field.

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 purchase assignment.

required
object (Assignment)

Assignment details

required
Array of objects (BuyerParty)

Specifies the buyer customers which are associated with this assignment.

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

Unique identifier for the asset requirement in the UUID format.

object (AgreementValidity)

Contains details about agreement validity.

object (Costs)

Contains details about the agreement costs.

object (OtherConditions)

Contains details about the other conditions for this assignment.

creationTime
string <date-time> (Timestamp)

Timestamp as defined by ISO 8601 with time offset.

Responses

Request samples

Content type
application/json
{
  • "assignment": {
    },
  • "buyerCustomerParties": [
    ],
  • "assetRequirementId": "45221bb8-2deb-47c4-b5e4-155a8f1770dd",
  • "agreementValidity": {
    },
  • "costs": {
    },
  • "otherConditions": {
    }
}

Response samples

Content type
application/json
{
  • "assignmentId": "7fe90453-0dea-4da8-9b42-d707704490e7"
}

Fetch a purchase assignment

Fetch details for the specified purchase assignment.

Authorizations:
bearerAuth
path Parameters
assignmentId
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 assignment 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
{
  • "assignmentId": "d265a413-a83e-40f1-b185-a3b1fb74c905",
  • "officialAssignmentId": "201252021",
  • "assignmentStatusCode": "ACTIVE",
  • "assignmentTypeCode": "PURCHASE",
  • "assignment": {
    },
  • "buyerCustomerParties": [
    ],
  • "assetRequirementId": "45221bb8-2deb-47c4-b5e4-155a8f1770dd",
  • "agreementValidity": {
    },
  • "contractDocumentId": "1e51dace-9004-48ea-84d8-23657476c1c5",
  • "costs": {
    },
  • "otherConditions": {
    },
  • "creationTime": "2021-03-13T12:07:23.000Z",
  • "modificationTime": "2021-08-15T08:04:44.000Z"
}

Update a purchase assignment

Update the details of the purchase assignment whose id is given as a path variable.

The asset requirements entity is defined separately and can be linked to the purchase assignment by providing value for the assetRequirementId field.

A purchase assignment can be updated only when its status is DRAFT. The associated asset requirements can be updated also when assignment in ACTIVE state, if the customer permission has been acquired for the updates.

Authorizations:
bearerAuth
path Parameters
assignmentId
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 assignment 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 updated purchase assignment.

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

Unique identifier for the assignment in the UUID format.

required
object (Assignment)

Assignment details

required
Array of objects (BuyerParty)

Specifies the buyer customers which are associated with this assignment.

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

Unique identifier for the asset requirement in the UUID format.

object (AgreementValidity)

Contains details about agreement validity.

object (Costs)

Contains details about the agreement costs.

object (OtherConditions)

Contains details about the other conditions for this assignment.

Responses

Request samples

Content type
application/json
{
  • "assignmentId": "d265a413-a83e-40f1-b185-a3b1fb74c905",
  • "assignment": {
    },
  • "buyerCustomerParties": [
    ],
  • "assetRequirementId": "45221bb8-2deb-47c4-b5e4-155a8f1770dd",
  • "agreementValidity": {
    },
  • "costs": {
    },
  • "otherConditions": {
    }
}

Response samples

Content type
application/json
{ }

Delete a purchase assignment

Deletes the specified purchase assignment whose id is given as a path variable.

A purchase assignment can be deleted only if its status is: DRAFT.

Authorizations:
bearerAuth
path Parameters
assignmentId
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 assignment 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": [
    ]
}

Sales Assignment

Sales Assignment API allows you to create, update and fetch sales assignments.

Create a sales assignment

Create a new sales assignment.

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 sales assignment.

required
object (Assignment)

Assignment details

object (AgreementValidity)

Contains details about agreement validity.

required
Array of objects (SellerParty)

Specifies the seller customers which are associated with this assignment.

Array of objects (ConsentorParty)

Specifies the consentor parties which are associated with this assignment.

required
Array of objects (AssetsWrite)

Assets to be sold in this assignment. A sales assignment typically includes one asset. However, there are situations when a sales assignment may include several assets:

  • New buildings can be sold through one sales assignment.
  • A residential share and one or more parking slots can be included in the same sales assignment.
object (Costs)

Contains details about the agreement costs.

object (OtherConditions)

Contains details about the other conditions for this assignment.

creationTime
string <date-time> (Timestamp)

Timestamp as defined by ISO 8601 with time offset.

Responses

Request samples

Content type
application/json
{
  • "assignment": {
    },
  • "agreementValidity": {
    },
  • "sellerCustomerParties": [
    ],
  • "consentorParties": [
    ],
  • "assets": [
    ],
  • "costs": {
    },
  • "otherConditions": {
    }
}

Response samples

Content type
application/json
{
  • "assignmentId": "7fe90453-0dea-4da8-9b42-d707704490e7"
}

Fetch a sales assignment

Fetch details for a specified sales assignment.

Authorizations:
bearerAuth
path Parameters
assignmentId
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 assignment 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
{
  • "assignmentId": "d265a413-a83e-40f1-b185-a3b1fb74c905",
  • "officialAssignmentId": "202132021",
  • "assignmentStatusCode": "ACTIVE",
  • "assignmentTypeCode": "SALES",
  • "assignment": {
    },
  • "agreementValidity": {
    },
  • "contractDocumentId": "1e51dace-9004-48ea-84d8-23657476c1c5",
  • "sellerCustomerParties": [
    ],
  • "consentorParties": [
    ],
  • "assets": [
    ],
  • "costs": {
    },
  • "otherConditions": {
    },
  • "creationTime": "2021-09-11T13:16:23.000Z",
  • "modificationTime": "2021-09-14T09:07:44.000Z"
}

Update a sales assignment

Update the details of the sales assignment whose id is given as a path variable.

A sales assignment can be updated only when its status is DRAFT. The associated assets can be updated also when assignment in ACTIVE state, if the customer permission has been acquired for the updates.

Authorizations:
bearerAuth
path Parameters
assignmentId
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 assignment 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 updated sales assignment.

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

Unique identifier for the assignment in the UUID format.

required
object (Assignment)

Assignment details

object (AgreementValidity)

Contains details about agreement validity.

required
Array of objects (SellerParty)

Specifies the seller customers which are associated with this assignment.

Array of objects (ConsentorParty)

Specifies the consentor parties which are associated with this assignment.

required
Array of objects (AssetsWrite)

Assets to be sold in this assignment. A sales assignment typically includes one asset. However, there are situations when a sales assignment may include several assets:

  • New buildings can be sold through one sales assignment.
  • A residential share and one or more parking slots can be included in the same sales assignment.
object (Costs)

Contains details about the agreement costs.

object (OtherConditions)

Contains details about the other conditions for this assignment.

Responses

Request samples

Content type
application/json
{
  • "assignmentId": "d265a413-a83e-40f1-b185-a3b1fb74c905",
  • "assignment": {
    },
  • "agreementValidity": {
    },
  • "sellerCustomerParties": [
    ],
  • "consentorParties": [
    ],
  • "assets": [
    ],
  • "costs": {
    },
  • "otherConditions": {
    }
}

Response samples

Content type
application/json
{ }

Delete a sales assignment

Deletes the specified sales assignment whose id is given as a path variable.

A sales assignment can be deleted only if its status is: DRAFT.

Authorizations:
bearerAuth
path Parameters
assignmentId
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 assignment 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": [
    ]
}

Save explanatory appendix PDF for an asset

Generates and saves explanatory appendix PDF for asset of assignment. If explanatory appendix for given asset already exists it will be replaced.

Authorizations:
bearerAuth
path Parameters
assignmentId
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 assignment 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 information that is needed to generate the explanatory appendix.

realtyId
required
string <uuid>

RealtyId for asset whose explanatory appendix is generated.

Responses

Request samples

Content type
application/json
{
  • "realtyId": "0e1e2539-c177-46cd-9fcf-47b1af5df8e0"
}

Response samples

Content type
application/json
{ }

Rental Assignment

Rental Assignment API allows you to create, update and fetch rental assignments.

Create a rental assignment

Create a new rental assignment.

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

required
object (Assignment)

Assignment details

object (AgreementValidity)

Contains details about agreement validity.

required
Array of objects (LessorParty)

Specifies the lessors which are associated with this assignment.

required
Array of objects (RentalAssets)

Assets to be rented in this assignment. A rental assignment typically includes one asset. However, there are situations when a rental assignment may include several assets:

  • A residential share and one or more parking slots can be included in the same rental assignment.
object (RentalCosts)

Contains details about the agreement costs.

object (OtherConditions)

Contains details about the other conditions for this assignment.

creationTime
string <date-time> (Timestamp)

Timestamp as defined by ISO 8601 with time offset.

Responses

Request samples

Content type
application/json
{
  • "assignment": {
    },
  • "agreementValidity": {
    },
  • "lessorParties": [
    ],
  • "assets": [
    ],
  • "costs": {
    },
  • "otherConditions": {
    }
}

Response samples

Content type
application/json
{
  • "assignmentId": "7fe90453-0dea-4da8-9b42-d707704490e7"
}

Fetch a rental assignment

Fetch details for a specified rental assignment.

Authorizations:
bearerAuth
path Parameters
assignmentId
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 assignment 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
{
  • "assignmentId": "ecbc2c7a-6687-448c-acf1-05b613bae7d4",
  • "officialAssignmentId": "201712025",
  • "assignmentStatusCode": "ACTIVE",
  • "assignmentTypeCode": "RENTAL",
  • "assignment": {
    },
  • "agreementValidity": {
    },
  • "contractDocumentId": "1e51dace-9004-48ea-84d8-23657476c1c5",
  • "lessorParties": [
    ],
  • "assets": [
    ],
  • "costs": {
    },
  • "otherConditions": {
    },
  • "creationTime": "2022-09-21T17:32:28Z",
  • "modificationTime": "2022-09-21T17:32:28Z"
}

Update a rental assignment

Update the details of the rental assignment whose id is given as a path variable.

A rental assignment can be updated only when its status is DRAFT. The associated assets can be updated also when assignment in ACTIVE state, if the permission has been acquired for the updates from the lessor.

Authorizations:
bearerAuth
path Parameters
assignmentId
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 assignment 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 updated rental assignment.

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

Unique identifier for the assignment in the UUID format.

required
object (Assignment)

Assignment details

object (AgreementValidity)

Contains details about agreement validity.

required
Array of objects (LessorParty)

Specifies the lessors which are associated with this assignment.

required
Array of objects (RentalAssets)

Assets to be rented in this assignment. A rental assignment typically includes one asset. However, there are situations when a rental assignment may include several assets:

  • A residential share and one or more parking slots can be included in the same rental assignment.
object (RentalCosts)

Contains details about the agreement costs.

object (OtherConditions)

Contains details about the other conditions for this assignment.

Responses

Request samples

Content type
application/json
{
  • "assignmentId": "ecbc2c7a-6687-448c-acf1-05b613bae7d4",
  • "assignment": {
    },
  • "agreementValidity": {
    },
  • "lessorParties": [
    ],
  • "assets": [
    ],
  • "costs": {
    },
  • "otherConditions": {
    }
}

Response samples

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

Delete a rental assignment

Deletes the specified rental assignment whose id is given as a path variable.

A rental assignment can be deleted only if its status is: DRAFT.

Authorizations:
bearerAuth
path Parameters
assignmentId
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 assignment 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": [
    ]
}

Continuation Agreement

Continuation Agreement API allows you to create, update and fetch continuation agreements. A continuation agreement is an extension to a sales assignment, a purchase assignment or a rental assignment.

A continuation agreement needs to be created when an existing, but to be expired agreement needs to be continued.

Create a continuation agreement

Create a new continuation agreement to continue an existing assignment.

Note! Upon creation of the continuation agreement, the existing assignment will be updated accordingly.

Authorizations:
bearerAuth
path Parameters
assignmentId
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 assignment 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 continuation agreement.

required
Array of objects (Agent)

Specifies the agents who are associated with this assignment.

required
object (WriteContinuationAgreementValidity)

Contains details about continuation agreement validity.

required
Array of objects (AssetReference)

Specifies the assets associated with this assignment with updated prices. This element applies only when the assignmentTypeCode is SALES.

object (OtherConditions)

Contains details about the other conditions for this assignment.

Responses

Request samples

Content type
application/json
{
  • "agents": [
    ],
  • "agreementValidity": {
    },
  • "assets": [
    ],
  • "otherConditions": {
    }
}

Response samples

Content type
application/json
{
  • "continuationAgreementId": "cea5c260-f2bc-4d17-8876-f3efbbac9d69"
}

Fetch continuation agreements

Fetch all the continuation agreements for a specific assignment.

Authorizations:
bearerAuth
path Parameters
assignmentId
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 assignment 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
{
  • "totalCount": 1,
  • "agreements": [
    ]
}

Fetch a continuation agreement

Fetch details for a specified continuation agreement.

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

continuationAgreementId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 122aec5c-66fa-4d48-a6f0-4ede37a60a30

Unique continuation agreement 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
{
  • "continuationAgreementId": "cea5c260-f2bc-4d17-8876-f3efbbac9d69",
  • "statusCode": "ACTIVE",
  • "assignmentId": "d265a413-a83e-40f1-b185-a3b1fb74c905",
  • "agents": [
    ],
  • "contractDocumentId": "3e77454a-9078-4f0f-b0d9-b37a89811a6c",
  • "agreementValidity": {
    },
  • "assets": [
    ],
  • "otherConditions": {
    },
  • "creationTime": "2021-08-12T13:07:23.000Z",
  • "modificationTime": "2021-08-15T09:04:44.000Z"
}

Update a continuation agreement

Update the continuation agreement whose id is given as a path variable.

A continuation agreement can be updated only when its status is DRAFT. The customer permission needs to be acquired for the updates.

Note! Upon updating the continuation agreement, the existing assignment will also be updated accordingly.

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

continuationAgreementId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 122aec5c-66fa-4d48-a6f0-4ede37a60a30

Unique continuation agreement 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 updated continuation agreement.

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

Unique identifier for the continuation agreement in the UUID format.

required
Array of objects (Agent)

Specifies the agents who are associated with this assignment.

required
object (WriteContinuationAgreementValidity)

Contains details about continuation agreement validity.

required
Array of objects (AssetReference)

Specifies the assets associated with this assignment with updated prices. This element applies only when the assignmentTypeCode is SALES.

object (OtherConditions)

Contains details about the other conditions for this assignment.

Responses

Request samples

Content type
application/json
{
  • "continuationAgreementId": "cea5c260-f2bc-4d17-8876-f3efbbac9d69",
  • "agents": [
    ],
  • "agreementValidity": {
    },
  • "assets": [
    ],
  • "otherConditions": {
    }
}

Response samples

Content type
application/json
{ }

Delete a continuation agreement

Deletes the specified continuation agreement whose id is given as a path variable.

A continuation agreement can be deleted only if its status is: DRAFT.

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

continuationAgreementId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 122aec5c-66fa-4d48-a6f0-4ede37a60a30

Unique continuation agreement 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 continuation agreement action

Execute continuation agreement action.

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

continuationAgreementId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 122aec5c-66fa-4d48-a6f0-4ede37a60a30

Unique continuation agreement 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 action to be executed for the continuation agreement.

actionCode
required
string
Enum: "LOCK" "UNLOCK" "ACTIVATE"

Action to be executed. The actions can be used to trigger the following status transitions:

  • LOCK = DRAFT -> READY_FOR_SIGNING

  • UNLOCK = READY_FOR_SIGNING -> DRAFT

  • ACTIVATE = READY_FOR_SIGNING -> ACTIVE

Responses

Request samples

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

Response samples

Content type
application/json
{ }

Assignment Diary Events

Assignment Diary Events API allows you to fetch assignment change history for the assignment diary.

Fetch assignment diary events

Fetch events for a diary of specified assignment.

Authorizations:
bearerAuth
path Parameters
assignmentId
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 assignment 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
{
  • "totalCount": 4,
  • "assignmentId": "23aa5835-9a3d-4e14-b812-f6cecaac2705",
  • "agencyOfficeId": "db0f6f68-5b9f-4f46-a8f3-4ef729d77db7",
  • "diaryEvents": [
    ]
}

Official Assignment Identifier Settings

Official Assignment Identifier Settings API can be used by main users of the agency or agency office to define how official assignment identifiers are generated.

Fetch official assignment identifier settings

Fetch official assignment identifier 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": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
  • "officeIdentifier": "00020",
  • "nextSequenceNumberToBeIssued": 98
}

Save official assignment identifier settings

Save official assignment identifier settings for given agency office.

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 assignment identifier settings for office.

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.

officeIdentifier
required
string (OfficeIdentifier) ^\d*$

If office identifier is set it is used as a first part of officialAssignmentId. Value should be unique to all company's offices.

Responses

Request samples

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

Response samples

Content type
application/json
{ }

Reset assignment identifier sequence number

Reset assignment identifier 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
{ }

Integration Settings

Fetch integration settings

Fetch integration 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": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
  • "hspTransferEnabled": true,
  • "surveypalTransferEnabled": true,
  • "externalSurveyTransferEnabled": false,
  • "surveypalSurveySettings": [
    ]
}

Save integration settings

Create or update integration settings for given agency office. All individual integration settings must be able to be set undefined and therefore are not required.

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 integration settings for office.

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.

hspTransferEnabled
boolean (HspTransferEnabled)

Indicates whether HSP integration is enabled for agencyOffice and the completed trades are sent to HSP.

surveypalTransferEnabled
boolean (SurveypalTransferEnabled)

Indicates whether Surveypal integration is enabled for agencyOffice.

externalSurveyTransferEnabled
boolean (ExternalSurveyTransferEnabled)

Indicates whether external customer feedback integration is enabled for agencyOffice.

Array of objects (SurveypalSurveySettings)

Surveypal survey configurations.

Responses

Request samples

Content type
application/json
{
  • "agencyOfficeId": "7bdffe48-0077-4de0-acd4-d9b9b1ab49f8",
  • "hspTransferEnabled": true,
  • "surveypalTransferEnabled": true,
  • "externalSurveyTransferEnabled": false,
  • "surveypalSurveySettings": [
    ]
}

Response samples

Content type
application/json
{ }