Alma logo
API docs by Redocly

Marketing API (1.0)

Download OpenAPI specification:Download

Introduction

Marketing API allows an agent to carry out marketing actions for a realty. Realty can be published to marketplaces for sales actions or requirements for a realty can be published for purchase purposes. Related resources in the API are:

  • Marketing actions
  • Published realties
  • Extra visibilities

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.

Sales Marketing Actions

Sales Marketing Action API allows you to create and edit sales marketing actions.

Publish sales marketing action

Publish new sales marketing action with the latest realty data to the specified marketplaces. Latest realty data and images are used to create the published realty content. Start and end time can be used to schedule publishing.

Authorizations:
bearerAuth
query Parameters
notify
string
Example: notify=https://client-service.com/api/v1/publish/status

Optional webhook address to call to asynchronously notify the completion of the publishing process.

dryRun
boolean
Default: false

Try publishing the marketing action without actually completing the publishing process for example to validate the published realty data.

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

New sales marketing action data.

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

Unique identifier for the realty.

realtyTypeCode
required
string (RealtyTypeCode)
Enum: "RESIDENTIAL_SHARE" "OTHER_SHARE" "RESIDENTIAL_PROPERTY" "ESTATE_PROPERTY" "COMMERCIAL_PROPERTY" "OTHER_PROPERTY"

Describes the type of the realty in terms of used endpoint. Possible values are:

  • RESIDENTIAL_SHARE is a share type of realty meant for living.
  • OTHER_SHARE is any other share type of realty.
  • RESIDENTIAL_PROPERTY is a property type of realty meant for living.
  • ESTATE_PROPERTY is a large area of land that can include buildings.
  • COMMERCIAL_PROPERTY is commercial property type of realty.
  • OTHER_PROPERTY is any other property type of realty.
marketingActionTypeCode
required
string (MarketingActionTypeCode)
Enum: "SALES" "PURCHASE"

Describes the type of the marketing action. Possible values are:

  • SALES A sales marketing action for a realty.
  • PURCHASE A purchase marketing action for a purchase assignment's asset requirements.
agent
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

A unique id which identifies the business user who acts as an agent.

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

object (Contact)

Contains the information of a contact associated with a published entity.

marketingContactCode
required
string (MarketingContactCode)
Enum: "AGENT_AND_AGENCY_OFFICE" "AGENCY_OFFICE_ONLY" "OTHER_CONTACT"

Describes whose contact information is shown in an announcement published for the realty. Possible values are:

  • AGENT_AND_AGENCY_OFFICE Both agent and agency office contact information are shown.
  • AGENCY_OFFICE_ONLY Only agency office contact information is shown.
  • OTHER_CONTACT Some other contact information specified in marketing action field otherContact is shown.
required
Array of objects (PublishingAction)

Contains the marketplaces to publish to.

Responses

Callbacks

Request samples

Content type
application/json
{
  • "realtyId": "ddc25849-7bc7-43c0-9c3b-602cb03f7806",
  • "realtyTypeCode": "RESIDENTIAL_PROPERTY",
  • "marketingActionTypeCode": "SALES",
  • "agent": "5d2a6d47-da73-4b11-8940-27cffabb6de5",
  • "agencyOffice": "212114ec-819e-483c-a8e0-f82289ac6e19",
  • "marketingContactCode": "AGENT_AND_AGENCY_OFFICE",
  • "publishing": [
    ]
}

Response samples

Content type
application/json
{
  • "marketingActionId": "bbc36992-55c7-3043-a3b2-309cb03f7b0b"
}

Callback payload samples

Callback
POST: {$request.query.notify}
Content type
application/json
{
  • "marketingActionId": "bbc36992-55c7-3043-a3b2-309cb03f7b0b",
  • "status": [
    ]
}

Search sales marketing actions

Search sales marketing actions with realty identifier.

Authorizations:
bearerAuth
query Parameters
realtyId
string <uuid>
Example: realtyId=dcc25349-7bc7-48c0-9c8b-6202b03f7806

Search with unique realty identifier in UUID format to get a list of sales marketing actions for the specific realty.

friendlyId
string
Example: friendlyId=e29495

Unique friendly identifier for a marketplace announcement.

status
Array of strings (PublishStatusCode)
Items Enum: "IN_PROGRESS" "WAITING" "PUBLISHED" "FINISHED" "FAILED"
Example: status=PUBLISHED

Search with marketplace publishing statuses.

marketplace
Array of strings (MarketplaceCode)
Items Enum: "ETUOVI" "VUOKRAOVI" "OIKOTIE" "KL_TOIMITILAT" "TOIMITILAT_FI" "PUBLISHED_REALTY_API" "PUBLISHED_ASSET_REQUIREMENT_API"
Example: marketplace=ETUOVI

Search with marketplace identifiers.

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
{
  • "salesMarketingActions": [
    ]
}

Fetch sales marketing action

Fetch details for a specified sales marketing action. Publishing status can be found from marketingActionStatus property. When status for marketplace type PUBLISHED_REALTY_API is PUBLISHED GET /publishedRealties/{marketingActionId} endpoint can be used to fetch the published realty content.

Authorizations:
bearerAuth
path Parameters
marketingActionId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: dcc28649-7bc7-34c0-9c3b-602cb03f7b0b

Unique marketing action 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
{
  • "marketingActionId": "bbc36992-55c7-3043-a3b2-309cb03f7b0b",
  • "friendlyId": "e294935",
  • "salesMarketingAction": {
    },
  • "marketingActionStatus": [
    ],
  • "creationTime": "2021-12-18T09:54:12Z",
  • "modificationTime": "2021-12-18T18:32:02Z"
}

Update sales marketing action

Update the details of an existing sales marketing action. Marketplaces can be added with publishing action PUBLISH to publish the same published realty content to the new marketplaces. Marketplaces can be added with publishing action FINISH to end publishing in those marketplaces. The published realty content can be republished using republish query parameter.

Authorizations:
bearerAuth
path Parameters
marketingActionId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: dcc28649-7bc7-34c0-9c3b-602cb03f7b0b

Unique marketing action identifier in UUID format.

query Parameters
notify
string
Example: notify=https://client-service.com/api/v1/publish/status

Optional webhook address to call to asynchronously notify the completion of the publishing process.

republish
boolean
Default: false

Republish the existing marketing action for example in cases where publishing has failed due to the target service failure.

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

Updated sales marketing action data.

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

Unique marketing action identifier in UUID format.

required
object (SalesMarketingActionOverview)

Responses

Callbacks

Request samples

Content type
application/json
{
  • "marketingActionId": "bbc36992-55c7-3043-a3b2-309cb03f7b0b",
  • "salesMarketingAction": {
    }
}

Response samples

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

Callback payload samples

Callback
POST: {$request.query.notify}
Content type
application/json
{
  • "marketingActionId": "bbc36992-55c7-3043-a3b2-309cb03f7b0b",
  • "status": [
    ]
}

Published Realties

Published Realty API allows you to fetch data of published realties for presenting them in a marketplace website or application.

Fetch published realty

Fetch data of a published realty specified by the marketing action friendly id.

Authorizations:
bearerAuth
path Parameters
friendlyId
required
string
Example: e29495

Unique friendly identifier for a marketplace announcement.

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
{
  • "marketingActionId": "bbc36992-55c7-3043-a3b2-309cb03f7b0b",
  • "publishedRealty": {
    },
  • "creationTime": "2021-12-18T09:54:16Z",
  • "modificationTime": "2021-12-18T18:32:03Z"
}

Search published realties

Search published realties with several search criteria.

Authorizations:
bearerAuth
query Parameters
agencyOfficeId
string <uuid>
Example: agencyOfficeId=212114ec-819e-483c-a8e0-f82289ac6e19

Search with agency office identifier in UUID format to get a list of published realties that belong to certain offices.

agentId
string <uuid>
Example: agentId=5d2a6d47-da73-4b11-8940-27cffabb6de5

Search with agent identifier in UUID format to get a list of published realties that belong to certain agent.

marketingActionStatusCode
string (MarketingActionStatusCode)
Enum: "PUBLISHED" "FINISHED"
Example: marketingActionStatusCode=PUBLISHED

Describes the status of the marketplace publishing. Possible values are:

  • PUBLISHED Publishing has been successfully carried out.
  • FINISHED Publishing has been finished.
modifiedAfter
string <date-time> (DateTime)
Example: modifiedAfter=2022-12-31T13:00:00Z

Search with modifiedAfter dateTime in ISO 8601 format to get a list of published realties which have been modified after the specified date.

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

Paginate returned data starting from this index inclusive. Index starts from 0.

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

Paginate returned data with this size.

marketplaceCode
string (MarketplaceCodeSearchParameter)
Default: "PUBLISHED_REALTY_API"
Enum: "VUOKRAOVI" "PUBLISHED_REALTY_API" "KL_TOIMITILAT" "TOIMITILAT_FI"

You don't need to provide this parameter if you are implementing homepage integration.

Describes the marketplace for the marketing action. Default value is PUBLISHED_REALTY_API. Note that only admins can change the value.

Possible values are:

  • VUOKRAOVI Vuokraovi.com marketplace where the published realty is pushed to.
  • KL_TOIMITILAT Kauppalehti toimitilat marketplace where the published realty is pushed to.
  • TOIMITILAT_FI Toimitilat.fi marketplace where the published realty is pushed to.
  • PUBLISHED_REALTY_API Any other marketplace, which uses GET /publishedRealties endpoint for fetching published realties.
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
{
  • "publishedRealties": [
    ],
  • "totalCount": 2
}

Extra Visibilities

Extra Visibility API allows you to purchase extra visibilities for sales marketing actions in Etuovi. A realty and a sales marketing action for Etuovi must exist before extra visibilities can be purchased.

The steps in purchasing extra visibilities are:

  • Optional: Fetch extra visibility products, which are available for the sales marketing action using GET /extraVisibilities?marketingActionId=3456
  • Optional: After taking the initial actions in UI to purchase an extra visibility, fetch preview data using GET /extraVisibilities/CCS_TOP_OF_LIST?preview=true&previewModeCode=MOBILE
  • Do the actual purchase of the extra visibility product using POST /extraVisibilityPurchases
  • Optional: Fetch extra visibility purchase history for the sales marketing action using GET /extraVisibilityPurchases?marketingActionId=3456

Extra visibility products

Fetch descriptions of all extra visibility products.

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.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {},
  • {
    },
  • {
    }
]

Extra visibility availabilities

Fetch extra visibilities' availability data for a sales marketing action specified with one of the parameters to determine which extra visibilities are possible to purchase. If more than one identifier is specified, the order of precedence is: marketingActionId, friendlyId. A sales marketing action must be published before any extra visibilities are available for purchase.

Authorizations:
bearerAuth
query Parameters
marketingActionId
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: marketingActionId=dec35249-7bc7-48c0-9c8b-b202b0ef180b

Unique marketing action identifier in UUID format.

friendlyId
string
Example: friendlyId=e29495

Unique friendly identifier for a marketplace announcement.

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
[
  • {
    },
  • {
    },
  • {
    }
]

Extra visibility product preview

Fetch data of a specified extra visibility product including social media post preview for a sales marketing action specified with one of the parameters. The preview data is usable e.g. after taking the initial actions in UI to purchase an extra visibility product and more detailed preview data of the product is needed. If more than one identifier is specified, the order of precedence is: marketingActionId, friendlyId. It might take several seconds to respond due to the generation of the social media post preview.

Authorizations:
bearerAuth
path Parameters
productId
required
string
Example: CCS_TOP_OF_LIST

Unique identifier for an extra visibility product.

query Parameters
marketingActionId
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: marketingActionId=dec35249-7bc7-48c0-9c8b-b202b0ef180b

Unique marketing action identifier in UUID format.

friendlyId
string
Example: friendlyId=e29495

Unique friendly identifier for a marketplace announcement.

previewSourceCode
string (PreviewSourceCode)
Enum: "FACEBOOK" "INSTAGRAM"
Example: previewSourceCode=FACEBOOK

Specify the source media of extra visibility social media post preview.

previewModeCode
string (PreviewModeCode)
Enum: "MOBILE" "DESKTOP"
Example: previewModeCode=MOBILE

Specify the mode of extra visibility social media post preview. Must be specified if the value of the parameter previewSourceCode is set.

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
{
  • "marketingActionId": "9fd9124c-e6c1-4368-9f17-6938f0e2f524",
  • "product": {
    },
  • "previewData": "<iframe src=\"https://www.facebook.com/ads/api/preview_iframe.php?d=AQJg97o0f\"width=\"540\" height=\"690\" scrolling=\"yes\" style=\"border: none;\"></iframe>"
}

Purchase Marketing Actions

Purchase Marketing Action API allows you to create and edit purchase marketing actions.

Publish purchase marketing action

Publish new purchase marketing action with the latest asset requirement data to the specified marketplaces. Latest data is used to create the published requirement content. Start and end time can be used to schedule publishing.

Authorizations:
bearerAuth
query Parameters
notify
string
Example: notify=https://client-service.com/api/v1/publish/status

Optional webhook address to call to asynchronously notify the completion of the publishing process.

dryRun
boolean
Default: false

Try publishing the marketing action without actually completing the publishing process for example to validate the published requirement data.

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

New purchase marketing action data.

assetRequirementId
required
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.

marketingActionTypeCode
required
string (MarketingActionTypeCode)
Enum: "SALES" "PURCHASE"

Describes the type of the marketing action. Possible values are:

  • SALES A sales marketing action for a realty.
  • PURCHASE A purchase marketing action for a purchase assignment's asset requirements.
agentId
string <uuid> (AgentId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

A unique id which identifies the business user who acts as an agent.

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.

object (Contact)

Contains the information of a contact associated with a published entity.

marketingContactCode
required
string (MarketingContactCode)
Enum: "AGENT_AND_AGENCY_OFFICE" "AGENCY_OFFICE_ONLY" "OTHER_CONTACT"

Describes whose contact information is shown in an announcement published for the realty. Possible values are:

  • AGENT_AND_AGENCY_OFFICE Both agent and agency office contact information are shown.
  • AGENCY_OFFICE_ONLY Only agency office contact information is shown.
  • OTHER_CONTACT Some other contact information specified in marketing action field otherContact is shown.
required
Array of objects (PublishingAction)

Contains the marketplaces to publish to.

Responses

Callbacks

Request samples

Content type
application/json
{
  • "assetRequirementId": "ddc25849-7bc7-43c0-9c3b-602bc30f7608",
  • "realtyTypeCode": "RESIDENTIAL_PROPERTY",
  • "marketingActionTypeCode": "PURCHASE",
  • "agent": "5d2a6d47-da73-4b11-8940-27cffabb6de5",
  • "agencyOfficeId": "212114ec-819e-483c-a8e0-f82289ac6e19",
  • "marketingContactCode": "AGENT_AND_AGENCY_OFFICE",
  • "publishing": [
    ]
}

Response samples

Content type
application/json
{
  • "marketingActionId": "bbc36992-55c7-3023-a362-326cb08f7606"
}

Callback payload samples

Callback
POST: {$request.query.notify}
Content type
application/json
{
  • "marketingActionId": "bbc36992-55c7-3023-a362-326cb08f7606",
  • "status": [
    ]
}

Search purchase marketing actions

Search purchase marketing actions.

Authorizations:
bearerAuth
query Parameters
assetRequirementId
string <uuid>
Example: assetRequirementId=dcc25349-7bc7-48c0-9c8b-6202b03f7806

Search with unique asset requirement identifier in UUID format to get a list of purchase marketing actions for the specific assignment asset requirements.

friendlyId
string
Example: friendlyId=e29495

Unique friendly identifier for a marketplace announcement.

status
Array of strings (PublishStatusCode)
Items Enum: "IN_PROGRESS" "WAITING" "PUBLISHED" "FINISHED" "FAILED"
Example: status=PUBLISHED

Search with marketplace publishing statuses.

marketplace
Array of strings (MarketplaceCode)
Items Enum: "ETUOVI" "VUOKRAOVI" "OIKOTIE" "KL_TOIMITILAT" "TOIMITILAT_FI" "PUBLISHED_REALTY_API" "PUBLISHED_ASSET_REQUIREMENT_API"
Example: marketplace=ETUOVI

Search with marketplace identifiers.

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
{
  • "purchaseMarketingActions": [
    ]
}

Fetch purchase marketing action

Fetch details for a specified purchase marketing action. Publishing status can be found from marketingActionStatus property. When status for marketplace type PUBLISHED_ASSET_REQUIREMENT_API is PUBLISHED GET /publishedAssetRequirements/{marketingActionId} endpoint can be used to fetch the published asset requirement content.

Authorizations:
bearerAuth
path Parameters
marketingActionId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: dcc28649-7bc7-34c0-9c3b-602cb03f7b0b

Unique marketing action 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
{
  • "marketingActionId": "bbc36992-55c7-3023-a362-326cb08f7606",
  • "friendlyId": "e294935",
  • "purchaseMarketingAction": {
    },
  • "marketingActionStatus": [
    ],
  • "creationTime": "2022-01-18T09:54:12Z",
  • "modificationTime": "2022-01-18T18:32:02Z"
}

Update purchase marketing action

Update the details of an existing purchase marketing action. Marketplaces can be added with publishing action PUBLISH to publish the same published asset requirements content to the new marketplaces. Marketplaces can be added with publishing action FINISH to end publishing in those marketplaces. The published content can be republished using republish query parameter.

Authorizations:
bearerAuth
path Parameters
marketingActionId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: dcc28649-7bc7-34c0-9c3b-602cb03f7b0b

Unique marketing action identifier in UUID format.

query Parameters
notify
string
Example: notify=https://client-service.com/api/v1/publish/status

Optional webhook address to call to asynchronously notify the completion of the publishing process.

republish
boolean
Default: false

Republish the existing marketing action for example in cases where publishing has failed due to the target service failure.

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

Updated purchase marketing action data.

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

Unique marketing action identifier in UUID format.

required
object (PurchaseMarketingActionOverview)

Responses

Callbacks

Request samples

Content type
application/json
{
  • "marketingActionId": "bbc36992-55c7-3023-a362-326cb08f7606",
  • "purchaseMarketingAction": {
    }
}

Response samples

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

Callback payload samples

Callback
POST: {$request.query.notify}
Content type
application/json
{
  • "marketingActionId": "bbc36992-55c7-3023-a362-326cb08f7606",
  • "status": [
    ]
}

Published Asset Requirements

Published Asset Requirement API allows you to fetch data of published asset requirements for presenting them in a marketplace website or application.

Fetch published asset requirement

Fetch data of a published asset requirement specified by the marketing action friendly id.

Authorizations:
bearerAuth
path Parameters
friendlyId
required
string
Example: e29495

Unique friendly identifier for a marketplace announcement.

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
{
  • "marketingActionId": "bbc36992-55c7-3023-a362-326cb08f7606",
  • "publishedAssetRequirement": {
    },
  • "creationTime": "2022-10-18T09:54:16Z",
  • "modificationTime": "2022-10-18T18:32:03Z"
}

Search published asset requirements

Search published asset requirements with several search criteria.

Authorizations:
bearerAuth
query Parameters
agencyOfficeId
string <uuid>
Example: agencyOfficeId=212114ec-819e-483c-a8e0-f82289ac6e19

Search with agency office identifier in UUID format to get a list of published asset requirements that belong to certain offices.

agentId
string <uuid>
Example: agentId=5d2a6d47-da73-4b11-8940-27cffabb6de5

Search with agent identifier in UUID format to get a list of published asset requirements that belong to certain agent.

marketingActionStatusCode
string (MarketingActionStatusCode)
Enum: "PUBLISHED" "FINISHED"
Example: marketingActionStatusCode=PUBLISHED

Describes the status of the marketplace publishing. Possible values are:

  • PUBLISHED Publishing has been successfully carried out.
  • FINISHED Publishing has been finished.
modifiedAfter
string <date-time> (DateTime)
Example: modifiedAfter=2022-12-31T13:00:00Z

Search with modifiedAfter dateTime in ISO 8601 format to get a list of published asset requirements which have been modified after the specified date.

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

Paginate returned data starting from this index inclusive. Index starts from 0.

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

Paginate returned data with this size.

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

Extra Visibility Purchases

Purchase extra visibility product

Purchase an extra visibility product for a sales marketing action specified with one of the identification properties in the request body. If more than one identifier is specified, the order of precedence is: marketingActionId, friendlyId. It might take several seconds to respond due to the generation of the social media post preview in some of the products. If activationTime is not given the purchase is done immediately, otherwise it is scheduled to be done at the given time.

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

Purchase data.

productId
required
string (ProductId)

Unique identifier for an extra visibility product.

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

Unique marketing action identifier in UUID format.

friendlyId
string (FriendlyId)

Unique friendly identifier for a marketing channel announcement.

activationTime
string <date-time>

Activation time of the extra visibility product. If the value is empty then the activation is done immediately. Date and time in ISO 8601 format.

Responses

Request samples

Content type
application/json
{
  • "productId": "CCS_TOP_OF_LIST",
  • "marketingActionId": "9fd9124c-e6c1-4368-9f17-6938f0e2f524",
  • "activationTime": "2022-12-31T13:00:00Z"
}

Response samples

Content type
application/json
{
  • "friendlyId": "e294935"
}

Fetch extra visibility purchases

Fetch extra visibility purchase history for a sales marketing action specified with one of the parameters. If more than one identifier is specified, the order of precedence is: marketingActionId, friendlyId.

Authorizations:
bearerAuth
query Parameters
marketingActionId
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: marketingActionId=dec35249-7bc7-48c0-9c8b-b202b0ef180b

Unique marketing action identifier in UUID format.

friendlyId
string
Example: friendlyId=e29495

Unique friendly identifier for a marketplace announcement.

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
{
  • "previousPurchases": [
    ],
  • "scheduledPurchases": [
    ]
}

Modify scheduled extra visibility purchase

Modify the activation time of a specified scheduled extra visibility purchase.

Authorizations:
bearerAuth
path Parameters
purchaseId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: dcc28649-7bc7-34c0-9c3b-602cb03f7b0b

Unique extra visible purchase 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

Scheduled purchase data.

activationTime
required
string <date-time>

Activation time of the extra visibility product. If the value is empty then the activation is done immediately. Date and time in ISO 8601 format.

Responses

Request samples

Content type
application/json
{
  • "activationTime": "2022-12-31T13:00:00Z"
}

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 the scheduled extra visible purchase

Deletes the information of the scheduled extra visible purchase whose id is given as a path variable.

Authorizations:
bearerAuth
path Parameters
purchaseId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: dcc28649-7bc7-34c0-9c3b-602cb03f7b0b

Unique extra visible purchase 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": [
    ]
}

Marketing videos

Upload marketing video to Youtube

Uploading video to Youtube and linking it to a realty, agencyOffice or businessUser.

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

Upload marketing video to Youtube. All necessary information is given in the request body.

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

Unique identifier for the realty, agencyOffice or businessUser.

ownerType
required
string (OwnerType)
Enum: "REALTY" "AGENCY_OFFICE" "BUSINESS_USER"

The type of the owner of the video. Possible values are:

  • REALTY: The video is owned by a realty.
  • AGENCY_OFFICE: The video is owned by an agency office.
  • BUSINESS_USER: The video is owned by a business user.
statusCode
required
string (YoutubeVideoStatusWrite)
Enum: "PRIVATE" "PUBLIC"

The statusCode of the video. Possible values are:

  • PRIVATE: The video is private.
  • PUBLIC: The video is public.
required
object (SourceFile)

The source file information.

videoTitle
required
string

The title of the video.

videoDescription
required
string

The description of the video.

Responses

Request samples

Content type
application/json
{
  • "ownerIdentification": "9fd9124c-e6c1-4368-9f17-6938f0e2f524",
  • "ownerType": "REALTY",
  • "statusCode": "PRIVATE",
  • "sourceFile": {
    },
  • "videoTitle": "Title of the video",
  • "videoDescription": "Description of the video"
}

Response samples

Content type
application/json
{
  • "marketingVideoId": "049a9276-f890-4bb0-9f2b-ad28be13f81f"
}

Get marketing video

Get marketing video information.

Authorizations:
bearerAuth
query Parameters
ownerType
required
string
Enum: "REALTY" "AGENCY_OFFICE" "BUSINESS_USER"
Example: ownerType=REALTY

The type of the owner of the video. Possible values are:

  • REALTY: The video is owned by a realty.
  • AGENCY_OFFICE: The video is owned by an agency office.
  • BUSINESS_USER: The video is owned by a business user.
ownerIdentification
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: ownerIdentification=9fd9124c-e6c1-4368-9f17-6938f0e2f524

Unique identifier for the realty, agencyOffice or businessUser.

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
{
  • "marketingVideoId": "049a9276-f890-4bb0-9f2b-ad28be13f81f",
  • "ownerIdentification": "9fd9124c-e6c1-4368-9f17-6938f0e2f524",
  • "ownerType": "REALTY",
  • "statusCode": "PRIVATE",
  • "youtubeId": "pl2-ZOLZifY",
  • "youtubeMetadata": "{}"
}

Update marketing video

Uploading video to Youtube and linking it to a realty, agencyOffice or businessUser.

Authorizations:
bearerAuth
path Parameters
marketingVideoId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: dcc28649-7bc7-34c0-9c3b-602cb03f7b0b

Unique marketing video 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

Video data for updating marketing video.

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

Unique marketing video identifier in UUID format.

statusCode
required
string (YoutubeVideoStatusWrite)
Enum: "PRIVATE" "PUBLIC"

The statusCode of the video. Possible values are:

  • PRIVATE: The video is private.
  • PUBLIC: The video is public.
videoTitle
required
string

The title of the video.

videoDescription
required
string

The description of the video.

Responses

Request samples

Content type
application/json
{
  • "marketingVideoId": "049a9276-f890-4bb0-9f2b-ad28be13f81f",
  • "statusCode": "PRIVATE",
  • "videoTitle": "Title of the video",
  • "videoDescription": "Description of the video"
}

Response samples

Content type
application/json
{ }

Delete marketing video

Delete marketing video information.

Authorizations:
bearerAuth
path Parameters
marketingVideoId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: dcc28649-7bc7-34c0-9c3b-602cb03f7b0b

Unique marketing video 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
{ }