OviPro logo
API docs by Redocly

Lead API (1.0)

Download OpenAPI specification:Download

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.

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.

Lead

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

Fetch leads

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

Authorizations:
bearerAuth
query Parameters
leadId
Array of strings <uuid> (LeadId)
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)
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"
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: "UNASSIGNED" "ASSIGNED" "APPROVED" "REJECTED"
Example: leadStatusCode=UNASSIGNED

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

leadSourceTypeCode
Array of strings (LeadSourceTypeCode)
Items Value: "BANK"
Example: leadSourceTypeCode=BANK

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

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
Example: sort=validAfter|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 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

Contains the details for the lead.

required
object (Lead)

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

Contains the details for the lead.

leadStatusCode
required
string (LeadStatusCode)
Enum: "UNASSIGNED" "ASSIGNED" "APPROVED" "REJECTED"

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

  • UNASSIGNED. The lead has been received and it's unassigned.
  • ASSIGNED. The lead has been be assigned to the agent.
  • 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.
required
object (LeadUpdate)

Lead update

Responses

Request samples

Content type
application/json
{
  • "leadStatusCode": "APPROVED",
  • "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)
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)
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)
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
Example: sort=validAfter|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.

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

Contains the details for the lead.

required
object (OutgoingLead)

Lead details

required
object
required
object

Responses

Request samples

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

Response samples

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