Alma logo
API docs by Redocly

Agency API (1.0)

Download OpenAPI specification:Download

Introduction

The Agency API provides endpoints for agencies, agency offices and agents.

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.

Agencies

Agency API allows you to query agencies.

Find the agencies of an agent

Finds the agencies which are visible to the specified agent.

Authorizations:
bearerAuth
query Parameters
agentId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: agentId=b0d2a485-6a73-468a-9acc-d8ce9b620b3d

A unique id which identifies the agent.

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.

Responses

Response samples

Content type
application/json
{
  • "agencies": [
    ]
}

Find the specified agency

Finds the specified agency.

Authorizations:
bearerAuth
path Parameters
agencyId
required
string <uuid>
Example: 3ee33c0c-312b-49f6-b5b3-98e2cbaf832f

A unique id which identifies the agency.

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.

Responses

Response samples

Content type
application/json
{
  • "agencyId": "56956001-28b7-4f57-b7e5-cc32acf4adfb",
  • "agencyNumber": 1021,
  • "agencyOrganizationGroupId": "4ba0a05e-6a35-4a79-a556-ec2a2a0e1dac",
  • "businessIdentification": {
    },
  • "invoicing": {
    },
  • "marketingName": "Kiinteistöykkönen Pirkanmaa",
  • "officialName": "Kiinteistöykkönen Pirkanmaa Oy LKV",
  • "visitingAddress": {
    }
}

AgencyOffices

Agency Office API allows you to query agency offices.

Finds agency offices by using the specified search criteria.

Finds agency offices by using the specified search criteria. The search logic is explained in the following:

  • If only the agencyId is given, this endpoint returns the offices of the specified agency which are visible to the authenticated user.
  • If only the the agentId is given, this endpoint returns all offices which are visible to the specified user.
  • If both agencyId and agentId are given, this endpoint returns the offices of the specified agency which are visible to the specified user.
  • If no search parameters are given, this endpoint returns all offices which are visible to the authenticated user.
Authorizations:
bearerAuth
query Parameters
agencyId
string <uuid>
Example: agencyId=16327644-e026-482d-9670-00334cbd631f

A unique identifier of an agency.

agentId
string <uuid>
Example: agentId=b44e1a5b-2c3b-4ed1-b559-2093437da4c5

A unique identifier of an agent.

modifiedAfter
string <date-time>
Example: modifiedAfter=2021-11-12T12:34:56+02:00

The date and time after which the object were modified.

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.

Responses

Response samples

Content type
application/json
{
  • "agencyOffices": [
    ]
}

Find the specified agency office

Finds the specified agency office.

Authorizations:
bearerAuth
path Parameters
agencyOfficeId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: edf9fb6b-00d6-4769-812e-d0c93a584c7b

A unique id which identifies the agency office.

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.

Responses

Response samples

Content type
application/json
{
  • "agencyOfficeId": "edf9fb6b-00d6-4769-812e-d0c93a584c7b",
  • "agencyOfficeNumber": 1055,
  • "agency": {
    },
  • "agencyOrganizationGroup": {
    },
  • "contacts": [
    ],
  • "name": "Kiinteistöykkönen Tampere",
  • "marketingName": [
    ],
  • "description": [
    ],
  • "currentNewsDescription": [
    ],
  • "location": {
    },
  • "postalAddress": {
    },
  • "visitingAddress": {
    },
  • "contracts": [
    ],
  • "tags": [
    ],
  • "links": [],
  • "contactRecipientCode": "RESPONSIBLE_AGENT",
  • "agentSortOrderCode": "RANDOM",
  • "recommendation": {
    },
  • "phoneDescription": [
    ],
  • "financialAccounts": [
    ],
  • "financialAccountForDownPayments": {
    },
  • "billing": {
    },
  • "branding": {
    }
}

Update the specified agency office

Updates the specified agency office.

Authorizations:
bearerAuth
path Parameters
agencyOfficeId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: edf9fb6b-00d6-4769-812e-d0c93a584c7b

A unique id which identifies the agency office.

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.

Request Body schema: application/json

Contains the updated agency office.

agencyOfficeId
required
string <uuid> (AgencyOfficeId)

An unique identifies of the agency office.

Array of objects (AgencyOfficeMarketingName)

An array which contains the different translations.

Array of objects (AgencyOfficeDescription)

An array which contains the different translations.

Array of objects (CurrentNewsDescription)

An array which contains the different translations.

Array of objects (Tags)

Tag which classifies the agency office. An agency office can have several tags.

Array of objects (Link)

Additional links for the agency office, for example to a privacy statement.

Array of objects (SupplierAssignedIdentifiers)

Identifiers assigned for the entity in other systems.

contactRecipientCode
string (ContactRecipientCode)
Enum: "RESPONSIBLE_AGENT" "AGENCY_OFFICE" "AGENCY"

Identifies the contact type to whom the contacts are delivered. Possible values are:

  • 'RESPONSIBLE_AGENT' means that the contacts are delivered to the responsible agent.
  • 'AGENCY_OFFICE' means that the contacts are delivered to the agency office.
  • 'AGENCY' means that the contacts are delivered to the agency.
agentSortOrderCode
string (AgentSortOrderCode)
Enum: "AGENT_NAME" "RANDOM" "NEWEST" "MOST_RECOMMENDED"

Identifies the sort order of the agents. This is an additional guidance for the API caller using agent search. Possible values are:

  • 'AGENT_NAME' means that the agents are sorted by name.
  • 'RANDOM' means that the agents are sorted randomly.
  • 'NEWEST' means that the agents are sorted by newest.
  • 'MOST_RECOMMENDED' means that the agents are sorted by most recommended.
object (Recommendation)
Array of objects (PhoneDescription)

An array which contains the different translations.

Array of objects (FinancialAccount)

Financial accounts for the agency office.

object (FinancialAccount)
object (Billing)

Billing information

object (Branding)

Branding information

reportingName
string (AgencyOfficeReportingName)

The reporting name of the agency office.

Responses

Request samples

Content type
application/json
{
  • "agencyOfficeId": "edf9fb6b-00d6-4769-812e-d0c93a584c7b",
  • "marketingName": [
    ],
  • "description": [
    ],
  • "currentNewsDescription": [
    ],
  • "tags": [
    ],
  • "links": [],
  • "supplierAssignedIdentifiers": [
    ],
  • "contactRecipientCode": "RESPONSIBLE_AGENT",
  • "agentSortOrderCode": "RANDOM",
  • "recommendation": {
    },
  • "phoneDescription": [
    ],
  • "financialAccounts": [
    ],
  • "financialAccountForDownPayments": {
    },
  • "billing": {
    },
  • "branding": {
    }
}

Response samples

Content type
application/json
{
  • "errorCode": "BAD_REQUEST_BODY",
  • "message": "Invalid request body",
  • "errors": [
    ]
}

Update the coordinates of the specified agency office

Updates the coordinates of the specified agency office.

Authorizations:
bearerAuth
path Parameters
agencyOfficeId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: edf9fb6b-00d6-4769-812e-d0c93a584c7b

A unique id which identifies the agency office.

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.

Request Body schema: application/json

Contains the new coordinates of the specified agency office.

latitude
required
number <double>

A geographic coordinate that specifies the north–south position of a point on the Earth's surface.

longitude
required
number <double>

A geographic coordinate that specifies the east–west position of a point on the Earth's surface.

Responses

Request samples

Content type
application/json
{
  • "latitude": 61.48662,
  • "longitude": 23.24047
}

Response samples

Content type
application/json
{
  • "errorCode": "BAD_REQUEST_BODY",
  • "message": "Invalid request body",
  • "errors": [
    ]
}

Update the contact for the specified agency office

Updates the contact for the specified agency office. The response body of the HTTP request contains an array which contains the new contact for the given agency office.

Authorizations:
bearerAuth
path Parameters
agencyOfficeId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: edf9fb6b-00d6-4769-812e-d0c93a584c7b

A unique id which identifies the agency office.

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.

Request Body schema: application/json

Contains the updated or created contact and office description.

If the id of the contact isn't specified, a new contact is added. If the id of the contact is specified, the existing contact is updated.

If an existing contact isn't found from this array, it will be deleted from the database.

Note that this array can contain multiple items.

required
Array of objects (Contacts)

Contains the contact details for the agency office

Array of objects (AgencyOfficeDescription)

An array which contains the different translations.

Responses

Request samples

Content type
application/json
{
  • "contacts": [],
  • "officeDescription": [
    ]
}

Response samples

Content type
application/json
{
  • "errorCode": "BAD_REQUEST_BODY",
  • "message": "Invalid request body",
  • "errors": [
    ]
}

Public Agents

Find the public agents of the agency office

Finds the public agents of the specified agency office.

Authorizations:
bearerAuth
path Parameters
agencyOfficeId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: edf9fb6b-00d6-4769-812e-d0c93a584c7b

A unique id which identifies the agency office.

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.

Responses

Response samples

Content type
application/json
{
  • "agents": [
    ]
}

Add a public agent to the agency office

Adds a public agent to the specified agency office.

Authorizations:
bearerAuth
path Parameters
agencyOfficeId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: edf9fb6b-00d6-4769-812e-d0c93a584c7b

A unique id which identifies the agency office.

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.

Request Body schema: application/json

Contains the public agent to be added to the specified agency office.

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

The unique id of the agent.

Responses

Request samples

Content type
application/json
{
  • "agentId": "57f60566-75d6-481a-bdc8-c85c0ed82ca0"
}

Response samples

Content type
application/json
{
  • "errorCode": "BAD_REQUEST_PARAMETERS",
  • "message": "Invalid request parameters."
}

Delete a public agent from the agency office

Deletes a public agent from the specified agency office.

Authorizations:
bearerAuth
path Parameters
agencyOfficeId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: edf9fb6b-00d6-4769-812e-d0c93a584c7b

A unique id which identifies the agency office.

agentId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: edf9fb6b-00d6-4769-812e-d0c93a584c7b

A unique id which identifies the agent.

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.

Responses

Response samples

Content type
application/json
{ }

Agents

Find agents

Finds all agents with specified search parameters.

Authorizations:
bearerAuth
query Parameters
agencyOfficeId
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: agencyOfficeId=38046447-49ba-4379-a36c-348a96b321b1

A unique id which identifies the agency office.

modifiedAfter
string <date-time>
Example: modifiedAfter=2021-11-12T12:34:56+02:00

The date and time after which the object were modified.

agentId
Array of strings <uuid>
Example: agentId=edf9fb6b-00d6-4769-812e-d0c93a584c7b&agentId=abdb48eb-19d8-4b98-a045-63acf3306e79

A unique id which identifies the agent.

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.

Responses

Response samples

Content type
application/json
{
  • "agents": [
    ],
  • "totalCount": 1
}

Find an agent

Finds an agent with the specified id.

Authorizations:
bearerAuth
path Parameters
agentId
required
string <uuid> ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: edf9fb6b-00d6-4769-812e-d0c93a584c7b

A unique id which identifies the agent.

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.

Responses

Response samples

Content type
application/json
{
  • "agentId": "ecddaeca-160a-46c4-987a-075942a4c512",
  • "firstName": "Ville",
  • "lastName": "Välittäjä",
  • "emailAddress": "ville.valittaja@example.com",
  • "phoneNumber": "+358 40 123 4567",
  • "title": "LKV",
  • "description": "Olen kokenut kiinteistönvälittäjä ja toiminut alalla jo 10 vuotta.",
  • "birthDate": "1985-05-12",
  • "languages": [
    ],
  • "degrees": [
    ],
  • "customerFeedback": {
    },
  • "recommendation": {
    },
  • "specialSkills": [
    ],
  • "contacts": [
    ],
  • "profilePictureUrl": "//d9zbdvy28211i.cloudfront.net/{imageParameters}/eomqa1media/ovi/business_user_profile/76/e0e4c4eb-f1de-44ce-9714-5c9a7cdba7aa.png",
  • "supplierAssignedIdentifiers": [
    ],
  • "publicAgentAgencyOfficeIds": [
    ],
  • "state": "ACTIVE",
  • "defaultAgencyOfficeId": "ec88251c-f299-4b5c-8252-8deb6d3873d7",
  • "modificationTime": "2019-01-01T12:00:00Z"
}