LivinIsto — home watch

Use this when the user asks LivinIsto to keep watching Slovak property listings (flats, houses, cottages, plots; for sale or rent) for them over time (e.g. "let me know until March about a 2-room flat in Žilina under 150 000 €"). This does NOT start watching by itself and takes no e-mail address or other personal data: it returns a consentUrl on www.livinisto.sk that the user must open themselves, enter their own e-mail there and confirm by clicking the link LivinIsto e-mails them. Never ask the user for their e-mail in the conversation and never open the link for them. An unconfirmed draft is deleted after 24 hours. Matching properties are e-mailed to the user and can also be read with intent_list_matches using the returned intentCode — keep it in the conversation. hiddenLimitEur is optional: the most the user would pay (for a rental, per month), stored encrypted and never shown to sellers or returned by any tool; pass it only if the user said it. Matches come from listings LivinIsto aggregates from the Slovak market (its own listings and public listings from Slovak property portals), so they cover only properties listed on LivinIsto (Slovakia only, EUR) and may be incomplete.

{
  "type": "object",
  "properties": {
    "statement": {
      "type": "string",
      "minLength": 2,
      "maxLength": 300,
      "description": "What the property MUST be, as one short Slovak phrase, e.g. \"2-izbový byt Žilina do 150 000 €\" or \"prenájom 1-izbový byt Bratislava do 700 €\"."
    },
    "niceToHave": {
      "description": "Wishes that are not required (never filters), e.g. \"balkón, výťah\".",
      "type": "string",
      "maxLength": 300
    },
    "buyBy": {
      "description": "Date (YYYY-MM-DD) by which the user wants to buy or rent; watching stops after it.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "hiddenLimitEur": {
      "description": "Optional private maximum price in EUR (for a rental, per month); encrypted on receipt and never returned by any tool.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 10000000
    }
  },
  "required": [
    "statement"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "intentCode": {
      "type": "string",
      "description": "Secret code of this intent; use it with intent_get_intent, intent_list_matches and intent_withdraw_intent."
    },
    "status": {
      "type": "string",
      "enum": [
        "awaiting_consent",
        "awaiting_email_confirmation",
        "active",
        "expired",
        "withdrawn"
      ],
      "description": "awaiting_consent = the user has not confirmed on the LivinIsto page yet; awaiting_email_confirmation = the user filled in the page and must click the link in the e-mail; active = LivinIsto is watching; expired = the confirmation link, the buy-by date or the intent's validity ran out; withdrawn = cancelled."
    },
    "consentUrl": {
      "type": "string",
      "description": "Page on www.livinisto.sk where the USER confirms the intent with their own e-mail. Show it unchanged."
    },
    "consentExpiresAt": {
      "type": "string",
      "description": "ISO time after which the unconfirmed draft is deleted."
    },
    "statement": {
      "type": "string"
    },
    "niceToHave": {
      "type": [
        "string",
        "null"
      ]
    },
    "buyBy": {
      "type": [
        "string",
        "null"
      ]
    },
    "hasHiddenLimit": {
      "type": "boolean",
      "description": "Whether a hidden limit was stored. Its value is never returned."
    },
    "understood": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "What LivinIsto will watch for, read from the statement (in Slovak). Tell the person before they confirm."
    },
    "notUnderstood": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Words of the statement that are NOT watched for as a filter. Tell the person."
    }
  },
  "required": [
    "intentCode",
    "status",
    "consentUrl",
    "consentExpiresAt",
    "statement",
    "niceToHave",
    "buyBy",
    "hasHiddenLimit",
    "understood",
    "notUnderstood"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Use this to check whether an intent created with intent_publish_intent is already confirmed by the user and active, waiting, expired or withdrawn. Requires the intentCode; returns the statement and dates only — never the user's e-mail, the hidden limit or any other personal data.

{
  "type": "object",
  "properties": {
    "intentCode": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{32}$",
      "description": "The intentCode returned by intent_publish_intent."
    }
  },
  "required": [
    "intentCode"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "status": {
      "description": "awaiting_consent = the user has not confirmed on the LivinIsto page yet; awaiting_email_confirmation = the user filled in the page and must click the link in the e-mail; active = LivinIsto is watching; expired = the confirmation link, the buy-by date or the intent's validity ran out; withdrawn = cancelled.",
      "type": "string",
      "enum": [
        "awaiting_consent",
        "awaiting_email_confirmation",
        "active",
        "expired",
        "withdrawn"
      ]
    },
    "statement": {
      "type": "string"
    },
    "niceToHave": {
      "type": [
        "string",
        "null"
      ]
    },
    "buyBy": {
      "type": [
        "string",
        "null"
      ]
    },
    "validUntil": {
      "description": "Date (YYYY-MM-DD) until which the intent is watched (before confirmation: until the draft is deleted).",
      "type": "string"
    },
    "activeSince": {
      "type": [
        "string",
        "null"
      ]
    },
    "hasHiddenLimit": {
      "type": "boolean"
    }
  },
  "required": [
    "found"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Use this when the user asks what LivinIsto has found for an intent created with intent_publish_intent. These are the same properties LivinIsto e-mails to the user; this server cannot send messages into the conversation by itself. Requires the intentCode; optional since (ISO time) returns only newer matches. Returns at most 20 newest matches with the price and LivinIsto price verdict (per m², against comparable properties nearby) at the time of the match and a link. Before the user confirms the intent there are no matches. Matches come from listings LivinIsto aggregates from the market, so they cover only properties listed on LivinIsto and may be incomplete; a property may already be sold or rented.

{
  "type": "object",
  "properties": {
    "intentCode": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{32}$",
      "description": "The intentCode returned by intent_publish_intent."
    },
    "since": {
      "description": "Only matches found after this ISO time.",
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    }
  },
  "required": [
    "intentCode"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "status": {
      "description": "awaiting_consent = the user has not confirmed on the LivinIsto page yet; awaiting_email_confirmation = the user filled in the page and must click the link in the e-mail; active = LivinIsto is watching; expired = the confirmation link, the buy-by date or the intent's validity ran out; withdrawn = cancelled.",
      "type": "string",
      "enum": [
        "awaiting_consent",
        "awaiting_email_confirmation",
        "active",
        "expired",
        "withdrawn"
      ]
    },
    "matches": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "propertyId": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "description": "Built from LivinIsto's own fields (type, rooms, place), never the seller's headline."
          },
          "propertyType": {
            "type": "string",
            "enum": [
              "byt",
              "dom",
              "chata",
              "pozemok",
              "apartman"
            ]
          },
          "transaction": {
            "type": "string",
            "enum": [
              "sale",
              "rent"
            ]
          },
          "rooms": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          },
          "roomOnly": {
            "type": "boolean",
            "description": "True when the rent is for a room in a shared flat, not the whole flat."
          },
          "areaM2": {
            "type": [
              "number",
              "null"
            ]
          },
          "landAreaM2": {
            "type": [
              "number",
              "null"
            ]
          },
          "city": {
            "type": [
              "string",
              "null"
            ]
          },
          "cityPart": {
            "type": [
              "string",
              "null"
            ]
          },
          "district": {
            "type": [
              "string",
              "null"
            ]
          },
          "priceEur": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "Asking price today; per month for a rental. Null when the listed number is not the price of the whole property (a share, an auction, a short stay) — check the listing."
          },
          "priceIsMonthly": {
            "type": "boolean"
          },
          "priceEurAtMatch": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          },
          "priceVerdictAtMatch": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "below_market",
                  "around_market",
                  "above_market"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "matchedAt": {
            "type": "string"
          },
          "stillListed": {
            "type": "boolean"
          },
          "url": {
            "type": "string",
            "description": "Link to the property on www.livinisto.sk — show it unchanged."
          }
        },
        "required": [
          "propertyId",
          "title",
          "propertyType",
          "transaction",
          "rooms",
          "roomOnly",
          "areaM2",
          "landAreaM2",
          "city",
          "cityPart",
          "district",
          "priceEur",
          "priceIsMonthly",
          "priceEurAtMatch",
          "priceVerdictAtMatch",
          "matchedAt",
          "stillListed",
          "url"
        ],
        "additionalProperties": false
      }
    },
    "more": {
      "description": "More matches exist than returned; call again with since.",
      "type": "boolean"
    }
  },
  "required": [
    "found"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Use this when the user wants LivinIsto to stop watching for an intent created with intent_publish_intent. Takes effect immediately; nothing more is e-mailed for it. Requires the intentCode.

{
  "type": "object",
  "properties": {
    "intentCode": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{32}$",
      "description": "The intentCode returned by intent_publish_intent."
    }
  },
  "required": [
    "intentCode"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "status": {
      "type": "string",
      "enum": [
        "withdrawn"
      ]
    }
  },
  "required": [
    "found"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}