# Oikotie Agency API Documentation

<p><strong>Oikotie Agency API</strong> returns an agency profile: names, business id, address, website, phone, logo, images, parent company and branches. Send the <code>company_id</code> (the <code>agency.id</code> of a search item) for one lookup. Send a <code>card_id</code> instead to find the agency of a listing, which costs one extra lookup. A private listing has no agency and answers with <code>agency</code> null and status 200.</p><p>Set <code>include_brokers</code> 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.</p>

- **Documentation:** [https://scrappa.co/docs/oikotie-api/oikotie_agency](https://scrappa.co/docs/oikotie-api/oikotie_agency)
- **API group:** Oikotie API
- **Endpoint:** `GET https://scrappa.co/api/oikotie/agency`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `company_id` | integer | No | Agency id from the agency.id field of a search item. Send company_id or card_id. |
| `card_id` | integer | No | Listing id. Finds the agency of the listing with one extra lookup. |
| `include_brokers` | boolean | No | true to add the broker list. One extra lookup. |

## Example response

```json
{
    "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

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A required parameter or a value is invalid. This response is not billable. |
| 404 | Not Found | The agency does not exist. This response is not billable. |
| 503 | Upstream Unavailable | Oikotie could not be reached or returned data that does not match the request. This response is not billable and is retryable. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)