# Kyero Agency Profile API Documentation

Scrappa's `GET /api/kyero/agent` returns the public profile of one Kyero estate agency. Send the `path` from the agency directory, or `id`, `slug` and `country`.

## What you get

`agent` has the name, logo, cover photo, `about` text, languages, address, town-level position, team members with job titles, services, `member_since`, listing counts and `portfolios` (price range, typical bedrooms and the places where the agency lists). `properties_for_sale` and `properties_to_rent` give a preview of the first listings with the real total in `count`.

## Listing preview

Kyero shows only the first listings on the profile page. The preview cannot be paged. Use the search endpoint to browse inventory.

## Contact details

Phone and WhatsApp numbers are hidden by Kyero and are not returned. `has_telephone` and `has_whatsapp` tell you whether the agency offers them.

- **Documentation:** [https://scrappa.co/docs/kyero-api/kyero_agent](https://scrappa.co/docs/kyero-api/kyero_agent)
- **API group:** Kyero API
- **Endpoint:** `GET https://scrappa.co/api/kyero/agent`

## 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 |
| --- | --- | --- | --- |
| `path` | string | No | Profile path from the agency directory, for example /en/spain/estate-agents/profile/roccabox-property-group-a14222. Or send id, slug and country. |
| `id` | integer | No | Agency id. Send with slug and country when no path is used. |
| `slug` | string | No | Agency slug, for example roccabox-property-group. |
| `country` | string | No | es, pt, it or fr. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/kyero/agent?path=%2Fen%2Fspain%2Festate-agents%2Fprofile%2Froccabox-property-group-a14222"
```

## Example response

```json
{
    "success": true,
    "country": "es",
    "agent": {
        "id": 14222,
        "name": "Roccabox Property Group",
        "slug": "roccabox-property-group",
        "logo_url": "https://img.kyero.com/fit/125x125/agents/logos/14/14222.jpg",
        "cover_photo_url": "https://img.kyero.com/crop/800x256/agents/cover-photos/14/14222.jpg",
        "about": "Award-winning luxury real estate agency on the Costa del Sol.",
        "languages": [
            "en",
            "da",
            "de",
            "es"
        ],
        "has_telephone": true,
        "has_whatsapp": true,
        "address": {
            "street": "Calle Los Jazmines 468, Nueva Andaluc\u00eda",
            "town": "Marbella",
            "region": "M\u00e1laga",
            "postcode": "29660",
            "country": "Spain",
            "formatted": "Calle Los Jazmines 468, Nueva Andaluc\u00eda, Marbella, 29660, M\u00e1laga, Spain"
        },
        "team_members": [
            {
                "id": 4708,
                "name": "Paola Ruiz",
                "job_title": "Property Consultant",
                "languages": [
                    "en",
                    "es"
                ],
                "image_url": "https://img.kyero.com/fit/340x320/agents/team-member-photos/4/4708.jpg"
            }
        ],
        "member_since": 2020,
        "for_sale_count": 1461,
        "long_term_rent_count": 0,
        "path": "/en/spain/estate-agents/profile/roccabox-property-group-a14222"
    },
    "properties_for_sale": {
        "count": 1461,
        "returned": 8,
        "items": [
            {
                "id": 21361013,
                "name": "Apartment in Marbella, Malaga",
                "price": 350000,
                "price_formatted": "\u20ac 350,000",
                "payment_scheme": "for_sale",
                "reference_no": "EI-AC2137",
                "location_id": 31673,
                "property_type": {
                    "id": 1,
                    "key": "apartment",
                    "group_id": 1
                },
                "bedrooms": 3,
                "bathrooms": 2,
                "built_m2": 100,
                "plot_m2": 0,
                "short_description": "Discover a collection of 34 extraordinary apartments and penthouses...",
                "images": [
                    "https://img.kyero.com/crop/960x720/properties/21361/21361013/428410368.jpg"
                ],
                "images_count": 31,
                "feature_keys": [
                    "garage",
                    "lift",
                    "terrace",
                    "pool",
                    "new_build"
                ],
                "badges": [
                    "video_tour",
                    "remote_viewing"
                ],
                "primary_badge": "new_build",
                "featured": false,
                "virtual_tour_url": null,
                "video_url": "https://vimeo.com/1025703918",
                "remote_viewing_enabled": true,
                "agent": {
                    "id": 14222,
                    "name": "Example Agency",
                    "logo_url": "https://img.kyero.com/fit/125x125/agents/logos/14/14222.jpg",
                    "type": "2",
                    "prime": true,
                    "path": "/en/spain/estate-agents/profile/example-agency-a14222",
                    "url": "https://www.kyero.com/en/spain/estate-agents/profile/example-agency-a14222"
                },
                "path": "/en/property/21361013-apartment-for-sale-marbella",
                "url": "https://www.kyero.com/en/property/21361013-apartment-for-sale-marbella"
            }
        ]
    },
    "properties_to_rent": {
        "count": 0,
        "returned": 0,
        "items": []
    },
    "meta": {
        "billable": true,
        "attempts": 1,
        "last_status": 200,
        "endpoint_family": "agent"
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 404 | Not Found | Kyero has no page for this request, for example a listing that is no longer online (`not_found`). Non-billable. |
| 422 | Validation Error | A query parameter failed validation, or a path, id or slug is unusable (`invalid_parameter`). Non-billable. |
| 503 | Upstream Unavailable | Kyero could not be reached after retries, answered a different page than requested, did not apply the filters, or answered with a body this API cannot read (`upstream_unavailable`, `upstream_blocked`, `pagination_mismatch`, `filter_not_honoured`, `parser_drift`). Retryable and never billed. Clients are never rate limited. |

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