Oikotie Agency API returns an agency profile: names, business id, address, website, phone, logo, images, parent company and branches. Send the company_id (the agency.id of a search item) for one lookup. Send a card_id instead to find the agency of a listing, which costs one extra lookup. A private listing has no agency and answers with agency null and status 200.
Set include_brokers to true to add the broker list with name, title, phone, email, specialty and language skills. This costs one extra lookup. Only data the agency publishes is returned; an agency that hides its phone number or address keeps it hidden. An unknown agency is a 404 and is not billable.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
This endpoint has no required query parameters.
3 optional filters available.
integer
Optional
Agency id from the agency.id field of a search item. Send company_id or card_id.
1234567890
integer
Optional
Listing id. Finds the agency of the listing with one extra lookup.
1234567890
boolean
Optional
true to add the broker list. One extra lookup.
true
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
meta
success
{
"data": {
"agency": {
"id": 14641782,
"url": "https://asunnot.oikotie.fi/yritys/bo-lkv/bo-lkv-espoo-14641782",
"logo": "https://cdn.asunnot.oikotie.fi/SNC-xPX-rQsz54hUG3EtRXeKUOQ=/full-fit-in/623x464/filters:watermark(https://cdn.asunnot.oikotie.fi/iaTBje2arSZdB17zrOD9jfusIlo=/static.asunnot.oikotie.fi/oikotie-watermark.png,24,-24,0):background_color(white):format(jpeg)/ot-real-estate-mediabank-prod/513/195/source/214591315",
"name": "Bo LKV | Espoo",
"title": null,
"images": [
"https://cdn.asunnot.oikotie.fi/s7wHXvbP2fXRpyToJSR6G-D1CIk=/full-fit-in/623x464/filters:watermark(https://cdn.asunnot.oikotie.fi/iaTBje2arSZdB17zrOD9jfusIlo=/static.asunnot.oikotie.fi/oikotie-watermark.png,24,-24,0):background_color(white):format(jpeg)/ot-real-estate-mediabank-prod/161/375/source/214573161"
],
"parent": {
"id": 14739921,
"name": "Bo LKV"
},
"contact": {
"fax": null,
"email": null,
"phone": "0408086832",
"website": "http://www.bo.fi/"
},
"children": [],
"location": {
"city": "Espoo",
"street": "Mets\u00e4nneidonkuja 10",
"postcode": "02130",
"coordinates": null,
"opening_hours": null
},
"oikotie_id": 201565,
"business_id": "2796763-3",
"description": null,
"external_id": "KIVI-36050",
"official_name": "Bo LKV Oy"
},
"brokers": [
{
"id": 22264796,
"url": "https://asunnot.oikotie.fi/yritys/example/test-broker-1",
"name": "Test Broker 1",
"email": "broker@example.com",
"image": "https://cdn.asunnot.oikotie.fi/uG8HJOgSnt7ziwbmBTEpNAFWW2E=/200x200/smart/filters:background_color(white):format(jpeg)/ot-real-estate-mediabank-prod/995/119/source/217911599",
"phone": "040 000 0000",
"title": "Asuntomyyj\u00e4, partner",
"specialty": null,
"presentation": null,
"language_skills": null
},
{
"id": 16837011,
"url": "https://asunnot.oikotie.fi/yritys/example/test-broker-2",
"name": "Test Broker 2",
"email": null,
"image": "https://cdn.asunnot.oikotie.fi/qR9LSXh3M1DbX6aQ-5Xd1WKne28=/200x200/smart/filters:background_color(white):format(jpeg)/ot-real-estate-mediabank-prod/116/768/source/227867611",
"phone": "040 000 0001",
"title": "kiinteist\u00f6nv\u00e4litt\u00e4j\u00e4 LKV,LVV, partner",
"specialty": null,
"presentation": null,
"language_skills": null
}
]
},
"meta": {
"billable": true,
"endpoint_family": "agency"
},
"success": true
}Errors
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
A required parameter or a value is invalid. This response is not billable.
{
"errors": {
"company_id": [
"The company id field is required when card id is not present."
]
},
"message": "The request validation failed"
}Not Found
The agency does not exist. This response is not billable.
{
"meta": {
"billable": false,
"retryable": false,
"endpoint_family": "agency"
},
"error": {
"code": "NOT_FOUND",
"message": "The requested resource was not found."
},
"success": false
}Upstream Unavailable
Oikotie could not be reached or returned data that does not match the request. This response is not billable and is retryable.
{
"meta": {
"billable": false,
"retryable": true,
"endpoint_family": "agency"
},
"error": {
"code": "UPSTREAM_UNAVAILABLE",
"message": "Oikotie could not be reached. Please retry shortly."
},
"success": false
}Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.