# Immoweb Agency API Documentation

Scrappa's `GET /api/immoweb/agencies` endpoint lists Belgian estate agencies, and the developers behind new-build projects.

## What a record contains

Each agency carries its name, description, logo, Belgian IPI registration number, location with coordinates, and a weekly opening-hours timetable with appointment requirements. Agency type distinguishes agencies, real estate agencies, companies and property developers — the last being how new-build developers surface, since no separate project entity is published.

## Two shapes from one endpoint

By default the response lists agency networks and groups — records carrying `groupInfo` with the network name, logo and live active-listing counts broken down by sale and rent. Pass `byGroup=false` to get individual agency records instead, which carry `publicInfo`, `timetable` and `location` at the top level. The two shapes differ, so read the record type you asked for.

This endpoint has no paging parameter and returns at most 100 records per call, so `returned` is the number of rows in this response — not the size of the directory. Belgian directories exceed that; narrow by agency type or language rather than assuming the list is complete.

## Finding an agency's listings

Every agency record carries the identifier you pass as `customerIds` to [Immoweb Search](/docs/immoweb-api/immoweb_search), which returns that agency's listings directly. No join endpoint is needed.

## Contact details are removed

Business email addresses and telephone numbers present in the upstream directory are stripped before the response is returned. Agency name, logo, IPI number, location and opening hours are all retained.

## Languages

Pass `language` as `nl`, `fr` or `en`. Bare two-letter codes only. Human French and Dutch descriptions are published alongside the default description.

- **Documentation:** [https://scrappa.co/docs/immoweb-api/immoweb_agencies](https://scrappa.co/docs/immoweb-api/immoweb_agencies)
- **API group:** Immoweb API
- **Endpoint:** `GET https://scrappa.co/api/immoweb/agencies`

## 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 |
| --- | --- | --- | --- |
| `byGroup` | boolean | No | Return agency networks and groups (default) or individual agencies when false. |
| `language` | string | No | nl, fr or en. Bare two-letter codes only; defaults to nl. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/immoweb/agencies?byGroup=false"
```

## Example response

```json
{
    "success": true,
    "returned": 1,
    "page_limit": 100,
    "by_group": false,
    "agencies": [
        {
            "id": 90001334,
            "type": "AGENCY",
            "location": {
                "geoPoint": {
                    "latitude": 51.05,
                    "longitude": 3.72
                },
                "address": {
                    "postalCode": "9000",
                    "locality": "Gent"
                }
            },
            "publicInfo": {
                "name": "Example Agency",
                "description": "Vastgoedagentsuur",
                "alternativeDescriptions": {
                    "fr": "Agence immobili\u00e8re",
                    "nl": "Vastgoedagentsuur"
                },
                "ipiNo": "BE-000000"
            },
            "timetable": [
                {
                    "dayOfTheWeek": "MONDAY",
                    "openingHours": [
                        {
                            "from": "09:00",
                            "to": "17:00",
                            "appointmentRequired": false
                        }
                    ]
                }
            ]
        }
    ]
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | One or more query parameters failed validation. No credits are charged. |
| 503 | Upstream Unavailable | One upstream lookup per request. A failed lookup is never billed. |

## 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)