{
  "openapi": "3.1.0",
  "info": {
    "title": "D'ALMEIDA Properties — agent API",
    "version": "1.0.0",
    "description": "Read-only search of the properties represented by D'ALMEIDA Properties (Cascais, Estoril, Lisbon, Sintra — Portugal), plus a lead endpoint to request a viewing or an off-market search. Licensed estate agency, AMI 27933. Illustrative examples are flagged and carry no price. Exact addresses are never exposed.",
    "contact": {
      "name": "D'ALMEIDA Properties",
      "email": "dalmeida.properties@gmail.com",
      "url": "https://www.dalmeidaproperties.com"
    }
  },
  "servers": [
    {
      "url": "https://www.dalmeidaproperties.com"
    }
  ],
  "paths": {
    "/api/agent/search": {
      "get": {
        "operationId": "searchProperties",
        "summary": "Search properties",
        "parameters": [
          {
            "name": "deal",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "comprar",
                "arrendar"
              ]
            },
            "description": "buy (comprar) or rent (arrendar). Default comprar."
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "house",
                "apartment",
                "building",
                "commercial",
                "office",
                "land",
                "farm",
                "other"
              ]
            }
          },
          {
            "name": "location",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Location slug at any level: lisboa, cascais, estoril, quinta-da-marinha, marques-de-pombal…"
          },
          {
            "name": "price_min",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "price_max",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "area_min",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "m²"
          },
          {
            "name": "area_max",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "bedrooms",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "minimum bedrooms"
          },
          {
            "name": "bathrooms",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "features",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "comma-separated keys: garagem, elevador, varanda, terraco, jardim, piscina, vistaMar"
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pt",
                "en"
              ]
            }
          },
          {
            "name": "include_illustrative",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching properties",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/listing/{id}": {
      "get": {
        "operationId": "getProperty",
        "summary": "One property by id (slug)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pt",
                "en"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Property"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/api/agent/company": {
      "get": {
        "operationId": "getCompany",
        "summary": "Agency identity, licence, contacts, areas and vocabulary",
        "responses": {
          "200": {
            "description": "Company info"
          }
        }
      }
    },
    "/api/agent/lead": {
      "post": {
        "operationId": "createLead",
        "summary": "Request a viewing, a valuation or an off-market search on behalf of a person (with their consent)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "firstName",
                  "lastName",
                  "email"
                ],
                "properties": {
                  "firstName": {
                    "type": "string"
                  },
                  "lastName": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "phone": {
                    "type": "string"
                  },
                  "intent": {
                    "type": "string",
                    "enum": [
                      "buy",
                      "sell",
                      "rent",
                      "valuation",
                      "off-market",
                      "viewing"
                    ]
                  },
                  "propertyId": {
                    "type": "string"
                  },
                  "notes": {
                    "type": "string"
                  },
                  "consent": {
                    "type": "boolean",
                    "description": "The person agreed to be contacted. Required."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Delivered"
          },
          "422": {
            "description": "Missing fields or consent"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    }
  }
}