OviPro logo
API docs by Redocly

Lead API (v1)

Download OpenAPI specification:

Introduction

Lead API allows an agent to view and manage leads associated with his/her agency office.

A lead can be received from several sources such as marketplaces and other partners. The agent need to handle a new lead by marking its status as approved (APPROVED) or rejected (REJECTED).

Leads can be also sent to a partner as an outgoing lead.

Contact

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

Lead

Lead API allows an agent to manage all the leads for his/her agency offices.

Create a marketplace lead

This endpoint is used by marketplaces to create leads. A marketplace specific permission is required to use this endpoint.

Authorizations:
bearerAuth
path Parameters
marketplaceCode
required
string (MarketplaceSourceCode)
Enum: "ETUOVI" "VUOKRAOVI" "OIKOTIE" "KL_TOIMITILAT" "TOIMITILAT_FI"
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
required

Contains the details for the lead.

required
object

Lead details

Responses

Request samples

Content type
application/json
{
  • "lead": {
    }
}

Response samples

Content type
application/json
{
  • "leadId": "ac34ee3b-3f6e-469e-8d02-9fa37f311ccd"
}

Fetch leads

An agent can fetch all the leads for his/her agency offices.

Fetching only changed leads

Use the modifiedAfter parameter to fetch only the leads that have been created or modified since the previous fetch:

  1. Set modifiedAfter to the newest modificationTime received in the previous fetch minus one minute, and startIndex to 0. The overlap ensures that leads which were being saved during the previous fetch are not missed.
  2. Request leads with modifiedAfter, startIndex, sort=modificationTime|asc and size=100.
  3. Take the modificationTime of the last lead in the response, exactly as returned:
    • If it is the same time as modifiedAfter, keep modifiedAfter and increase startIndex by the number of leads in the response.
    • Otherwise, set modifiedAfter to it, and set startIndex to 0. The leads at the end of the response that have this same modificationTime are returned again in the next response.
  4. Repeat from step 2 until the response contains fewer leads than requested with size.

The same lead can be returned more than once, for example because of the overlap or because the lead was modified during the fetch, so update the stored leads by leadId.

Authorizations:
bearerAuth
query Parameters
leadId
Array of strings <uuid> (LeadId) [ items <uuid >^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... ]
Example: leadId=ac34ee3b-3f6e-469e-8d02-9fa37f311ccd

Search by the lead identifier to get a list of leads having these identifiers.

agentId
string <uuid> (AgentId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: agentId=5d2a6d47-da73-4b11-8940-27cffabb6de5

Search by the agent identifier to get a list of leads the agent is associated with.

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 leads that belong to certain agency offices.

leadTypeCode
Array of strings (LeadTypeCode)
Items Enum: "BUYER_REFERRAL" "SELLER_REFERRAL" "REALTY_CONTACT_REQUEST" "PURCHASE_ANNOUNCEMENT_CONTACT_REQUEST" "SHOWING_REQUEST" "MEETING_REQUEST" "PRICE_ESTIMATE_REQUEST" "BROCHURE_REQUEST" "OFFICE_CONTACT_REQUEST" "AGENT_CONTACT_REQUEST" "WATCH_REQUEST" "OTHER_CONTACT_REQUEST" "RENTAL_APPLICATION"
Example: leadTypeCode=SELLER_REFERRAL

Search by the lead type codes to get a list of leads having these lead types.

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 identifier to get a list of leads associated with the party.

leadStatusCode
Array of strings (LeadStatusCode)
Items Enum: "NEW" "IN_PROGRESS" "APPROVED" "REJECTED"
Example: leadStatusCode=NEW

Search by the lead status codes to get a list of leads that have certain statuses.

Array of MarketplaceSourceCode (string) or OtherSourceCode (string) (LeadSourceTypeCode)
Example: leadSourceTypeCode=BANK

Search by the lead source types to get a list of leads that have certain lead source types.

spamClassificationCode
Array of strings (SpamClassification)
Items Enum: "NOT_CLASSIFIED" "LEGITIMATE" "SUSPICIOUS" "SPAM"
Example: spamClassificationCode=NOT_CLASSIFIED&spamClassificationCode=LEGITIMATE&spamClassificationCode=SUSPICIOUS

Search by the spam classifications to get a list of leads that have certain spam classifications.

realtyFriendlyId
string
Example: realtyFriendlyId=D66927

Search by the realty identifier to get a list of leads associated with the realty.

modifiedAfter
string <date-time> (Timestamp)
Example: modifiedAfter=2026-10-28T09:10:39.284Z

Search by modification time to get a list of leads created or modified on or after the specified time.

The time must include a time offset, for example 2026-10-28T09:10:39.284Z or 2026-10-28T11:10:39.284+02:00. The + sign must be URL-encoded as %2B.

See the endpoint description for how to fetch only changed leads.

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

Paginate leads starting from this index. Index starts from 0.

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

Leads returned per page.

sort
Array of strings[ items^(effectiveCreationTime|modificationTime)\|(a... ]
Example: sort=effectiveCreationTime|desc

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

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

When sort or modifiedAfter is given, leads with equal sort field values are always returned in the same order.

When modifiedAfter is given without sort, leads are sorted by modificationTime|asc.

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

Create a lead

Create a new lead. The lead can arrive from a marketplace or from a partner.

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
required

Contains the details for the lead.

required
object (LeadWrite)

Lead details

Responses

Request samples

Content type
application/json
{
  • "lead": {
    }
}

Response samples

Content type
application/json
{
  • "leadId": "ac34ee3b-3f6e-469e-8d02-9fa37f311ccd"
}

Update a lead

Update details for the specified lead.

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

A unique id which identifies the lead.

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
required

Contains the details for the lead.

leadStatusCode
required
string (LeadStatusCode)
Enum: "NEW" "IN_PROGRESS" "APPROVED" "REJECTED"

Lead status. The status defines if the lead is approved or rejected. Possible values are:

  • NEW. The lead has been received and it's new.
  • IN_PROGRESS. An agent has started working on the lead.
  • APPROVED. The lead has been approved by the agent. An approved lead may be linked to a party.
  • REJECTED. The lead has been rejected by the agent.
leadActionCodes
Array of strings (LeadActionCode)
Items Enum: "CONTACTED" "BROCHURE_SENT" "SHOWING_BOOKED" "MEETING_BOOKED" "NOT_INTERESTED" "NO_RESPONSE" "WATCH_ADDED"
required
object (LeadUpdate)

Lead update

Responses

Request samples

Content type
application/json
{
  • "leadStatusCode": "APPROVED",
  • "leadActionCodes": [
    ],
  • "lead": {
    }
}

Response samples

Content type
application/json
{ }

Outgoing Lead

Outgoing Lead API allows an agent to manage all the outgoing leads for his/her agency offices and create a lead for a partner.

Fetch leads

An agent can fetch all the outgoing leads for his/her agency offices.

Authorizations:
bearerAuth
query Parameters
leadId
Array of strings <uuid> (LeadId) [ items <uuid >^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... ]
Example: leadId=ac34ee3b-3f6e-469e-8d02-9fa37f311ccd

Search by the lead identifier to get a list of outgoing leads having these identifiers.

agentId
string <uuid> (AgentId) ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: agentId=5d2a6d47-da73-4b11-8940-27cffabb6de5

Search by the agent identifier to get a list of outgoing leads the agent is associated with.

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 outgoing leads that were sent by certain agency offices.

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 identifier to get a list of outgoing leads associated with the 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 identifier to get a list of outgoing leads associated with the realty.

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

Paginate leads starting from this index. Index starts from 0.

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

Leads returned per page.

sort
Array of strings[ items^(creationTime)\|(asc|ASC|desc|DESC)$ ]
Example: sort=creationTime|desc

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

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

header Parameters
Request-ID
required
string <uuid>
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,
  • "leads": [
    ]
}

Create an outgoing lead

Create a new outgoing lead. The lead will be sent to a partner.

You can optionally include a list of document IDs that will be used to generate download links from the document API. The user must have access to the documents, otherwise the request will fail.

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
required

Contains the details for the lead.

required
object (OutgoingLead)

Lead details

required
object
required
object
documentIds
Array of strings <uuid> (DocumentId) [ items <uuid >^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8... ]

List of document IDs to be used for generating download links via the document API.

Responses

Request samples

Content type
application/json
{
  • "lead": {
    },
  • "customer": {
    },
  • "sender": {
    }
}

Response samples

Content type
application/json
{
  • "leadId": "ac34ee3b-3f6e-469e-8d02-9fa37f311ccd"
}

Create document download URLs for an outgoing lead

Retrieves document download URLs for the specified outgoing lead. The URLs can be used to access attached documents directly.

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

A unique id which identifies the lead.

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
required

Optional configuration for document download URLs

expiryDays
integer [ 1 .. 90 ]

Number of days until the download URLs expire. Defaults to 14 days if not specified.

Responses

Request samples

Content type
application/json
{
  • "expiryDays": 30
}

Response samples

Content type
application/json
{}