openapi: 3.1.0
info:
    title: Immoteur Public API
    version: 1.0.0
    description: |-
        Public API for the Immoteur service.

        ## Authentication
        Use a **Personal Access Token** from your Immoteur dashboard and send it in the `Authorization` header:

        ```
        Authorization: Bearer YOUR_TOKEN_HERE
        ```

        ### cURL example
        ```bash
        curl -sS https://api.immoteur.com/public/v1/auth \
          -H "Authorization: Bearer $IMMOTEUR_TOKEN"
        ```

        ## Environments
        - **Production:** `https://api.immoteur.com/public/v1`

        ## Errors & Rate Limiting
        - `400 Bad Request`: malformed request or invalid syntax.
        - `401 Unauthorized`: missing or invalid token.
        - `403 Forbidden`: token valid but not permitted for this resource.
        - `429 Too Many Requests`: back off and retry with exponential delay.
        - `422 Validation Error`: payload is syntactically correct but fails validation.

        ## Pagination
        - Requests specify `page` (1..500). Responses include `page`, `nextPage`, `perPage`, `total`, `totalPages`.

        ## Data Access Limits
        The `meta.dataAccessLimit` block shows **implicit filters** tied to your plan (e.g., whitelisted departments/SIREN/SIRET). Your effective result set equals **your filters ∩ requested filters**.

        ## Using AI/LLMs
        - Always include the `Authorization` header.
        - Prefer explicit filters (departments, INSEE, postcodes) with **existing** French codes/names.
        - Follow the examples below as canonical payload shapes.

        ## Contact & Docs
        - Website: https://immoteur.com
        - Support: Use your customer portal or contact listed on the website.
    contact:
        url: 'https://immoteur.com'
        name: Immoteur
        email: support@immoteur.com
tags:
    -   name: Download
        description: Download classifieds or properties
    -   name: Info
        description: Token/account info
    -   name: Property
        description: Property search
servers:
    -   url: https://api.immoteur.com/public/v1
        description: Production server
externalDocs:
    description: Full product documentation
    url: https://docs.immoteur.com
security:
    -   bearerAuth: [ ]
paths:
    /auth:
        get:
            summary: Get Auth Info
            description: Returns the authenticated user's email and token information as a simple test endpoint.
            operationId: auth
            tags:
                - Info
            responses:
                '200':
                    description: Authenticated account and token information
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - email
                                    - tokenName
                                    - tokenCreatedAt
                                properties:
                                    email:
                                        type: string
                                        format: email
                                        description: Email address of the authenticated account
                                        example: buyer@example.com
                                    tokenCreatedAt:
                                        type: string
                                        format: date-time
                                        description: Creation date of the token
                                        example: '2025-09-01T10:15:30Z'
                                    tokenName:
                                        type: string
                                        description: Name of the current auth token
                                        example: prod-ci-key-1
                            example:
                                email: buyer@example.com
                                tokenCreatedAt: '2025-09-01T10:15:30Z'
                                tokenName: prod-ci-key-1
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '403':
                    $ref: '#/components/responses/ForbiddenError'
                '404':
                    $ref: '#/components/responses/NotFoundError'
                '429':
                    $ref: '#/components/responses/RateLimitError'
                default:
                    $ref: '#/components/responses/DefaultError'

    /download/classifieds:
        get:
            summary: Download classifieds
            description: |-
                Download classifieds filtered by a **source** previously configured in your account (e.g., a webhook source).
                Set `Accept` to match the requested `format`. For `format=jsonl` use `Accept: application/x-ndjson`; for `format=csv` use `Accept: text/csv`.

                ### cURL example (JSONL)
                ```bash
                curl -L "https://api.immoteur.com/public/v1/download/classifieds?format=jsonl&source=webhook&id=0bb3760e-8ff1-45e4-a9d3-dec91687cefa" \
                  -H "Authorization: Bearer $IMMOTEUR_TOKEN" \
                  -H "Accept: application/x-ndjson" \
                  -o classifieds.jsonl
                ```
            operationId: downloadClassifieds
            tags:
                - Download
            parameters:
                -   name: format
                    in: query
                    required: true
                    schema:
                        type: string
                        enum:
                            - csv
                            - jsonl
                    description: Format of file to download
                    example: jsonl
                -   name: source
                    in: query
                    required: true
                    schema:
                        type: string
                        enum:
                            - webhook
                    description: Type of source from which use filters.
                    example: webhook
                -   name: id
                    in: query
                    required: true
                    schema:
                        type: string
                        format: uuid
                    description: ID of the source
                    example: 0bb3760e-8ff1-45e4-a9d3-dec91687cefa
            responses:
                '200':
                    description: JSONL or CSV file containing classifieds.
                    content:
                        application/x-ndjson:
                            schema:
                                type: string
                                format: binary
                        text/csv:
                            schema:
                                type: string
                                format: binary
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '403':
                    $ref: '#/components/responses/ForbiddenError'
                '404':
                    $ref: '#/components/responses/NotFoundError'
                '429':
                    $ref: '#/components/responses/RateLimitError'
                default:
                    $ref: '#/components/responses/DefaultError'

    /properties/search:
        post:
            summary: Search properties with filters
            description: Returns a paginated list of properties based on searchable fields
            operationId: propertySearch
            tags:
                - Property
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - page
                                - transactionType
                                - propertyTypes
                            properties:
                                locationDepartments:
                                    type: array
                                    items:
                                        type: string
                                    description: List of French department codes (e.g., "75" for Paris).
                                    example: ['75', '92']
                                locationInseeCodes:
                                    type: array
                                    items:
                                        type: string
                                    description: List of INSEE city codes.
                                    example: ['75056', '92050']
                                locationPostcodes:
                                    type: array
                                    items:
                                        type: string
                                    description: List of French postcodes.
                                    example: ['75001', '92000']
                                page:
                                    type: integer
                                    minimum: 1
                                    maximum: 500
                                    default: 1
                                    description: 1-based page index.
                                    example: 1
                                propertyAreaMax:
                                    type: integer
                                    description: Maximum property area (m²).
                                    example: 100
                                propertyAreaMin:
                                    type: integer
                                    description: Minimum property area (m²).
                                    example: 40
                                propertyBalconyExists:
                                    type: boolean
                                    description: Filter results to properties that have a balcony.
                                    example: true
                                propertyBedroomCountMin:
                                    type: integer
                                    minimum: 0
                                    description: Minimum number of bedrooms.
                                    example: 2
                                propertyCellarExists:
                                    type: boolean
                                    description: Filter results to properties that have a cellar.
                                    example: false
                                propertyElevatorExists:
                                    type: boolean
                                    description: Filter results to properties that have an elevator.
                                    example: true
                                propertyGarageExists:
                                    type: boolean
                                    description: Filter results to properties that have a garage.
                                    example: false
                                propertyGardenExists:
                                    type: boolean
                                    description: Filter results to properties that have a garden.
                                    example: false
                                propertyIsProgram:
                                    type: boolean
                                    description: Limit to new-build/off-plan programs.
                                    example: false
                                propertyParkingExists:
                                    type: boolean
                                    description: Filter results to properties that have parking.
                                    example: true
                                propertyRoomCountMin:
                                    type: integer
                                    minimum: 0
                                    description: Minimum total room count.
                                    example: 3
                                propertySwimmingPoolExists:
                                    type: boolean
                                    description: Filter results to properties that have a swimming pool.
                                    example: false
                                propertyTerraceExists:
                                    type: boolean
                                    description: Filter results to properties that have a terrace.
                                    example: true
                                propertyTypes:
                                    type: array
                                    items:
                                        $ref: '#/components/schemas/PropertyType'
                                    description: One or more property types to include.
                                    example: ['apartment', 'house']
                                transactionPriceHasChanged:
                                    type: boolean
                                    description: Only properties whose price has changed recently.
                                    example: false
                                transactionPriceMax:
                                    type: integer
                                    description: Maximum current price.
                                    example: 1000000
                                transactionPriceMin:
                                    type: integer
                                    description: Minimum current price.
                                    example: 200000
                                transactionType:
                                    $ref: '#/components/schemas/TransactionType'
                        example:
                            page: 1
                            transactionType: sale
                            propertyTypes: ['apartment', 'house']
                            locationDepartments: ['75', '92']
                            locationInseeCodes: ['75056', '92050']
                            locationPostcodes: ['75001', '92000']
                            transactionPriceMin: 200000
                            transactionPriceMax: 1000000
                            propertyBedroomCountMin: 2
                            propertyAreaMin: 40
                            propertyElevatorExists: true
                            propertyTerraceExists: true
                            propertyParkingExists: true
            responses:
                '200':
                    description: List of properties matching the filters
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - items
                                    - meta
                                properties:
                                    items:
                                        type: array
                                        items:
                                            type: object
                                            required:
                                                - id
                                                - property
                                                - location
                                                - media
                                                - classifieds
                                                - transaction
                                                - meta
                                            properties:
                                                classifieds:
                                                    type: array
                                                    items:
                                                        type: object
                                                        required:
                                                            - id
                                                            - url
                                                        properties:
                                                            id:
                                                                type: string
                                                                format: uuid
                                                                example: 5a97b8d2-0da7-47a7-8a03-1c6d4f3d9c48
                                                            url:
                                                                description: URL of the classified.
                                                                type: string
                                                                format: uri
                                                                example: https://www.seloger.com/annonces/achat/appartement/paris-1er-75/5-pieces/0.htm
                                                energy:
                                                    description: Energy information for the classified.
                                                    $ref: '#/components/schemas/Energy'
                                                id:
                                                    type: string
                                                    format: uuid
                                                    example: 3a8f1d72-3d0b-4ee6-9a83-a7a9a73ae6c2
                                                location:
                                                    description: Location information.
                                                    $ref: '#/components/schemas/Location'
                                                media:
                                                    $ref: '#/components/schemas/Media'
                                                meta:
                                                    $ref: '#/components/schemas/PropertyMeta'
                                                property:
                                                    $ref: '#/components/schemas/Property'
                                                transaction:
                                                    $ref: '#/components/schemas/Transaction'
                                    meta:
                                        type: object
                                        required:
                                            - dataAccessLimit
                                            - page
                                            - nextPage
                                            - perPage
                                            - total
                                            - totalPages
                                        properties:
                                            dataAccessLimit:
                                                description: Inner filters applied to your search, see `https://immoteur.com/en/dashboard/billing`
                                                type: object
                                                required:
                                                    - departments
                                                    - sirens
                                                    - sirets
                                                properties:
                                                    departments:
                                                        type: array
                                                        items:
                                                            type: string
                                                        example: ['75', '92']
                                                    sirens:
                                                        type: array
                                                        items:
                                                            type: string
                                                        example: ['123456789']
                                                    sirets:
                                                        type: array
                                                        items:
                                                            type: string
                                                        example: ['12345678900011']
                                            nextPage:
                                                type: integer
                                                nullable: true
                                                example: 2
                                            page:
                                                type: integer
                                                example: 1
                                            perPage:
                                                type: integer
                                                example: 20
                                            total:
                                                type: integer
                                                example: 240
                                            totalPages:
                                                type: integer
                                                example: 12
                            example:
                                items:
                                    - id: 3a8f1d72-3d0b-4ee6-9a83-a7a9a73ae6c2
                                      propertyArea: 52.5
                                      propertyType: apartment
                                      location:
                                          city:
                                              name: Paris
                                              inseeCode: '75056'
                                          country: france
                                          department: '75'
                                          postcode: '75001'
                                          latitude: 48.8606
                                          longitude: 2.3376
                                      media:
                                          images:
                                              - url: https://images.immoteur.com/sample/apt-paris-1.jpg
                                      classifieds:
                                          - id: 5a97b8d2-0da7-47a7-8a03-1c6d4f3d9c48
                                            url: https://www.seloger.com/annonces/achat/appartement/paris-1er-75/5-pieces/0.htm
                                      energy:
                                          dpe:
                                              date: '2023-05-10'
                                              label: d
                                              value: 180
                                          ges:
                                              date: '2023-05-10'
                                              label: e
                                              value: 45
                                          heating:
                                              source: gas
                                              system: radiator
                                              type: individual
                                      metaFirstSeenAt: '2025-06-20'
                                      propertyBalconyExists: false
                                      propertyBedroomCount: 2
                                      propertyCellarExists: false
                                      propertyElevatorExists: true
                                      propertyGarageExists: false
                                      propertyGardenExists: false
                                      propertyParkingExists: true
                                      propertyRoomCount: 3
                                      propertySwimmingPoolExists: false
                                      propertyTerraceExists: true
                                      transaction:
                                          type: sale
                                          price:
                                              current: 650000
                                              perSquareUnit: 12500
                                meta:
                                    dataAccessLimit:
                                        departments: ['75', '92']
                                        sirens: ['123456789']
                                        sirets: ['12345678900011']
                                    page: 1
                                    nextPage: 2
                                    perPage: 20
                                    total: 240
                                    totalPages: 12
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '403':
                    $ref: '#/components/responses/ForbiddenError'
                '404':
                    $ref: '#/components/responses/NotFoundError'
                '422':
                    $ref: '#/components/responses/ValidationError'
                '429':
                    $ref: '#/components/responses/RateLimitError'
                default:
                    $ref: '#/components/responses/DefaultError'

webhooks:
    classified-notification:
        post:
            summary: Classified created/updated/removed notification.
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/ClassifiedNotification'
                        example:
                            id: 7f6e3b4d-9c22-46a0-8f20-0d1a2b3c4d5e
                            type: created
                            currency: euro
                            squareUnit: squareMeter
                            meta:
                                firstSeenAt: '2025-09-15T08:10:00Z'
                                lastModifiedAt: '2025-09-15T09:00:00Z'
                                lastSeenAt: '2025-09-15T09:00:00Z'
                                removedAt: null
                            source:
                                domain: seloger.com
                                url: https://www.seloger.com/annonces/achat/appartement/paris-1er-75/5-pieces/0.htm
                            publisher:
                                isProfessional: true
                                type: agency
                                id: 2c2a42a0-1a9b-4b18-9f1d-1f9b2a3c4d5e
                                email: contact@agence-paris.fr
                                phone: '+33123456789'
                                feesUrl: https://www.agence-paris.fr/honoraires
                                siren: '123456789'
                            location:
                                city:
                                    name: Paris
                                    inseeCode: '75056'
                                country: france
                                department: '75'
                                postcode: '75001'
                                latitude: 48.8606
                                longitude: 2.3376
                            media:
                                images:
                                    - url: https://images.immoteur.com/sample/apt-paris-1.jpg
                            property:
                                type: apartment
                                area: 50
                                roomCount: 3
                                bedroomCount: 2
                                elevatorExists: true
                                terraceExists: true
                            transaction:
                                type: sale
                                price:
                                    current: 650000
                                    perSquareUnit: 13000
                            energy:
                                dpe:
                                    date: '2023-05-10'
                                    label: d
                                    value: 180
                                ges:
                                    date: '2023-05-10'
                                    label: e
                                    value: 45
                                heating:
                                    source: gas
                                    system: radiator
                                    type: individual
            responses:
                "200":
                    description: Webhook received successfully
                "400":
                    $ref: '#/components/responses/BadRequestError'
                default:
                    $ref: '#/components/responses/DefaultError'

components:
    schemas:
        ClassifiedNotification:
            type: object
            required:
                - id
                - currency
                - meta
                - property
                - source
                - squareUnit
                - publisher
                - transaction
                - location
            properties:
                contact:
                    description: Contact information for the classified.
                    $ref: '#/components/schemas/ClassifiedContact'
                currency:
                    description: Currency of the price.
                    $ref: '#/components/schemas/ClassifiedCurrency'
                description:
                    description: Description of the classified.
                    type: string
                    example: Bel appartement lumineux au cœur de Paris.
                energy:
                    description: Energy information for the classified.
                    $ref: '#/components/schemas/Energy'
                id:
                    description: Unique identifier for the classified.
                    type: string
                    format: uuid
                    example: 7f6e3b4d-9c22-46a0-8f20-0d1a2b3c4d5e
                location:
                    description: Location information for the classified.
                    $ref: '#/components/schemas/Location'
                media:
                    description: Media information for the classified.
                    $ref: '#/components/schemas/Media'
                meta:
                    description: Meta information for the classified.
                    $ref: '#/components/schemas/ClassifiedMeta'
                property:
                    description: Property information for the classified.
                    $ref: '#/components/schemas/Property'
                publisher:
                    description: Publisher information for the classified.
                    $ref: '#/components/schemas/ClassifiedPublisher'
                source:
                    description: Source information for the classified.
                    $ref: '#/components/schemas/ClassifiedSource'
                squareUnit:
                    description: Square unit of the price.
                    $ref: '#/components/schemas/ClassifiedSquareUnit'
                title:
                    description: Title of the classified.
                    type: string
                    example: Appartement 3 pièces Paris 1er
                transaction:
                    description: Transaction information for the classified.
                    $ref: '#/components/schemas/Transaction'
        ClassifiedCurrency:
            type: string
            enum:
                - euro
        ClassifiedSquareUnit:
            type: string
            enum:
                - squareMeter
        PropertyType:
            description: |-
                *   **House**: Residential building sold as an entire unit (e.g., a single-family home, villa, or full residence).
                *   **Apartment**: A single residential unit within a larger building.
                *   **Program**: Refers to new-build or off-plan property developments.
                *   **Shop**: Commercial property with public access, such as boutiques, barbers, or butcher shops.
                *   **Premises**: Non-residential units like cellars, attics, or general storage/local spaces.
                *   **Office**: Properties intended for professional work environments.
                *   **Land**: Plots of terrain, undeveloped or partially developed.
                *   **Building**: An entire non-residential building sold as a unit, such as a hotel or hangar.
                *   **Parking**: Spaces or boxes designed for vehicle storage.
            type: string
            enum:
                - apartment
                - building
                - house
                - land
                - office
                - other
                - parking
                - premises
                - program
                - shop
        ClassifiedContact:
            type: object
            properties:
                email:
                    description: Email address of the contact.
                    type: string
                    format: email
                    example: proprietaire@example.org
                name:
                    description: Name of the contact.
                    type: string
                    example: Jean Dupont
                phone:
                    description: Phone number of the contact (E.164 recommended).
                    type: string
                    format: phone
                    pattern: '^\+?[1-9]\d{1,14}$'
                    example: '+33612345678'
        Energy:
            type: object
            properties:
                dpe:
                    description: DPE energy information.
                    $ref: '#/components/schemas/EnergyDpe'
                ges:
                    description: GES energy information.
                    $ref: '#/components/schemas/EnergyGes'
                heating:
                    description: Heating energy information.
                    $ref: '#/components/schemas/EnergyHeating'
        EnergyDpe:
            type: object
            properties:
                date:
                    type: string
                    format: date
                    example: '2023-05-10'
                label:
                    $ref: '#/components/schemas/EnergyDpeLabel'
                value:
                    type: integer
                    example: 180
        EnergyGes:
            type: object
            properties:
                date:
                    type: string
                    format: date
                    example: '2023-05-10'
                label:
                    $ref: '#/components/schemas/EnergyGesLabel'
                value:
                    type: integer
                    example: 45
        EnergyDpeLabel:
            type: string
            enum:
                - a
                - b
                - c
                - d
                - e
                - f
                - g
        EnergyGesLabel:
            type: string
            enum:
                - a
                - b
                - c
                - d
                - e
                - f
                - g
        EnergyHeating:
            type: object
            properties:
                source:
                    description: Source of heating energy.
                    type: string
                    enum:
                        - aerothermal
                        - biomass
                        - coal
                        - electricity
                        - fuel
                        - gas
                        - geothermal
                        - pellet
                        - solar
                        - wood
                    example: gas
                system:
                    description: Heating system type.
                    type: string
                    enum:
                        - fireplace
                        - floor
                        - radiator
                        - reversibleAirConditioning
                        - stove
                    example: radiator
                type:
                    description: Type of heating system.
                    type: string
                    enum:
                        - city
                        - individual
                        - mixed
                        - shared
                    example: individual
        Location:
            type: object
            required:
                - city
                - country
                - department
                - postcode
            properties:
                city:
                    description: City of the property.
                    $ref: '#/components/schemas/LocationCity'
                country:
                    description: Country of the property.
                    type: string
                    enum:
                        - france
                    example: france
                department:
                    type: string
                    description: French department code (e.g., "75").
                    example: '75'
                latitude:
                    description: Latitude of the property.
                    type: number
                    format: double
                    example: 48.8606
                longitude:
                    description: Longitude of the property.
                    type: number
                    format: double
                    example: 2.3376
                postcode:
                    description: Postcode of the property.
                    type: string
                    example: '75001'
        LocationCity:
            type: object
            required:
                - name
                - inseeCode
            properties:
                inseeCode:
                    description: INSEE code of the city.
                    type: string
                    example: '75056'
                name:
                    description: Name of the city.
                    type: string
                    example: Paris
        Media:
            type: object
            required:
                - images
            properties:
                images:
                    description: Images of the classified.
                    type: array
                    items:
                        $ref: '#/components/schemas/MediaImage'
                    example:
                        - url: https://images.immoteur.com/sample/apt-paris-1.jpg
        MediaImage:
            type: object
            required:
                - url
            properties:
                url:
                    description: URL of the image.
                    type: string
                    format: uri
                    example: https://images.immoteur.com/sample/apt-paris-1.jpg
        ClassifiedMeta:
            type: object
            required:
                - firstSeenAt
                - lastModifiedAt
                - lastSeenAt
            properties:
                firstSeenAt:
                    description: Date the classified was first seen.
                    type: string
                    format: date
                    example: '2025-09-15'
                lastModifiedAt:
                    description: Date the classified was last modified.
                    type: string
                    format: date
                    example: '2025-09-15'
                lastSeenAt:
                    description: Date the classified was last seen.
                    type: string
                    format: date
                    example: '2025-09-15'
                removedAt:
                    description: Date the classified was removed.
                    type: string
                    format: date
        Property:
            type: object
            required:
                - type
            properties:
                airConditioningExists:
                    description: Indicates if the property has air conditioning.
                    type: boolean
                    example: false
                alarmExists:
                    description: Indicates if the property has an alarm system.
                    type: boolean
                    example: false
                area:
                    description: Area of the property.
                    type: number
                    format: float
                    minimum: 0
                    example: 50
                atticExists:
                    description: Indicates if the property has an attic.
                    type: boolean
                    example: false
                balconyArea:
                    description: Area of the balcony.
                    type: number
                    format: float
                    minimum: 0
                    example: 6
                balconyCount:
                    description: Number of balconies.
                    type: integer
                    minimum: 0
                    example: 1
                balconyExists:
                    description: Indicates if the property has a balcony.
                    type: boolean
                    example: false
                bathroomCount:
                    description: Number of bathrooms.
                    type: integer
                    minimum: 0
                    example: 1
                bedroomCount:
                    description: Number of bedrooms in the property.
                    type: integer
                    minimum: 0
                    example: 2
                caretakerExists:
                    description: Indicates if the property has a caretaker.
                    type: boolean
                    example: false
                cellarExists:
                    description: Indicates if the property has a cellar.
                    type: boolean
                    example: false
                constructionYear:
                    description: Year of construction for the property.
                    type: integer
                    minimum: 0
                    example: 1975
                doorCodeExists:
                    description: Indicates if the property has a door code.
                    type: boolean
                    example: true
                elevatorExists:
                    description: Indicates if the property has an elevator.
                    type: boolean
                    example: true
                fireplaceExists:
                    description: Indicates if the property has a fireplace.
                    type: boolean
                    example: false
                floor:
                    description: Floor of the property (Apartment only).
                    type: integer
                    minimum: 0
                    example: 3
                floorCount:
                    description: Total number of floors in the property (Apartment only).
                    type: integer
                    minimum: 0
                    example: 6
                garageExists:
                    description: Indicates if the property has a garage.
                    type: boolean
                    example: false
                gardenExists:
                    description: Indicates if the property has a garden.
                    type: boolean
                    example: false
                intercomExists:
                    description: Indicates if the property has an intercom.
                    type: boolean
                    example: true
                isCondominium:
                    description: Indicates if the property is part of a condominium.
                    type: boolean
                    example: true
                isDisabledFriendly:
                    description: Indicates if the property is disabled friendly.
                    type: boolean
                    example: false
                isDualAspect:
                    description: Indicates if the property has dual aspect.
                    type: boolean
                    example: false
                isNew:
                    description: Indicates if the property is new.
                    type: boolean
                    example: false
                isOccupied:
                    description: Indicates if the property is occupied.
                    type: boolean
                    example: false
                landArea:
                    description: Land area of the property (including house, garden, terrace, entrance, etc.).
                    type: number
                    format: float
                    minimum: 0
                    example: 0
                livingRoomArea:
                    description: Area of the living room.
                    type: number
                    format: float
                    minimum: 0
                    example: 20
                orientation:
                    description: Orientation of the property.
                    type: string
                    enum:
                        - east
                        - north
                        - northEast
                        - northWest
                        - south
                        - southEast
                        - southWest
                        - west
                    example: south
                parkingExists:
                    description: Indicates if the property has parking.
                    type: boolean
                    example: true
                renovationIsNeeded:
                    description: Indicates if renovation is needed.
                    type: boolean
                    example: false
                renovationYear:
                    description: Year of renovation for the property.
                    type: integer
                    minimum: 0
                    example: 2018
                roomCount:
                    description: Number of rooms in the property.
                    type: integer
                    minimum: 0
                    example: 3
                showerRoomCount:
                    description: Number of shower rooms in the property.
                    type: integer
                    minimum: 0
                    example: 1
                swimmingPoolExists:
                    description: Indicates if the property has a swimming pool.
                    type: boolean
                    example: false
                terraceArea:
                    description: Area of the terrace.
                    type: number
                    format: float
                    minimum: 0
                    example: 8
                terraceCount:
                    description: Number of terraces.
                    type: integer
                    minimum: 0
                    example: 1
                terraceExists:
                    description: Indicates if the property has a terrace.
                    type: boolean
                    example: true
                toiletCount:
                    description: Number of toilets.
                    type: integer
                    minimum: 0
                    example: 1
                toiletSeparateExists:
                    description: Indicates if the property has a separate toilet.
                    type: boolean
                    example: true
                type:
                    description: Type of property.
                    $ref: '#/components/schemas/PropertyType'
        PropertyMeta:
            type: object
            required:
                - firstSeenAt
            properties:
                firstSeenAt:
                    description: Date the classified was first seen.
                    type: string
                    format: date
                    example: '2025-09-15'
        ClassifiedPublisher:
            type: object
            required:
                - isProfessional
            properties:
                email:
                    description: Email address of the publisher (if professional).
                    type: string
                    format: email
                    example: contact@agence-paris.fr
                feesUrl:
                    description: URL to the fee information of the publisher (if professional).
                    type: string
                    format: uri
                    example: https://www.agence-paris.fr/honoraires
                id:
                    description: Unique identifier for the publisher.
                    type: string
                    format: uuid
                    example: 2c2a42a0-1a9b-4b18-9f1d-1f9b2a3c4d5e
                isProfessional:
                    description: Indicates if the publisher is a professional.
                    type: boolean
                    example: true
                phone:
                    description: Phone number of the publisher (if professional).
                    type: string
                    format: phone
                    pattern: '^\+?[1-9]\d{1,14}$'
                    example: '+33123456789'
                siren:
                    description: SIREN number of the publisher (if professional).
                    type: string
                    example: '123456789'
                type:
                    description: Type of publisher (if professional).
                    type: string
                    enum:
                        - agency
                        - mandatary
                    example: agency
        Transaction:
            type: object
            required:
                - price
                - type
            properties:
                price:
                    description: Price information for the transaction.
                    $ref: '#/components/schemas/TransactionPrice'
                type:
                    description: Type of transaction.
                    $ref: '#/components/schemas/TransactionType'
        TransactionType:
            type: string
            enum:
                - rent
                - sale
        ClassifiedSource:
            type: object
            required:
                - domain
                - url
            properties:
                domain:
                    description: Domain of the source.
                    type: string
                    example: seloger.com
                url:
                    description: URL of the source.
                    type: string
                    format: uri
                    example: https://www.seloger.com/annonces/achat/appartement/paris-1er-75/5-pieces/0.htm
        TransactionPrice:
            type: object
            required:
                - current
            properties:
                current:
                    description: Current price of the transaction.
                    type: integer
                    minimum: 0
                    example: 650000
                perSquareUnit:
                    description: Price per square unit (only for sale).
                    type: integer
                    minimum: 0
                    example: 12500
    responses:
        DefaultError:
            description: Undocumented error
        BadRequestError:
            description: Bad request — the request could not be understood or was missing required information.
        UnauthorizedError:
            description: Authentication required / invalid token
            content:
                application/json:
                    schema:
                        type: object
                        required:
                            - message
                        properties:
                            message:
                                type: string
                    example:
                        message: "Unauthenticated."
        ForbiddenError:
            description: Authenticated but not allowed for this resource
        RateLimitError:
            description: Too many requests
        ValidationError:
            description: Validation error response
            content:
                application/json:
                    schema:
                        type: object
                        required:
                            - errors
                        properties:
                            errors:
                                type: object
                                additionalProperties:
                                    type: array
                                    items:
                                        type: string
                    example:
                        errors:
                            transactionType:
                                - 'The selected transactionType is invalid.'
                            page:
                                - 'The page must be at least 1.'
        NotFoundError:
            description: Resource not found
    securitySchemes:
        bearerAuth:
            type: http
            scheme: bearer
            bearerFormat: Personal Access Token
            description: |-
                Send your Immoteur Personal Access Token in the `Authorization` header:
                `Authorization: Bearer <token>`
